Audit Your Application Using the vb-audit Grunt Task

Visual Builder provides an NPM package (grunt-vb-audit) that includes the vb-audit Grunt task that you can use to audit your visual applications.

The root folder of your visual application includes two resource files that Grunt uses when it audits applications: Gruntfile.js and package.json:

File	Description
`Gruntfile.js`	Contains a basic Grunt script that you can modify to add custom audit tasks, and to configure built-in tasks.
`package.json`	Declares the dependency and specifies the URL reference to the `grunt-vb-audit` NPM package that provides the Grunt task to audit visual applications. Visual Builder automatically updates the package version and URL whenever Oracle publishes a new version of the package.

As with the Grunt tasks that you use to build and deploy your visual application, you need to install Node.js and its package manager (npm) on your local system. You also need to save the sources for the visual application on your local system.

To audit your application using vb-audit:

In the command-line interface, navigate to the folder on your local system containing the package.json and Gruntfile.js files.
Enter npm install to retrieve the node dependencies required to audit the application.
The install command retrieves the grunt-vb-audit NPM package defined in package.json.

Enter grunt vb-audit in the command-line interface to audit your application. The following illustrative example shows how you execute this task.

# Audit application sources
./node_modules/.bin/grunt vb-audit \
--url=<https://Visual-Builder-runtime-instance-url/ic/builder/> \
--username=<Visual-Builder-runtime-username> \
--password=<Visual-Builder-runtime-password> \
--id=<your visual app ID> \
--ver=<your visual app version>

You can omit the task parameters (URL, username, and so on) if the visual application that you audit does not include modules that require a server connection, such as business objects, for the audit to complete. If you do not specify values for the task parameters when a server connection is required, error messages appear in the command-line interface and the corresponding modules fail the audit.

By default, vb-audit audits all files in your application according to the following glob patterns:

[
    '**/*',
    // Ignore npm directories during audit
    '!node/**',
    '!**/node_modules/**',
]

You can override the files to audit with your own glob patterns. The exclusion patterns in the default glob pattern are appended to the glob patterns that you supply.

Configure Audit Options in Gruntfile.js

You can specify server connection properties and vb-audit properties in your visual application's Gruntfile.js file.

The following example shows available options.

grunt.initConfig({
    vb: {
        url: '<VB-instance-url>',
        id: <your visual app ID>,
        ver: <your visual app version>,
        username: <username>,
        password: <password>,  // This is not encrypted
    },
    'vb-audit': {
        options: {
            config: {
                auditors: {
                    // Disable specific auditors
                    'lcm.VirtualRolesAuditor': { // Requires backend
                        enabled: false,
                    },
                    'components.InstalledComponentsAuditor': { // Requires backend
                        enabled: false,
                    },
                    'serviceConnectionAuditor': { // Requires backend
                        enabled: false,
                    },
                    'deploymentProfileAuditor': { // Requires backend
                        enabled: false,
                    },
                },
            },
            files: [ // Globbing patterns to use for this application
                '*',
                'process/**',
                'services/**',
                'settings/**',
                'webApps/**',
                '!**/package-lock.json',
            ],
            processResults: (results) => { // Supply an alternate results processor
                grunt.log.writeln(`Processed ${results.auditedResourceCount} files`);
            },
            outputFile: 'auditoutput.txt', // Output file to receive the audit results (e.g. auditoutput.txt, auditoutput.csv)
        },
    },
});

The entries in 'vb-audit': { options: { config: { are passed to the audit system and override or augment the options that you set in your visual application's settings/audit.json file if you configured options in the latter file using Visual Builder’s Audits feature.

For output, you can specify processResults or outputFile. If you specify neither, vb-audit writes the output to the command-line interface. Note that the example Gruntfile.js shown above displays both options, as it is an illustrative example of available options. Omit the option (processResults or outputFile) that you do not want to use, or omit both options if you want to write output to the command-line interface.

The results parameter for processResults has the following format:

{
    auditedResourceCount, <number of resources audited>
    totalResourceCount, <number of resources checked (some resources may not have auditors)>
    issues[{
        ruleId, // String id of the rule
        severity, // ['error' | 'warning' | 'info' | 'todo']
        message, // String message
        filePath, // resource's file path
        location: {
            line,
            col,
            endLine,
            endCol,
            length,
        },
    }]
}

You can specify target-based options in Gruntfile.js that override or augment your standard options. The following example audits the modules in the webApps directory:

grunt.initConfig({
    vb: {
        ...
    },
    'vb-audit': {
        options: {
            ...
        },
 
        webApps: { // target to audit the modules in the webApps directory
            files: [
                'webApps/**'
            ],
        },
    },
});

To audit the webApps target, run the vb-audit task and specify the target:

./node_modules/.bin/grunt vb-audit:webApps

Note:

grunt.config.merge merges the target options, such as webApps in our previous example, into the vb-audit options. It merges array and object properties recursively. If, for example, options defines a files array with 5 elements and you provide a target options with a files array that has 2 elements, the first 2 elements in the options files array will be overwritten and the remaining 3 elements remain unchanged.

A difference between the files option in the Gruntfile.js file and the paths/exclude option in your settings/audit.json file is that the Gruntfile.js files option assembles the set of files that vb-audit sends to the audit system, whereas the audit.json patterns are ignored by the audit system. In particular, if you supply a files option in your Gruntfile.js, you need to have an exclusion pattern for something like node_modules, as processing the thousands of files under node_modules can be time consuming. This exclusion pattern is included in the default configuration.

Override Configuration Options in Gruntfile.js

You can override the Gruntfile.js configuration options for vb-audit by specifying properties on the command-line interface.

The following example shows available options.

./node_modules/.bin/grunt vb-audit \
    --audit.files='webApps/**' \
    --audit.disabledauditors='lcm.VirtualRolesAuditor,components.InstalledComponentsAuditor' \
    --audit.outputfile='auditoutput.txt'