2 Configure the JET Audit Framework
You can modify some basic settings of the default Oracle JAF configuration to set up an audit for your application.
About the Oracle JAF Configuration
Oracle JET Audit Framework (JAF) relies on the configuration file created by the JET tooling when you invoke the JAF initialization command ojaf --init in a Command Prompt window on the JET application.
The oraclejafconfig.json file that you create when you initialize Oracle JAF the first time defines the properties that you can use to control many aspects of your JET application audit. For example, by configuring the JAF audit, you can perform the following.
-
Specify the JET version when you want to use audit rules that are specific to a JET version. This is configured by default as the JET version of the application to be audited.
-
Specify the file set when you want to exclude application directories and file types. This is configured by default to include all files of the application to be audited.
-
Invoke custom audit rules that are user-defined and assembled as a JAF rule pack for distribution.
-
Prevent specific audit rules from running in the audit or limiting the audit to only rules of a certain severity level.
-
Include the metadata of Oracle JET Web Components to audit the HTML files of your application's custom components.
-
Control the JavaScript/TypeScript source code to audit based on JAF comments that you embed in your source files.
-
Work with the output of the audit to customize the presentation of audit messages or to suppress audit messages.
The properties in the oraclejafconfig.json file configuration settings are up to you to specify. By doing so, you can fine-tune the audit to focus audit results on only the source that you intend. Multiple configuration files can created for specific runtime criteria or projects. The configuration files are JSON format, but JavaScript style comments are permitted for documentation purposes. The configuration file to be used can be specified on the command-line.
Each time you run the audit from a Command Prompt window, Oracle JAF searches the directory in which you initiated the audit for the JAF configuration file oraclejafconfig.json. If no configuration file is found there, then JAF processes only HTML files found in the current directory. In that case, the default JAF configuration settings are used for the audit.
About the Oracle JAF Configuration File Properties
Oracle JET Audit Framework (JAF) configuration file is a JSON format document with properties that define the runtime behavior of the JAF audit.
The oraclejafconfig.json file that you create when you initialize JAF the first time contains the properties that you can use to control many aspects of the JET application audit. The file lets you define the following properties.
| Configuration Property | Description |
|---|---|
| rulePacks | Optional. Specifies sets of user-defined rules to include into an audit. The property specifies the zip files or folders for the rules that make up a custom rule pack. For an example, see Audit with Custom Rule Packs. |
| builtinJetRules | Optional. Default is true. If false, all the built-in JET rules in the internal rule set with prefix JET are disabled. This is a convenience property since it obviates having to specify all the JET rules and individually marking them disabled if only user-defined rules in custom rule packs are to be run. For an example, see Audit with Custom Rule Packs. |
| builtinJetWcRules | Optional. Default is false. If true, all the built-in rules in the internal rule set with prefix JETWC for audits by custom Web Component authors are enabled. This is a convenience property since it obviates having to specify all the JET Web Component rules and individually marking them enabled. For an example, see Audit JET Custom Web Component Projects. |
| ruleMods | Optional. Enables/disables rules and can also override or define any rule's options in any rulePack, such as the built-in JET rules in the internal rulePack JET. Rules may be enabled/disabled by use of the enable/disable properties, whose values are the rule names or group names. The override options are grouped by the configuration property rulePacks sub-property prefix. Each entry is a name/value pair, where the property name is a rule name and the property value object supplies the option(s) for the rule. See JAF configuration property rulePacks. For an example, see Configure Audit Rule Runtime Properties. Note that rules marked with the property $required set to true cannot be disabled via configuration properties.
|
| severity | Optional. Specifies the rule severity levels to which issues will be restricted. If omitted, the default is all (all issues found are reported). The default severity levels accepted are (in descending priority order): blocker, critical, major, minor, info. (If these have been redefined by using the configuration property sevMap, then a redefined severity may also be used here.) For an example, Restrict Audit Rule Severity Level. |
| sevMap | Optional. Allows reassignment of the severity level of any audit rule message from any rule pack. It can also be used to redefine the set of severity levels used by Oracle JAF when security level identifiers other than the default ones are preferred. For an example, Alter the Severity Level of an Audit Rule. |
| groups | Optional. Specifies one or more groups that will be used to form the active rule set. If omitted the default is all. If this property is used, only the rule groups defined in it are active. Note that this property is mutually exclusive with the JAF configuration property ruleNames. For an example, Audit with Specific Rules. |
| defGroups | Optional. Allows custom groups to be defined and used in the JAF configuration property groups definition. For an example, see Audit with Specific Rules. |
| ruleNames | Optional. Specifies the specific rules and, optionally, rule groups that will form the active rule set. This property is mutually exclusive with JAF configuration property groups. If this property is used, only the rules or rule groups defined in it are active. For an example, see Audit with Specific Rules. |
| base | Optional. Specifies the base directory used to resolve any relative file paths found in the JAF configuration file. If omitted, the location of the configuration file is used. The macro $jafcwd may be used, and its value is the directory in which the audit is invoked. For an example, see Configure the Project Scope for the Audit. |
| files | Optional. Specifies an array of directory paths, file paths, or URLs used to determine the input file set to be audited. Globs may be specified in a file path. If any file path is relative, it is considered to be relative to the location specified by the JAF configuration property base. Note that forward slashes may be used to specify file paths regardless of the platform (Microsoft Windows users can avoid using double backslashes, making the file paths more readable). See also the JAF configuration property exclude. For an example, see Configure the Project Scope for the Audit. |
| exclude | Optional. Specifies an array of file paths which should be excluded from the audit. Globs may be specified. If any file path is relative, it is considered to be relative to the JAF configuration property base. Note that forward slashes may be used to specify file paths regardless of the platform (Microsoft Windows users can avoid using double backslashes, making the file paths more readable). For an example, see Configure the Project Scope for the Audit. |
| jetPagesOnly | Optional. If true, this property suppresses auditing of an HTML file if the page does not contain any JET custom elements. Default is false. For an example, see Audit Only HTML Files That Contain Oracle JET Components. |
| theme |
Optional. Specifies the Oracle theme - may be redwood, alta, stable, or none. If the property is omitted, redwood is assumed as the default. Note that Stable is treated as a synonym for Redwood. The theme setting affects rules that are theme dependent. In particular, the attribute |
| format | Optional. Specifies the type of audit output generated. May be prose for standard report style text output, line for a flattened-out text style, or json for JSON output format. If not specified, the default output is prose style. For an example, see Toggle the Default Format of Audit Messages. |
| proseFormat | Optional. If format has been specified as prose, this property defines a custom presentation format (template) for the displayed issues. May use a list of template tokens that may be specified in any order. For examples, see Customize the Presentation of the Audit Messages. |
| lineFormat | Optional. If JAF configuration property format has been specified as line, this property defines a custom presentation format (template) for the displayed issue. May use a list of template tokens that may be specified in any order. This property is useful for reconfiguring the output when used in a Microsoft Visual Code terminal window. For an example, see Customize the Presentation of the Audit Messages. |
| outPath | Optional. Specifies the file path to which the audit output (specified as either prose or JSON) will be written. If the file path is relative, it is considered to be relative to the location specified by the JAF configuration property base. If omitted, the output is written to stdout. For an example, see Output Audit Messages in JSON Format. |
| tabs | Optional. Specifies the tab settings to be used when reporting line/column issues found during an audit. If omitted, the default assumes that each tab character represents 4 spaces. For an example, see Adjust the Tab Value Used to Report Line and Column Issues. |
| messages | Optional. Controls which messages are reported. It can specify the message IDs to reject, or alternatively those to be accepted only. For an example, see Suppress Audit Messages. |
| markupOptions | Optional. This property can be used to modify the reporting of links found in markup files. If true is specified (or the option is omitted), ojaf looks for URL-like text that has not been marked-up as a link. This can be useful when analyzing .md text for compliance. It is possible for false positives to be generated, since text such as foo.html or foo.in are considered links, and the rule should inspect the link for validity. If false is specified, links not formally declared using markup syntax will not be reported as links.
|
| typescript | Optional. This property must be set to true to enable the auditing of TSX files. Otherwise, the files will be skipped. For more information, see Audit JET Web Component Projects Containing VComponents. |
| addFileList | Optional. If set to true, and the JAF configuration property format is set to json, this property causes the audited file set to appear in an additional fileset section (as an array of full file path strings) of the JSON output. This can be useful when creating custom reports from the audit's output JSON, since it allows access to the full file set that was audited. For an example, see Output Audit Messages in JSON Format. |
| title | Optional. Specifies one or more strings used to customize a title for an audit report. The strings will be displayed when the audit is run with prose format, or the strings will be inserted into JSON output for the audit with JSON format. Macros are available to insert values such as the Oracle JET version, or date and time into the title strings. For an example, see Format a Title for the Audit Report. |
| jetVer | Optional. Specifies the Oracle JET version to be audited against. Can be a full or partial semantic version (semver) with the format "[x [.y[. z]]", such as "8.2.0" (a quoted string). For an example, see Audit with Specific JET and ECMA Script Versions.
|
| components | Optional. Specifies paths to folders where metadata in the component.json file of user-defined Oracle JET Web Components can be found. This provides the ability for rules to inspect the Web Component metadata to validate custom element attributes. (Note that this is for user-defined Web Components only; it is not used for Oracle JET HTML components.) For an example, see Audit JET Custom Web Component Usages.
|
| componentOptions | Optional. Specifies controlling options for the associated components and componentUrls properties. If the neither property is specified, componentOptions is ignored. This can be used to disable the application of metadata schema extracted by JAF from component.json files and used to validate web components. This may be useful to prevent JAF-INIT messages from being displayed if the schema pass identifies component metadata issues. For an example, see Audit JET Custom Web Component Usages.
|
| nameSpaces | Optional. Specifies the list of namespaces that are not allocated by Oracle and that are user defined to allow JAF to successfully audit user-defined custom Web Components. For an example, see Audit JET Custom Web Component Usages. |
| stylesets | Optional. Specifies an allowed list of valid user-defined Web Component style names. This permits Oracle JAF to report on invalid style names in HTML and CSS and to distinguish those styles from valid JET core styles. For an example, see Audit CSS Styles and Web Components Styles. |
| comments | Optional. If true, this property enables JavaScript commenting with JAF comment commands when you want to limit audit scope at the level of the source code. Default value is false. For an example, see Comment Source Code for Fine-Grained Audit Control. |
| followLinks | Optional. If true, <link> and <script> elements in HTML that refer to external stylesheet and JavaScript files are followed, and the files are audited. Specify false to prevent externally linked files from being audited. The default value if not specified is true. For an example, see Suppress Auditing Linked Content.
|
| ecmaVer | Optional. Specifies the ECMA script version for JavaScript auditing. May be 5, 6, 7, 8, 9, 10, or 11 (a number, without quotes) or the corresponding ES version year (for example 2015, 2016, 2017, and so on). Support for ES version 11 (2020) requires JAF version 2.9.20 or later. If omitted, the default is ES version 11 (2020) as of Oracle JAF version 2.9.48 and ES version 10 (2019) is the default starting in Oracle JAF version 2.9.11. For an example, see Audit with Specific JET and ECMA Script Versions. |
| tempDir | Optional. Specifies the file path to the directory in which Oracle JAF should create its internal work folder (jaftmp@). Intermediate directories are created if necessary. If omitted, the default value is the current working directory. This can be used when the default value cannot be used due to permission restrictions on file creation. The path can be absolute or relative. If relative, the path is considered to be relative to the current working directory
|
| ruleDescriptions | Optional. This property takes the following values: none, all, short, or long, and causes an additional descriptions section to appear in the output JSON. This property applies only if JSON output format has been specified (using JAF configuration property "format" : "json"). For an example, see Output Audit Messages in JSON Format. |
| userDefs |
Optional. Specifies a user-defined property (typically an object) that is passed in The userDefs property should be limited to specific, simple cases only. Generally, and especially when multiple non-JET rulepacks are used, run-time data should be maintained in a rulepack extension (see startupRP and closedownRP in Implement Custom Rules Using the Audit Lifecycle. |
| options | Optional. Defines miscellaneous runtime options. The property can be used to reduce clutter on the command line when running an audit using the Command Line Interface. For an example, see Audit the Application with Predefined Runtime Options. |
| extends | Optional. Specify a configuration file whose properties are to be inherited. If the path is relative, it is resolved via the base property or the location of the configuration file in which it is specified. A configuration may also extend a JAF standard profile, a list of which can be viewed by using the command ojaf -prof. For an example, see Specify Configuration Inheritance.
|
| extendOptions | Optional. Specify one or more properties that should not be inherited from the configuration specified by the property extends. For an example, see Specify Configuration Inheritance. |
| @include() | Optional. This directive allows a configuration file to include text from another file. This can be useful when the application file set to be audited is very large, and permits the audit parameters to be separated from the file list. The directive specifies the path to a text file which is be included in the configuration in place of the directive line. The included files may also use @include(). For an example, see Audit CSS Styles and Web Components Styles. |
Configure the Project Scope for the Audit
Use the optional Oracle JAF configuration properties files and excludes to limit audit scope based on the file set to audit. If the properties are omitted, the default file set is based on the JET application configuration and includes by default all HTML files in the root directory.
/* Comments are supported */
{
"files" : [ <path>/*.html, <path_to_specific_file>, ...] // comments are supported
}{
"files" : ["D:/apps/components/public_html/js/views/**/*.html"]
}{
"base" : ["./some/filepath"],
"files" : ["./html/*.html"],
"exclude" : ["./html/*test[1-9].html"],
...
}The top-level base property can also be specified using the macro value $jafcwd. This macro takes on the value of the directory in which the audit was invoked.
Specify Configuration Inheritance
Use the extends configuration property to allow parent configurations to inherit properties and property values from child configurations, and use the extendOptions property to define the actions taken during inheritance.
When multiple configurations need to be maintained by an organization that has different auditing requirements, some aspects of the configurations may be common and need to be repeated. To avoid duplication and related synchronization issues, JAF permits a hierarchical structure to be used, where one configuration can inherit properties or property values from another. This is performed by use of the extends property.
Primary config_1
--------------
{ "extends" : "/path/to/config_2.json"
. . .
}
Child config_2
-------------
{ "extends" : "/path/to/config_3.json"
. . .
}
Child config_3
-------------
{ . . . // no "extends"
}In the above example, the final active configuration is a modified copy of the primary configuration, config_1, and is the result of a merge of the child configurations and the primary configuration. The merge sequence starts at the last child, config_3, and moves upwards to config_1. The sequence is as follows:
- config_3 is a child configuration and is thus merged into its direct parent, config_2.
- The result of that merge is a child configuration to its direct parent, config_1 (the primary configuration), and is merged into config_1.
- A copy of the updated config_1 becomes the final active configuration for the audit.
Note that circular references are not permitted and are detected by the command ojaf, resulting in termination of the audit.
If a configuration uses relative file references, these are resolved during the merge with its direct parent. This resolution is performed in the standard JAF documented sequence:
- If no base property is declared, the relative paths are considered relative to the location of their containing configuration file.
- If a base property is declared, the relative paths are considered relative to the base property path.
- If the base property is itself relative, the base property is considered relative to the location of the containing configuration file.
When two configurations are merged, a parent property either takes precedence over the child property, or the child property values are merged into the parent property.
- If the child property does not exist in the parent configuration, the property is transferred directly to the parent, unless this is overridden by the optional property extendOptions.
- If the parent property exists, but the child property cannot be merged or is a single value (such as severity, theme, and jetver), the parent property takes precedence.
- During an inheritance merge, the base and extends properties of a child are not inherited by the parent.
- If a property is considered inheritable, the action taken depends on the specific property. As illustrated in the following example, the options property result is a direct merge, assuming that Config2 extends Config1:
Active (final) Config <--- Config2 <--- Config1
--------------------- ------------------ --------------------
"options" : { options" : { "options" : {
"msgid" : true, "msgid" : true, "msgid" : true,
"color" : false, "color" : false "color" : true,
"verbose" : true "verbose" : true
} } }Optionally, the action taken during inheritance can be controlled by the property extendOptions. This property is examined only for a parent configuration and is never inherited. extendOptions declares the action that applies to each property in the direct child that it refers to.
"extendOptions" : {
<property> : "ignore" ,
. . .
}A property that is declared in a child configuration can be prevented from propagating into the parent configuration. For example, a parent configuration can specify that the child configuration property ruleDescriptions should be ignored.
"extendOptions" : {
"ruleDescriptions" : "ignore" ,
. . .
}The configuration properties files and exclude together define the scope of the fileset that will be audited. As noted in the table below, these properties are inheritable and are merged by default (unless vetoed by extendOptions). The action taken for these two properties is as follows:
- The parent and child files and exclude properties are examined for relative paths, which are resolved.
- If a files property contains files or base objects, they are expanded and resolved.
- The resulting flattened/resolved arrays (with duplicates removed) are merged, and the result is their union.
| Inherited Properties Merged By Default | Properties Never Inherited or Propagated |
| components, componentUrls, exclude, files, groups, messages, nameSpaces, options, ruleMods, ruleNames, rulePacks, sevMap | base, extends, tokens |
Use the command-line flag -dac (display active configuration) to evaluate the result of inheritance without actually running the audit life-cycle.
Inheritance from built-in standard profiles is available when using the extends property while setting up a configuration. JAF provides some standard profiles to enable/disable standard sets of rules and, in some cases, elevate the severity of errors. You can view the available profiles by using the -prof command option (see Audit the Application Using the Command Line).
$ ojaf -prof
--- JAF Profiles ---
* best-practice
JAF Standard profile configuration enforcing best practice for JET Application Development.
* redwood-strict (extends 'best-practice')
JAF Standard profile configuration for strict audit checking of Redwood applications.To use one of these profiles as a base for your own configuration, use the extends option but specify the name of the profile required rather than a path to a specific configuration JSON file.
{
"extends": {"profile":"redwood-strict"}
"jetVer": "11.0.0",
"ecmaVer":"2019",
"base": "$jafcwd",
"files": [
"./src/**/*.html",
"./src/**/*.js",
"./src/**/*.css",
"./src/**/component.json"
],
...
}For example, in the case of the profile redwood-strict above, the severity of rule oj-html-alta-deprecated is upgraded to blocker because a Redwood application should not use the Alta theme. You can view specific profiles by using ojaf -prof <profile name> (e.g.,, ojaf -prof best-practice). To view the full set of rules that are enabled and their severity, you can use the -dac command option to display the final active configuration that has been evaluated.
Configure Audit Rule Runtime Properties
Use the Oracle JAF configuration property ruleMods to change the auditing behavior of any audit rule.
"ruleMods" : {
"ABCD": {
"my-rule" : {"pageType": "index", "companyCode": "acd", // user rule with arbitrary runtime properties
"isMulti": true, . . .}
}
}| Rule Property | Description |
|---|---|
| enabled | Enables or disables the audit rule. All rules are enabled by default. See example below. |
| severity | Classifies the severity level of the audit rule. You may change the level to info, minor, major, critical (default), blocker when you want to restrict the audit by rule severity level. Note that these severity levels may be replaced by user-defined severity levels as required by your organization. See also Alter the Severity Level of an Audit Rule. |
| status | Associates a development status with the audit rule. You may change the status to production, alpha, beta, or deprecated. |
| filetype |
Specify the file types for which the audit rule will be invoked. You may change the file type to html and/or css, and/or js and/or json. For example:
or
The filetype property is ignored by hook rules declared for startup/closedown phases, since these are not file related. |
| group | Specify the group or groups to which the audit rule is assigned. You may change the rule group when you want to restrict the audit by rule group. For example:
|
| jetver | Specifies the Oracle JET release version or versions to be audited against. You may change the JET release version required to invoke the rule. The format supports semantic versioning, as used in programs like npm. For example: |
| issueTag |
Defines a string which is passed through to the output JSON, or custom proseFormat / lineFormat, whenever the rule to which it is applied fires an audit issue. The string may be applied to any rulepack and rule. It is not inspected by JAF,
and could, for example be formatted as a colon-separated key:value pair. When the
rule to which it is applied fires, the issueTag property is passed through
to the output. For JSON formatted output, it appears as Issue property
issueTag, and similarly in the Issue object for API/AMD modes. For CLI
default output, the issueTag string is not displayed, unless a custom
format is defined via the configuration proseFormat or lineFormat
properties. In this case the issueTag string is available as substitution
|
"ruleMods" : {
"enable" : [ "rulename1", "rulename2, "groupname1"], // can specify rule names and group names
"disable" : [ "rulename3", "rulename4, "groupname2" ]
}Note that since a group name represents a set of rules, group names can be declared in addition to rule names.
If both enable and disable properties are declared, the enable set is processed first, followed by the disable set. If a conflict is found, a notification message is generated and the run abandoned.
Configurable rules inspect the rule options at start-up time and configure themselves accordingly. Redefine rule options for these rules, such as their severity level and enabled status, by editing the oraclejafconfig.json file ruleMods property. Each rule option entry is a name/value pair, where the property name is a rule name and the property value object supplies the option(s) for the rule. For instance, to set a desired value for the severity sub-property and enabled sub-property:
"ruleMods" : {
"JET" : {
"oj-html-ojattr" : {"severity": "critical"},
"oj-html-lib" : {"enabled": "false"}
}
}This example illustrates that any rule option can be set, where the built-in rule oj-html-ojattr has been overridden as severity level critical and the rule oj-html-lib has been disabled. However, it is recommended that those particular options are set through the configuration sevMap and ruleMods enable/disable properties.