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. Veracode recommends 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
Parameter | Long Version | Description |
---|---|---|
-f Required | --file | Filename of the packaged application to upload and scan. |
-rp | --request_policy | Name 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_profile | Name of the profile in your API credentials file that contains your API credentials. Default is the default profile. |
-vid Required | --veracode_api_id | Your Veracode API ID. Instead of using this parameter in the command line, Veracode recommends you use them in an API credentials file. |
-vkey Required | --veracode_api_key | Your Veracode API key. Instead of using this parameter in the command line, Veracode recommends you use them in an API credentials file. |
-fs | --fail_on_severity | Fail 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_cwe | Fail 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_file | Filter the flaws that exist in the specified baseline file and show only the additional flaws in the current scan. |
-pn | --policy_name | Name of the Veracode default policy rule to apply to the scan results. You can only use this parameter with a Veracode default policy. |
-pf | --policy_file | Name of the local policy file you want to apply to the scan results. To download this file, use the --request_policy parameter. |
-t | --timeout | Amount 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_details | Enter true to show detailed messages for each issue in the results summary. The results include a link to Veracode remediation guidelines. Default is false . |
-esd | --emit_stack_dump | Enter 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_display | Enter true to show a human-readable results summary on the console. Default is true . |
-jd | --json_display | Enter true to show the JSON containing the scan results on the console. Default is false . |
-V | --verbose | Enter true to display detailed messages in the scan results. Default is false . |
-so | --summary_output | Enter true to save the scan results as a human-readable file. Default is false . |
-sf | --summary_output_file | Enter the filename of the scan results summary file. The file is stored in the current directory. Default is results.txt . |
-jo | --json_output | Enter true to save the scan results in JSON format. Default is true. |
-jf | --json_output_file | Rename 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_file | Enter 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_generation | Enter true to create GitLab issues from discovered flaws. Default is false .NOTE Before you can use the --gl_issue_generation parameter in a Pipeline Scan, you must create a GitLab access token. If you want to use this parameter when scanning Java applications, you must also configure environment variables to set GitLab base directories. You can use any GitLab subscription to generate GitLab issues.The issue generation 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://<GITLAB_URL>/api/v4/projects/ . If not set, this value defaults to https://gitlab.com/api/v4/projects/ |
-gvg | --gl_vulnerability_generation | Enter 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_name | Enter 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_url | Enter the source control URL for the CI/CD code repository that runs a Pipeline Scan. |
-r | --project_ref | Enter the source control reference, revision, or branch for the CI/CD code repository that runs a Pipeline Scan. |
-aid | --app_id | Enter the application profile ID for the application you want to upload and scan. |
-ds | --development_stage | Enter one these values, which are case-sensitive, for the type of development stage: Development , Testing , Release . |
-i | --include | Enter 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 | --help | List all the possible commands and parameters for the Pipeline Scan. |
-v | --version | Display the Pipeline Scan version. |