Using the Veracode Greenlight Continuous Integration Tool

Veracode Greenlight

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


To be able to use the Greenlight CI tool, Java projects must successfully build, meaning that you have run gradle build or maven verify, and the build outputs must be available to Greenlight before attempting to scan. Greenlight can scan specific types of JavaScript files, however, you must use the Greenlight CI tool twice to scan Java and JavaScript files separately.

In addition, your Veracode Greenlight user account must have Veracode API credentials to be able to use the Greenlight API.

Multi-Commit Scanning

By default, the Greenlight CI tool only looks at the last commit. If you are pushing changes to your CI system for each commit, this action captures all changes. However, many developers make several commits, test them locally, and then push the set of commits to the CI system all at the same time. To see the changes in a specific set of commits, Greenlight has to find a previous commit against which it can perform the comparison. You can query the CI system for a commit that was in a previous successful pipeline and provide this commit hash to the Greenlight CI tool.

Download and Pipeline Usage

The Veracode Greenlight CI tool is available for you to download at 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 findings are found, the tool returns a status code that indicates how many findings 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 finding counts for findings 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]
[-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}]
Note: When running the tool on JVM 9+, you may need to add --add-modules java.xml.bind to the java command, before the -jar option.

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 Greenlight looks for changed files and the build outputs for those files. For Java these are CLASS files, and for JavaScript they are not required. Both directories are relative to the Git directory, which defaults to the current working directory.
  • --issue_counts=2:0,1:0,0:0: to only fail the build if severity 3 or higher findings 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 in command-line arguments to pass additional information to the CI tool. Examples of additional information include:

  • The Git commit to scan.
  • Source and build directories. For Java, these directories store the JAVA and CLASS files. These directories are scanned recursively, therefore, you must specify them at the top of the package hierarchy. For JavaScript, the build directory is not needed or used.
  • Excluded source directories.
  • Scan language, either Java (submitting the CLASS files for analysis) or JavaScript (submitting the source files for analysis).
  • Results customization information, such as ignore issues of certain severities and display or hide details in the results summary.
  • Results output, whether to show both summary and results JSON file on the console, save the results to disk, or disable output completely.

The available options also include the ability to scan arbitrary JARs (smaller than the Greenlight API size limit of 1 MB), and to analyze any existing results JSON file. These options are less useful in a CI/CD pipeline, but are useful during development and are there to provide flexibility.

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 findings 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.