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.
vb-audit
:
- In the command-line interface, navigate to the folder on your local system containing the
package.json
andGruntfile.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 inpackage.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'