Skip to main content

Veracode Pipeline Scan

Pipeline Scan embeds Veracode Static Analysis directly into your development tools and workflows. Scan code in your IDEs, SCM repositories, and CI/CD pipelines.

To automate application packaging, use or integrate auto-packaging. To automate resolving security findings found in your applications, use or integrate Veracode Fix.

Pipeline Scan is not connected to the Veracode Platform, so it doesn't support certain features, such as flaw mitigations or flaw matching. If you require these features, use Upload and Scan.

How does Pipeline Scan work?​

  • Uploads a packaged artifact of your application code to the Static Analysis Engine.
  • Performs a prescan verification of your code.
  • Performs a Static Analysis to detect security findings in source code.
  • Compares the results to the results in a baseline file of known findings to identify new findings.
  • Analyzes the results of your code against security policies to assess the application's compliance with your organization's security requirements.
  • Provides scan results that you can review in your development tools and resolve automatically using Veracode Fix.

The following example shows an initial Pipeline Scan that creates a baseline file of known findings followed by additional scans that run iteratively against the baseline. The iterative scanning approach enables you to gradually identify and resolve new findings until those new findings no longer appear in the scan results.

Create a baseline file and run Pipeline Scans against the baseline

How can I use Pipeline Scan?​

Run scans locally or in your pipelines.

Pipeline Scan is integrated in the following products.

Supported languages​

Pipeline Scan supports several languages and frameworks

Prerequisites​

Your environment must meet these specific prerequisites before you can successfully upload your packaged application to the Veracode Platform and run Pipeline Scans:

  • An active Veracode Static Analysis license.

  • One of the following Veracode accounts:

    • A human user account with the Security Lead, Creator, or Submitter user role.

    • An API service account with the Upload and Scan API or Upload API - Submit Only API role.

      note

      One Veracode user can start a maximum of six pipeline scans per minute. Users who exceed this limit will see HTTP error 429.

  • You have generated API credentials. You can provide your credentials with the command parameters or with an API credentials file.

  • Enable port 443 in the environments you run Pipeline Scans. The Pipeline Scan uses the Pipeline Scan REST APIs, which use the standard HTTPS port 443.

  • You have ensured that all required Veracode IP addresses for the Veracode APIs and integrations are on the allowlist for your organization. Pipeline Scan uses these addresses to authenticate with Veracode. To update your allowlist, you might need to contact your IT team.

  • You have compiled and packaged your application source files according to the packaging requirements.

  • You have installed Java 8 or later.

  • You have access to a development or test pipeline to which you can add the Pipeline Scan. If you do not have access to a pipeline, you can try running the Pipeline Scan from the command line.

    note

    Each pipeline scan is limited to a maximum scan time of 60 minutes.

  • The application you want to scan:

    • Builds successfully.

    • Does not exceed the total file size limit of 200 MB.

    • Meets the packaging requirements for the supported languages

      note

      You cannot use the Pipeline Scan if the source-code language for your application is not supported.

  • If you are using authenticated HTTPS proxy connections, ensure you have configured the proxy settings using this format:

    java -Dhttps.proxyHost={myproxy} -Dhttps.proxyPort={myport} -Dhttps.proxyUser={myuser} -Dhttps.proxyPassword={mypass}

About Pipeline Scan baseline files​

The Pipeline Scan provides the option to set a baseline of known security findings using the Static Analysis results from a Pipeline Scan of an application. By default, each scan saves its results to a results.json file, and you can use this file as a baseline of findings for that application.

In your Pipeline Scan configuration, set the --baseline_file parameter to the name of your results.json. You can safely rename results.json to something else, such as baseline.json.

To identify new findings, the Pipeline Scan compares the current scan results with those listed in the baseline file. It ignores the baseline findings during the scan and only uses them to flag new issues.

For a CI/CD workflow, you can decide whether any new findings outside your baseline are important enough to "break the build". Set the --fail_on_severity parameter to fail the build based on the severity of the findings. Then, your team can determine a mitigation strategy for addressing these findings before moving the code to the next phase in your development pipeline.

You can only create a baseline file using the Pipeline Scan—not through the Veracode Platform. For examples of how to create a baseline file using the veracode static scan command, see the CLI reference.

Use Pipeline Scan to run Veracode Static Analysis scans locally, in your development pipelines, or using Veracode products that support it.

Obtain the Pipeline Scan files​

You can obtain the latest version of the Pipeline Scan as a ZIP archive from Veracode or as a container image from Docker Hub.

The ZIP archive contains the pipeline-scan.jar, which includes all dependencies except the required Java 8 compatible JRE, and a README with detailed code examples. You add the full path to pipeline-scan.jar in your pipeline scripts for running a Pipeline Scan. The provided script examples include steps to both download and extract the ZIP as part of the Pipeline Scan job.

To complete this task:

  1. Select from the following locations.

  2. If you downloaded the ZIP archive, extract the contents to a local directory.

Scan from the command line​

You can run a few Pipeline Scan commands at a local console, outside a development pipeline, to get started with running a scan and viewing scan results without the need for a test or production pipeline. You can also use the command line for debugging.

Before you begin:

Before running a Pipeline Scan, ensure you meet the prerequisites.

This is an optional procedure that steps you through running a few Pipeline Scan commands from the command line using different command parameters for generating scan results, creating a custom baseline file, and running a Pipeline Scan against that baseline file.

If you want to add a Pipeline Scan to your development pipeline, you can skip this procedure and go to Run a Pipeline Scan in a pipeline. You can also run and manage scans using the Pipeline Scan API.

A Veracode account is limited to six Pipeline Scans per 60 seconds, and each scan is limited to a maximum scan time of 60 minutes.

The example Java application is a WAR file named verademo.war, which you can download from the Veracode GitHub repository. You can also use any application that meets the prerequisites.

To complete this task:

  1. Obtain the Pipeline Scan files.

  2. To view all scan results for an application, run:

    java -jar pipeline-scan.jar --file verademo.war

    Each scan returns a status code.

  3. To include additional details about each finding in the scan results, run:

    java -jar pipeline-scan.jar --file verademo.war -id true

  4. To save the scan results to a JSON file with a custom filename, run:

    java -jar pipeline-scan.jar --file verademo.war -jf verademo_results.json

    By default, Pipeline Scan saves the scan results to a results.json file in the local directory. This file is also called an artifact.

    note

    Each Pipeline Scan command overwrites the default results.json file with the latest results. By giving your JSON file a unique filename you can prevent subsequent scans from overwriting your saved scan results.

    The JSON file contains detailed information about each flaw in key-value pair. This example shows a single finding in a JSON file.

  5. To set your custom JSON file as the baseline file of known findings for this application, run:

    java -jar pipeline-scan.jar --file verademo.war -bf verademo_results.json

Next steps:

  • If you set a baseline file, store it in version control at the same level as the scanned application. Any changes to a baseline file can affect your security strategy. It is important that you version this file to ensure it contains the required baseline of findings for the given application. If necessary, you can revert to a previous version of the file.
  • Review the scan results with your team to determine a mitigation plan for addressing the discovered flaws.

Scan in a pipeline​

You can add the Pipeline Scan to a job in your development pipeline. You can use the provided code examples as templates for adding the Pipeline Scan as a stage in a pipeline job and configure the command parameters to achieve the desired scan results.

You can configure scans to run based on various triggers, such as commits, merge requests, or code builds. You can also configure scans to break the build based on flaw severity, CWE category, or security thresholds.

Before you begin:

Before running a Pipeline Scan, ensure you meet the prerequisites.

note

We recommend that you configure a Pipeline Scan in a test pipeline. For example, use a test pipeline on a local workstation or virtual machine (VM) in case you encounter any problems. You can safely resolve any problems in your test pipeline and ensure your configuration provides the expected scan results before moving the configuration to your production pipeline.

If you want to run a Pipeline Scan, try different commands, debug, or review scan results outside a pipeline, you can Run a Pipeline Scan from the Command Line.

You can also run and manage scans using the Pipeline Scan API.

A Veracode account is limited to six Pipeline Scans per 60 seconds, and each scan is limited to a maximum scan time of 60 minutes.

We recommend that you set the job to download pipeline-scan-LATEST.zip or get the latest Docker image, each time the job runs, to ensure that you are using the latest version of the Pipeline Scan. Alternatively, you can cache pipeline-scan-LATEST.zip locally on your CI system and download it at regular intervals. The code examples include a step for downloading and extracting the latest version of the Pipeline Scan ZIP archive.

To complete this task:

  1. Obtain the Pipeline Scan files.
  2. In your development pipeline, add or edit a job for the Pipeline Scan that runs after the stage for building your application.
  3. Add the code for your CI/CD code repository to the Pipeline Scan stage. For additional code examples or to ask questions, visit the Veracode Community.
  4. In the Pipeline Scan job, include either the pipeline-scan.jar file you extracted from pipeline-scan-LATEST.zip or the Docker image.
  5. Edit the Pipeline Scan job to include the command parameters that meet the security-scanning requirements for your application. The example configuration scenarios provide common configurations for specifying fail-build criteria, such as failing the pipeline on specific flaw severities or CWEs.
  6. Run the pipeline to run the Pipeline Scan job.

The scan results provide a list of discovered flaws, if any, and a status code. If the Pipeline Scan finds any flaws, it returns the status code >=1, or greater than or equal to 1, to indicate the number of flaws found and fails the pipeline job.

The Pipeline Scan saves the scan results to a build artifact, which is a JSON file named results.json. You can rename the JSON file and use it as a baseline file to set a baseline of discovered flaws for the scanned application.

Next steps:

  • If you set a baseline file, store it in version control at the same level as the scanned application. Any changes to a baseline file can affect your security strategy. It is important that you version this file to ensure it contains the required baseline of findings for the given application. If necessary, you can revert to a previous version of the file.
  • Review the scan results with your team to determine a mitigation plan for addressing the discovered flaws.

Apply security policies​

You can use a Veracode security policy to evaluate the scan results from a Pipeline Scan.

You can configure a Pipeline Scan to evaluate the scan results against one of the standard or recommended security policies. To use a custom policy, you must include the --request_policy parameter in your pipeline or at the command line to retrieve the policy definition from Veracode.

Pipeline Scan performs a Static Analysis scan and supports the following policy rule types:

  • Findings with CWE ID
  • Findings in CWE Category
  • Findings by Severity

Pipeline Scan does not consider grace periods, required scan frequency, or evaluation time frames.

Configure logging​

To obtain detailed console output during scanning, add the parameter --verbose=true to your pipeline script.

To send logging information to outputs other than the console, you can use the Apache Log4j 2 utility.

To configure logging settings, you can include a Log4j 2 configuration file with the name pipeline.scan.log4j2.properties in the execution directory of pipeline-scan.jar. The configuration file overrides the command-line options.

The following examples show a Java and XML configuration that uses Log4j 2 to:

  • Send verbose and debug messages to the log file pipeline-scan.log.
  • Send information messages to the console.

In both examples, you can turn on log for console by setting logger.file.additivity to true.

pipeline.scan.log4j2.properties example​

      # Extra logging related to initialization of Log4j
      # Set to debug or trace if log4j initialization is failing
      status = warn

      # Name of the configuration
      name = ConsoleLogForPipelineScan

      # Define the output file, e.g. logs/pipeline-scan.log, pipeline-scan.log
      property.filename = pipeline-scan.log

      # Console appender configuration
      appender.console.type = Console
      appender.console.name = consoleLogger
      appender.console.layout.type = PatternLayout
      appender.console.layout.pattern = [%d{dd MMM yyyy HH:mm:ss,SSSS}] PIPELINE-SCAN %p: %m %n

      # File appender configuration
      appender.file.type = File
      appender.file.name = fileLogger
      appender.file.fileName = ${filename}
      appender.file.layout.type = PatternLayout
      appender.file.layout.pattern = [%d{dd MMM yyyy HH:mm:ss,SSSS}] PIPELINE-SCAN %p: %m %n

      logger.file.name=PIPELINE_SCAN
      logger.file.level = debug
      logger.file.additivity = false
      logger.file.appenderRef.file.ref = fileLogger

      rootLogger.level = info
      rootLogger.appenderRef.stdout.ref = consoleLogger

log4j2.xml configuration file example​

Alternatively, to use a log4j2.xml configuration file like this example, you must specify the command line option -Dlog4j.configurationFile=[path-to]/log4j2.xml when running a pipeline scan:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level - %msg%n"/>
        </Console>
        <File name="File" fileName="pipeline-scan.log" append="true">
            <PatternLayout>
                <Pattern>%d{HH:mm:ss.SSS} [%t] %-5level - %msg%n</Pattern>
            </PatternLayout>
        </File>
    </Appenders>
    <Loggers>
        <Logger name="PIPELINE_SCAN" level="debug" additivity="false">
            <AppenderRef ref="File"/>
        </Logger>
        <Root level="info">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

Pipeline Scan parameters​

This section describes the command-line parameters for Pipeline Scan.

Use the Pipeline Scan command line to either:

  • Download a custom security policy to your working directory using the --request_policy <custom policy name> parameter. The only result is that you download the requested policy. No scanning occurs. we recommend that you only download a policy that has changed and do not download a policy every time you run a pipeline build.
  • Specify an application to scan using the --file <filename> parameter with the following parameters for configuring the scan, the scan results, and project metadata, which is your CI/CD code repository:
    • API credentials: your Veracode Platform API ID and key, using either an API credentials file or parameters at the command prompt.
    • Scan configuration: settings for how the scan runs, including how to fail a pipeline, the maximum scan runtime, and a baseline file against which to compare results.
    • Results display: options for configuring the scan results output. By default, the results are in results.json.
    • Project metadata: information about your CI/CD code repository to include in the results and usage reports.

Syntax​

java -jar pipeline-scan.jar {parameters}

If you are using JVM (Java Virtual Machine) version 9 or later, you might need to add --add-modules java.xml.bind in front of the -jar parameter.

Parameters​

ParameterLong versionDescription
-f Required--fileFilename of the packaged application to upload and scan.
-rp--request_policyName of the security policy to download as a file. Required only if you want to download the configuration for a custom policy defined by your organization. After downloading the policy, you can provide this file in a subsequent command using the --policy_file parameter. See an example of using a custom policy.
-prof--veracode_profileName of the profile in your API credentials file that contains your API credentials. Default is the default profile.
-vid Required--veracode_api_idYour Veracode API ID. Instead of using this parameter in the command line, we recommend you use them in an API credentials file.
-vkey Required--veracode_api_keyYour Veracode API key. Instead of using this parameter in the command line, we recommend you use them in an API credentials file.
-fs--fail_on_severityFail the pipeline job if the scan finds flaws of the specified severities. Enter a comma-separated list of severities in quotation marks. For example, --fail_on_severity="Very High, High" reports if issues of severity Very High or High exist in the scan. Default is "Very High, High, Medium, Low, Very Low".
-fc--fail_on_cweFail the pipeline job if the scan finds flaws of the specified CWEs. Enter a comma-separated list of CWE IDs. For example, if you include --fail_on_cwe=95,100,978, the scan results only list issues related to CWEs 95, 100, or 978. Default is to fail the job for all discovered CWEs. If you use --fail_on_cwe without defining a --fail_on_severity parameter, the Pipeline Scan uses the default --fail_on_severity values: "Very High, High, Medium, Low, Very Low".
-bf--baseline_fileFilter the flaws that exist in the specified baseline file and show only the new flaws in the current scan.
-pn--policy_nameName of the default security policy rule to apply to the scan results. You can only use this parameter with a default policy.
-pf--policy_fileName of the local policy file you want to apply to the scan results. To download this file, use the --request_policy parameter.
-t--timeoutAmount of time, in minutes, for the Pipeline Scan to wait before reporting an unsuccessful scan if the scan does not complete. Default is 60 minutes, which is also the maximum value. You can also set a timeout with the Pipeline Scan API.
-id--issue_detailsEnter true to show detailed messages for each issue in the results summary. The results include a link to Veracode remediation guidance. Default is false.
-esd--emit_stack_dumpEnter true to add the stack dump data for each flaw to the results in the file results.json. The stack dump data is listed in the stack_dumps property. Required if you want to use results.json with the CLI command veracode fix. Default is false.
-sd--summary_displayEnter true to show a human-readable results summary on the console. Default is true.
-jd--json_displayEnter true to show the JSON containing the scan results on the console. Default is false.
-V--verboseEnter true to display detailed messages in the scan results. Default is false.
-so--summary_outputEnter true to save the scan results as a human-readable file. Default is false.
-sf--summary_output_fileEnter the filename of the scan results summary file. The file is stored in the current directory. Default is results.txt.
-jo--json_outputEnter true to save the scan results in JSON format. Default is true.
-jf--json_output_fileRename the JSON file that contains the scan results. The file is stored in the current directory. Default filename is results.json.
-fjf--filtered_json_output_fileEnter the filename in the current directory to save results that violate pass-fail criteria. Default is filtered_results.json.
NOTE
You must use different filenames for the --json_output_file and --filtered_json_output_file parameters.
-gig--gl_issue_generationEnter true to create GitLab issues from discovered flaws. Default is false.
NOTE
Before you can use this parameter, you must configure GitLab to import findings. You can use any GitLab subscription to generate GitLab issues.
-gvg--gl_vulnerability_generationEnter true to create a JSON file from the scan results. GitLab automatically imports the flaws from the JSON file as vulnerabilities. Default is false.
NOTE
To use this parameter, you must define the paths and reports settings in the GitLab CI.
-p--project_nameEnter the name of the CI/CD code repository that runs a Pipeline Scan. This parameter adds the repository name to the scan results, which can help you track scans across repositories.
-u--project_urlEnter the source control URL for the CI/CD code repository that runs a Pipeline Scan.
-r--project_refEnter the source control reference, revision, or branch for the CI/CD code repository that runs a Pipeline Scan.
-aid--app_idEnter the application profile ID for the application you want to upload and scan.
-ds--development_stageEnter one these values, which are case-sensitive, for the type of development stage: Development, Testing, Release.
-i--includeEnter a case-sensitive, comma-separated list of name patterns that represent the names of the modules to scan as top-level modules. Veracode identifies these modules during prescan. The * wildcard matches zero or more characters. The ? wildcard matches exactly one character. For example, to include various module names that contain module: --include "module 1, module-*, module2.jar"
The scan results show the names of the modules that Veracode identified and the modules included in the scan. This parameter does not pause, stop, or impact the performance of your pipeline.
-h--helpList all the possible commands and parameters for the Pipeline Scan.
-v--versionDisplay the Pipeline Scan version.

Import findings into GitLab​

When using Pipeline Scan in GitLab pipelines, you can configure GitLab to generate issues for scan findings and import the findings to GitLab as vulnerabilities. You can use any GitLab subscription to generate GitLab issues.

This feature uses the GitLab API. You can configure it to support custom domains. To use a custom domain, set the GITLAB_URL CI/CD variable to the base URL. For example: GITLAB_URL=https://&lt;GITLAB_URL&gt;/api/v4/projects/. The default is https://gitlab.com/api/v4/projects/

To import findings into GitLab, complete the following tasks and configure the --gl_issue_generation and --gl_vulnerability_generation parameters.

Create a GitLab access token​

Create a GitLab access token and set it as an environment variable to enable a Pipeline Scan to generate GitLab issues from discovered flaws.

To complete this task:

  1. In Gitlab, select Edit Profile > Access Tokens > Create personal access token.
  2. Ensure that the token has a scope of api. See the GitLab documentation.
  3. Select Settings > CI/CD > Variables and store the token you created as an environment variable named PRIVATE_TOKEN.

Set GitLab base directories​

If you are scanning Java applications, set environment variables for GitLab base directories to enable a Pipeline Scan to generate GitLab issues.

To complete this task:

  1. In GitLab, select Settings > CI/CD > Variables.

  2. Set the following environment variables:

    • SRC_ROOT: the filepath typically is /src/main/java/.
    • JSP_ROOT: the filepath typically is /src/main/webapp/.

Status codes​

The following table describes the status codes for a completed Pipeline Scan. You can configure your development pipeline to use these status codes for pass-fail criteria during scanning.

Status codeDescription
0Pipeline Scan did not find any flaws.
1-200Range of the number of discovered flaws.
-1 or 255Scan failed because of network flaws, invalid Veracode API credentials, or other problems.
-2 or 254Scan did not complete within the default timeout of 60 minutes.
-3 or 253Scan did not complete within the time specified for the --timeout parameter.
Last updated on