Get Started with the Oracle JET Audit Framework

1 Get Started with the Oracle JET Audit Framework

The Oracle JET Audit Framework (JAF) is a command-line utility and supporting API that allows you to audit JET applications by using a rich set of built-in audit diagnostic rules. The API supports extending JAF with custom audit rules that you write to meet specific diagnostic requirements of your application.

About Auditing Oracle JET Applications

Oracle JET Audit Framework (JAF) is dynamic and performs an audit of Oracle JET project files based on runtime options it finds in a configuration file.

To get started with JAF, the initial creation of the configuration file is automated to help you get up and running quickly. After a default configuration file is created, you have many options to tailor the audit to your project needs.

With Oracle JAF installed, audits that you perform against your JET project run in a command-line interface, similar to the Oracle JET CLI. The installation of JAF provides a lint-style command-line utility named ojaf that audits JET application files (currently HTML, JS, TS, TSX, CSS, and JSON) by applying rules that perform a static analysis from an Oracle JET perspective.

The audit diagnostic messages returned by invocation of the ojaf utility result from built-in rule sets that are specific to the Oracle JET release version of the application. As new versions of Oracle JET are released, you can update JAF and keep current with the latest applicable audit rules. For this reason, you will want to update JAF regularly.

The audit rules that are specific to each version of Oracle JET are called the built-in rules. Additionally, you can configure the audit to run with custom, user-defined rules. Both the built-in rules and rules that you may write yourself, are logically and physically grouped together in a rule pack.

Like an Oracle JET installation, installation of Oracle JAF requires that Node.js is installed as a prerequisite. The ojaf utility will report if the Node.js version does not meet the minimum node version requirement.

Before you run the audit, you use the JET tooling to initialize Oracle JAF and to scaffold a default JAF configuration file, oraclejafconfig.json. You can customize the properties of the Oracle JAF configuration to control many aspects of both the rule set (the set of active rules) and the file set (the set of files to be audited) for a specific audit run:

Any rule may be disabled.
One or more rules may be designated by name to be run and all others excluded.
Rule groups may be specified (for example, only run rules related to HTML).
Rules may selected by severity of the issue they report.
All built-in rules may be suppressed (allowing only user-defined rules to run).
All rules specified in a defined rule pack may be disabled.
The target file set can be defined easily, including by using glob support for both inclusion and overriding exclusion.
Multiple configuration files can created for specific runtime criteria or projects. The configuration files are JSON format, but JavaScript/TypeScript style comments are permitted for documentation purposes. The configuration file to be used can be specified on the command-line.

If the built-in audit rules provided with the JAF installation do not meet all the diagnostic requirements of your application, you can write custom audit rules to extend JAF. You implement user-defined audit rules as JavaScript files. The JAF API allows you to register event listeners and handle the audit context created by JAF on the file set of your JET projects. Custom audit rules can be assembled into distributable rule packs and invoked by developers on any Oracle JET application.

Typical Workflow for Auditing an Oracle JET Application

Understand auditing options for Oracle JET web and hybrid mobile applications.

To audit the source files in an Oracle JET application, refer to the typical workflow described in the following table:

Task	Description	More Information
Initialize the Oracle JET Audit Framework (JAF) and perform an audit dry-run	Create a default `oraclejafconfig.json` file and run a dryrun report to verify the files that will be audited.	Initialize Oracle JAF and Run an Audit
Configure JAF	Edit the `oraclejafconfig.json` file to limit the scope of the audit to the desired file set or rule severity level, for example.	Configure the JET Audit Framework
Run an audit	Report the diagnostic messages discovered by the rule set for a specific Oracle JET version.	Run Audits on Oracle JET Applications
Fine-tune audit results	Hide diagnostic messages emitted by specified rules or comment source code with JAF comment commands to limit the scope.	Fine Tune the Audit
Customize audit reports	Format the optional JSON output of the audit in a custom report.	Work with the Output of Audits

Typical Workflow for Writing Custom Audit Rules

Understand how to interact with the Oracle JAF API and work the various utility libraries to create user-defined, custom audit rules that extend JAF.

To write custom audit rules and assemble your JavaScript implementation files as a rule pack that you can share with JET application developers, refer to the typical workflow described in the following table:

Task	Description	More Information
Understand the JAF concepts for writing custom rules	Learn about the various JAF audit context events and the properties that you can access on the context object passed at runtime to your audit rules by the JAF audit engine.	About the JAF Audit Engine
Understand the custom audit rule implementation	Learn how you can handle the audit context object by registering a listener to respond to context events and learn about the miscellaneous helper functions provided by JAF utility libraries that you can access on the context object.	Understand the Structure of Custom Audit Rules and Reference: Custom Audit Rule Utility Libraries
Understand the requirements to create and to distribute custom rules	Set up a JET development environment to implement your custom rules before you distribute the rules as a rule pack.	Get Started Writing Custom Audit Rules
Write custom rules that audit file data parsed by JAF	Review sample custom (node) rules that show how to audit for data nodes returned on your application's target file set, including HTML, JSON, JavaScript/TypeScript, and CSS files.	Implement Custom Node Rules
Write custom rules that work with the phases of the JAF lifecycle	Review sample custom (hook) rules that show how you can invoke an audit at various stages of the JAF audit lifecycle, such as upon audit startup.	Implement Custom Hook Rules

Install the Oracle JET Audit Framework

Use npm to install the Oracle JET Audit Framework (JAF).

Like an Oracle JET installation, installation of Oracle JAF requires that Node.js is installed as a prerequisite. For additional information, see Install Node.js.
At the command prompt, enter the following command as Administrator on Windows or use sudo on Macintosh and Linux machines:
```
[sudo] npm install -g @oracle/oraclejet-audit
```
It may not be obvious that the installation succeeded. Enter ojaf -v to verify that the installation succeeded. If you do not see the Oracle JAF version, scroll through the install command output to locate the source of the failure.
- If you receive an error that your version of Node.js is outdated, download and install the recommended version.
- If you receive an error related to a network failure, verify that you have set up your proxy correctly if needed.
- If you receive an error that your version of npm is outdated, type the following to update the version: [sudo] npm install -g npm.

Initialize Oracle JAF and Run an Audit

If you have an Oracle JET application you created using the JET command-line interface, then you can auto-configure an audit for the application and run the audit in the command prompt window.

In the JET application, open a command prompt and, from the root directory, use the Oracle JET Audit Framework (JAF) command to initialize a default JAF configuration for the application.

ojaf --init

When you initialize Oracle JAF, the JET tooling scaffolds a default JAF configuration file named oraclejafconfig.json. The tooling creates the JAF configuration file in the root directory and defines the default configuration settings based on the JET application configuration file oraclejetconfig.json, also located in the application root directory.

Before you audit the application for the first time, you can confirm the default configuration for the application files that JAF will audit. This command is called a dry-run because it does not audit the application but confirms the files to be audited based on current JAF configuration settings.

ojaf --dryrun

To perform an audit of your application, enter the command to invoke the JAF audit utility.

ojaf

When you run the audit, 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 and will always use the default JAF configuration for the audit.

On subsequent invocations of ojaf, a check is made to see if the Oracle JET configuration file (oraclejetconfig.json) has changed since the last ojaf invocation. If changes are detected, such as might occur when you migrate your application to a new JET version, then JAF updates certain settings in the JAF configuration file automatically. The configuration property settings that JAF monitors and updates based on JET configuration file changes are:

jetVer specifies the JET version to be audited against.
files specifies the file paths or URLs used to determine the input file set to be audited.
exclude specifies the files paths which should be excluded from the audit.
components specifies paths to folders where user-defined custom web component metadata (component.json) can be found. This provides the ability for rules to inspect the component metadata and to validate custom element attributes.
theme specifies the Oracle theme (redwood, alta, stable, or none) and affects rules that are theme dependent. In particular, the attribute label-edge if not used will have a default value that is dependent on the theme. The Redwood theme is the default if the theme property is not specified, and stable is considered a synonym for redwood.

Note that you may freeze a JAF configuration and prevent further automatic updates by editing the oraclejafconfig.json file and setting the property update as follows.

"ojet": {
           "update": false,
           ...
        }

All other configuration properties remain unchanged, however, you may customize your application audit, by updating the configuration file oraclejafconfig.json in a text editor and adding or amending JAF properties. A full description of the configuration options are found in About the Oracle JAF Configuration File Properties.

Additionally, you can obtain a complete list of ojaf command line flags by entering the following command.

ojaf --help