Using the Veracode Greenlight Continuous Integration Tool

Veracode Greenlight

The Veracode Greenlight continuous integration (CI) tool scans Git commits for amended and scannable Java source files, and submits them to Veracode Greenlight for analysis.

Prerequisites

To be able to use the Greenlight CI tool, the source files must be Java 8 format and the project must successfully build, meaning that you have run gradle build or maven verify. In addition, the build outputs must be available to Greenlight before attempting to scan. In addition, your Veracode Greenlight user account must have Veracode API credentials to be able to use the Greenlight API.

Download and Pipeline Usage

The Veracode Greenlight CI tool is available for you to download at https://downloads.veracode.com/securityscan/gl-scanner-java-LATEST.zip. This ZIP file contains a readme file and a single JAR file, gl-scanner-java.jar, which contains all the dependency files.

After downloading the ZIP file, add a job to your CI/CD pipeline after a build job. Use this new job to download and unzip the CI tool, and then run the JAR with the command java -jar. In general, this job submits the files to Greenlight for analysis. If any flaws are found, the tool returns a status code that indicates how many flaws are found, and then fails the pipeline job. The parameters you pass to the CI tool determine the configuration of the scan and the output.

Command-line Parameters

If you enter only the mandatory Veracode API credentials and leave all the other parameter settings as the defaults, the CI tool only:

  • Scans the last Git commit (HEAD) and looks for changed files in the Gradle default main Java source (src/main/java) and build (build/classes/java/main) directories.
  • Reports flaw counts for flaws of severity 1 or higher.
  • Displays a summary of the results to the console.
  • Writes the results JSON file to storage, where the pipeline can then apply other actions to it.
The following is the usage of the command-line parameters:
java -jar gl-scanner-java.jar
[-h] [-v] -i API_ID -k API_SECRET_KEY [-g GIT_DIR] [-s SOURCE_DIR] [-x EXCLUDE] [-b BUILD_DIR]
[-p PROJECT_NAME] [-u PROJECT_URL] [-r PROJECT_REF] [-ic ISSUE_COUNTS] [-cb CALLBACK_URL]
[-id {true,false}] [-bp {true,false}] [-sd {true,false}] [-so {true,false}] [-sf SUMMARY_OUTPUT_FILE]
[-jd {true,false}] [-jo {true,false}] [-jf JSON_OUTPUT_FILE] [-sj {true,false}] [-c COMMIT_HASH | -j JAR |
-a {true,false}]

Common Parameter Usage

The following parameters are the ones most commonly used:
  • --project_[name|url|dir: to append the project name to the results JSON and summary outputs for easy organization and for use by the Greenlight usage reports.
  • --source_dir and --build_dir: comma-separated lists of directories in which to look for changed files, and to find the build outputs for those files, respectively. Both directories are relative to the Git directory, which defaults to the current directory.
  • --issue_counts=2:0,1:0,0:0: to only fail the build if severity 3 or higher flaws are found.
  • --callback_url: to use in asynchronous CI/CD pipelines by defining a URL where the results JSON is posted upon completion of the Greenlight scan.

Refer to the list of optional parameters to pass other information to the CI tool using command-line arguments, such as:

  • The Git commit to scan
  • Excluded source directories
  • Results customization, such as ignore issues of certain severities and display or hide details in the results summary
  • Results output, to show both summary and results JSON file on the console, saved to disk, or disable completely.

Status Codes

The following are the status codes returned by the CI tool:

  • If the tool finds no changed or scannable files, the tool returns a status code of 0, and the pipeline job passes.
  • If the tool finds changed and scannable files, it submits these files to Greenlight for scanning, which results in the following codes:
    • If the Greenlight scan does not result in any findings, the tool returns a status code of 0 and the pipeline job passes.
    • If the scan results in findings, the tool returns a status code equal to the number of flaws found (up to 200), and the pipeline job fails.
    • If the scan fails to run due to network issues, invalid API credentials, or other reasons, the tool returns -1 and the pipeline job fails.