Enable OIS Scans

Read the OIS Scanning Wiki page for more information about this topic, including how-to guides and presentations.

Configuration

Options for enabling and configuring the new integrated OIS Scan Tools have been introduced in Jenkins Shared Library.

Enabling

Currently, by default, OIS scanning is enabled for all builds*. However, if you wish to limit its execution, there are several options:

Environment-global Flag

enableOisScan: false

Override the default global enableOisScan: true value to false. This disables automatic OIS scans for every build in Sandbox and Staging, but still allows them to be run manually by toggling the RUN_OIS_SCAN_ONLY build parameter when running a job.

Regex-specified Branches

Example

branchesOisScanRegex: '^(?i)Release/.*' # matches '(r|R)elease/1.0', etc.

Override the default global branchesOisScanRegex: '.*' value to set to a regular expression, which when a branch name matches, will enable OIS scanning for that branch. Once again, even if a branch is not matched and enabled, it is able to be scanned by toggling the RUN_OIS_SCAN_ONLY parameter.

Defaults for enabling OIS scans are currently set to apply to all branches in all environments (except Production) so that any OIS Scan-related issues can be found as early as possible.

However, this will at some point change to be more narrowly-scoped so that only the main and Release branches are OIS Scan-enabled by default.

Configuring CodeQL

By default, CodeQL is configured to trace the normal build of the project, which requires it to be initialized prior to the build command execution. In the case of standard Maven Java builds, the command run is mvn install which compiles both "production" and test classes.

Since CodeQL does not provide a way to exclude test classes, all code, including test classes, will be scanned and possibly generate false positives (since test classes are not included in deployed applications and should be ignored).

In order to prevent test classes from being scanned and reported, a jenkins.yaml option to "defer" CodeQL initialization until after the main build is available. When enabled, a second specialized build is executed which skips tests and test execution.

Following are the default values for these options:

deferCodeQLInit: false (1)
buildCommandForCodeQL: 'mvn clean install --batch-mode -Dmaven.test.skip -Pskip-all-generation -Dhelm.skip -Ddocker.skip -Djib.skip -Djacoco.skip=true -Djacoco.dump.skip=true' (2)

staging: # staging/sqa build environment overrides
  # ...
  deferCodeQLInit: true (3)

1	Disabled by default: uses standard build command to trace code
2	Maven command specific for the CodeQL trace that skips compilation and execution of tests, file generation, image creation, code coverage, etc.
3	In the Staging environment, `deferCodeQLInit` is enabled, effectively excluding tests for the CodeQL trace during the additional second build, and uses the command specified in `buildCommandForCodeQL`

Additional Files

As noted in the OIS Scanning Wiki page, in order to fully enable this feature into the (Staging/SQA) build, add the following emass.json file to a directory named .github in the base directory of the project and commit to the Git repository:

.github/emass.json

{
"systemID": 1008,
"systemName": "VAEC Mobile Application Platform (Cloud) Assessing",
"systemOwnerName": "Daryl Kling",
"systemOwnerEmail": "Daryl.kling@va.gov"
}