Using Scan Directives for Agent-Based Scanning

Veracode Software Composition Analysis

Veracode Software Composition Analysis agents support scans that include per-scan directives, known as scan directives. To specify these scan directives on a per-project basis, include a srcclr.yml file at the root of the scan.

Note: When you include a comma-separated list in a directive, enclose the string in quotation marks.
You can also use each scan directive as an environment variable in your CI configuration by adding SRCCLR_ before the directive name and changing the directive name to be all uppercase. For example:
export SRCCLR_SCAN_COLLECTORS=pip

Agent Directives

scan_collectors:

By default, Veracode SCA agents find all supported build tools and package managers in the directory specified by the scan command, or the current directory for CI scans. You can use scan_collectors to specify which build tools and package managers to use. The possible values for scan_collectors are:

Collector Language
maven Java
gradle
ant
jar
sbt Scala
glide Go
"go get"
"go mod"
godep
dep
govendor
trash
pip Python
pipenv
bower JavaScript
yarn
npm
cocoapods Objective-C
gem Ruby
composer PHP
makefile C/C++
dll C#
msbuilddotnet

Example:

scan_collectors: "gem, maven"

skip_collectors:

By default, Veracode SCA agents find all supported build tools and package managers in the directory specified by the scan command, or the current directory for CI scans. You can use skip_collectors to specify which build tools and package managers to ignore when running a scan. The possible values for skip_collectors are:

Collector Language
maven Java
gradle
ant
jar
sbt Scala
glide Go
"go get"
"go mod"
godep
dep
govendor
trash
pip Python
pipenv
bower JavaScript
yarn
npm
cocoapods Objective-C
gem Ruby
composer PHP
makefile C/C++
dll C#
msbuilddotnet

Example:

skip_collectors: "godep,govendor,go get"
Note: If you include a comma-separated list with the skip_collectors command using PowerShell, you must enclose the string in quotation marks to avoid errors.

scan_analyzers:

In container scans, Veracode SCA agents find all supported build tools and package managers in the directory specified by the scan command or the current directory for CI scans, by default. You can use scan_analyzers to specify which build tools and package managers to use. The possible values for scan_analyzers are:

Analyzer Package Manager Language/Distribution
yum yum CentOS, RHEL
gem gem Ruby
pip2 pip2 Python 2
pip3 pip3 Python 3
npm NPM JavaScript
apk apk Alpine
apt apt Debian, Ubuntu

Example:

scan_analyzers: "apk, yum"

skip_analyzers:

In container scans, Veracode SCA agents find all supported build tools and package managers in the directory specified by the scan command or the current directory for CI scans, by default. You can use skip_analyzers to specify which build tools and package managers to ignore when running a scan. The possible values for skip_analyzers are:

Analyzer Package Manager Language/Distribution
yum yum CentOS, RHEL
gem gem Ruby
pip2 pip2 Python 2
pip3 pip3 Python 3
npm NPM JavaScript
apk apk Alpine
apt apt Debian, Ubuntu

Example:

skip_analyzers: "apk, yum"

vuln_methods_ignored_directories:

A comma-separated list of directories that you want Veracode to ignore during a vulnerable methods analysis. This directive overrides the default directories.

Example:

vuln_methods_ignored_directories: doc

vuln_methods_extra_ignored_directories:

A comma-separated list of directories that adds to the default per-language set that the agent ignores during a vulnerable methods analysis.

vuln_methods_extra_ignored_directories: "doc, test"

Default values:

  • Ruby: test
  • Java: test
  • Python: test, tests, doc, docs, bin, .virtualenv, env, venv

ssl_cert_dir:

A filepath that specifies the directories that contain X.509 certificates that the Veracode SCA agent should trust in addition to the certificates present in the Java Runtime Environment (JRE) or stored in your operating system. If you enter multiple directories, separate the filepaths with the correct path separator for your operating system. For example, use a colon (:) for Linux and macOS.

Default value: the certificate location directory specified in the Java Virtual Machine (JVM).

Example:
ssl_cert_dir: C:\path\to\certificate\directory

ssl_cert_file:

A filepath that specifies the X.509 certificates that the Veracode SCA agent should trust in addition to the certificates present in the JRE or stored in your operating system. If you enter multiple files, separate the filepaths with the correct path separator for your operating system. For example, use a colon (:) for Linux and macOS. If specified, this value overrides the ssl_cert_dir directive.

Default value: the certificate location specified in the JVM.

Example:
ssl_cert_file: C:\path\to\certificate\example_cert.cer

Multi-Language Directives

scope:

Ruby, Java, NPM, Yarn, Bower, PHP

The scope directive limits the dependency resolution, including the discovered dependencies, to the dependencies within the specified scope. It also includes any scope from which the specified scope inherits, as long as the build system supports the inherited scope. This directive applies the same scope to any package manager used in the project.

For Maven, you can set the scope directive to one of these values:
  • compile to restrict the scan to system, provided, and compile dependencies.
  • runtime to restrict the scan to compile and runtime dependencies.
  • compile+runtime to restrict the scan to system, provided, compile, and runtime dependencies.
  • runtime+system to restrict the scan to system, compile, and runtime dependencies.
  • test to restrict the scan to system, provided, compile, runtime, and test dependencies.

For Ant projects that use the Ivy dependency manager, you can use the scope directive to specify a comma-separated list of configurations where the dependencies belong. The list can include configuration names, an asterisk (*) to specify all configurations, and !conf to exclude the conf configuration.

For NPM, you can set the scope directive to one of these values:
  • production or prod to restrict the scan to production dependencies, including the optional dependencies you can install.
  • development or dev to restrict the scan to development dependencies.
For Yarn, you can set the scope directive to one of these values:
  • production or prod to restrict the scan to production, peer, and optional dependencies.
  • development or dev to restrict the scan to development dependencies.

For PHP, you can set the scope directive to --no-dev, which only installs production packages.

Default values by package manager:
  • Maven: compile
  • Ant, with Ivy: Any one of default, runtime, compile, or *, resolved in that order.
  • Gradle 3.0 and earlier: compile
  • Gradle 3.1–3.3: runtime
  • Gradle 3.4 and later: default
  • Bundler: The scope defined in your Gemfile
  • NPM: All scopes defined in your package.json file

Example:

# Java example
scope: testCompile

# Prevent scanning 'devDependencies' for an NPM project
scope: production
Note: This example indicates that you only want to include dependencies that are in the testCompile scope, or a scope from which testCompile inherits.

Java

compile_first:

Boolean value that forces the Veracode SCA agent to perform a compilation prior to scanning. Only applicable for Maven.

Default value: true

Example:

compile_first: false

install_first:

Boolean value that forces the Veracode SCA agent to perform a compilation and installation prior to scanning. Only applicable for Maven.

Default value: true

Example:

install_first: false

custom_maven_command:

String attribute with which the Veracode SCA agent utilizes the supplied Maven options instead of compile and install, which are the defaults. This command must take the form of a single String object.

Default value: compile install

Example:

custom_maven_command: clean compile

custom_maven_exec:

String attribute that specifies the full path to a custom Maven executable. Defaults to using the Maven executable on the PATH of the environment in which the agent performs the scan.

Example:

custom_maven_exec: /usr/local/bin/mvn

custom_gradle_exec:

String attribute that specifies the full path to a custom Gradle executable. Defaults to using the Gradle executable on the PATH of the environment in which the agent performs the scan or a gradlew file in the directory being scanned, if it exists.

Example:

custom_gradle_exec: /usr/local/bin/gradle

custom_ant_exec:

String attribute that specifies the full path to a custom Ant executable. Defaults to using the Ant executable on the PATH of the environment in which the agent performs the scan.

Example:

custom_ant_exec: /usr/local/bin/ant

ant_build_steps:

String attribute with custom Ant build steps to run before scanning.

Example:

ant_build_steps: clean compile

ivy_settings_filename:

By default, Veracode SCA uses the ivysettings.xml file found in the root folder. You can use this directive to specify another Ivy settings file. Specify the file using its absolute path or its path relative to the root folder.

Absolute path example:

ivy_settings_filename: /path/to/ivysettings.xml

Relative path example:

ivy_settings_filename: ivysettings-release.xml

ant_lib_dir:

This directive defines where your Ant third-party dependencies are located if you do not provide Ant build steps in the ant_build_steps directive. The directive value defaults to the directory in which you perform scans. Specify the location as comma-separated directory paths that are either absolute or relative to the scan project root.

Example:

ant_lib_dir: lib/, main/jarfiles/

gradle_location:

This directive supports configurations in which the gradlew file does not exist at the root of a Gradle project. This value must be a relative path and include the gradlew filename at the end.

Example:

gradle_location: api/gradlew

gradle_tasks:

By default, the agent uses the classes task when performing Gradle scans. This task allows for complete dependency resolution and generation of class files, while not going far enough in the build to execute unit and integrations tests. To run custom tasks during Gradle scans instead of the classes task, use this directive with a space-separated list of tasks to execute.

Default value: classes

Example:

gradle_tasks: clean compile

gradle_filter_task:

This directive allows you to dynamically pin scans to only specific sub-modules, based on whether that sub-module contains the specified task. In the example below, the scan is limited to sub-modules containing the classes task.

Example:

gradle_filter_task: classes

dependency_tree_file:

This directive allows you to specify the path to a file containing the output of the Maven dependency:tree command or the Gradle dependencies task in dependency tree scanning mode. The path is relative to the root folder.

Example:

dependency_tree_file: tree.txt

Ruby

force_bundle_install:

Boolean attribute that forces the Veracode SCA agent to perform a bundle install, even when a Gemfile.lock file already exists.

Default value: false

Example:

force_bundle_install: true

Python

system_site_packages:

This directive maps to a boolean that indicates whether the Python virtualenv image with which the Veracode SCA agent scans for pip dependency information includes the system site packages.

Default value: false

Example:

system_site_packages: true

pip_requirements_file:

The attribute value associated with this directive is a file that indicates an alternative location to find the pip requirements file for a particular project. If you do not specify this directive, the Veracode SCA agent looks for requirements.txt, dev-requirements.txt, or requirements-dev.txt in the root of the project.

Example:

pip_requirements_file: libs/requirements.txt

pip_extra_flags:

This directive allows you to specify extra flags for the pip install command that the Veracode SCA agent executes.

Example:

pip_extra_flags: --extra-index-url http://example.com/pypi/simple --trusted-host example.com

NPM

skip_npm_install

Boolean value that determines whether the agent skips the npm install task when scanning an NPM project.

Default value: false

Example:
skip_npm_install: true

Bower

allow_root:

By default, Bower does not permit root users to perform installation tasks. While this restriction is for security reasons, many Docker configurations use the root user. Setting this directive to true instructs Bower to use the --allow-root flag.

Default value: false

Example:

allow_root: true

Go

force_go_install:

Boolean value that forces the Veracode SCA agent to download the Go dependencies the project uses before scanning for them.

Default value: false

Example:

force_go_install: false

PHP

skip_composer_install:

Boolean value that can prevent Veracode SCA from re-installing composer packages. If you use this directive, the composer.lock file must be present in the repository already.

Default value: false

Example:

skip_composer_install: false

.NET

skip_dotnet_restore:

Boolean value that skips the restore step for NuGet packages in MSBuild during the scan. Veracode recommends you use this directive in either of these situations:
  • You do not have the executables installed on your machine.
  • You built the project with the project.assets.json files present in the project directory before performing the scan.
Note: If you set this directive to true when the project.assets.json files are not present in the project, Veracode SCA cannot identify dependencies.

Default value: false

Example:

skip_dotnet_restore: true

use_dotnet_exec:

This directive specifies the .NET toolchain for the Veracode SCA agent to use. If you do not specify a toolchain, the agent attempts to identify one of the three valid case-insensitive toolchain values, searching in this order: dotnet, nuget, then msbuild. The agent ignores this directive if the custom_dotnet_exec, custom_msbuild_exec, or custom_nuget_exec directive specifies an executable.

Example:

use_dotnet_exec: nuget

custom_dotnet_exec:

String attribute that specifies the full path to a custom .NET CLI executable. The default value is the .NET executable on the PATH of the environment in which the agent performs the scan.

Example:

custom_dotnet_exec: C:\build_tools\dotnet.exe

custom_msbuild_exec:

String attribute that specifies the full path to a custom MSBuild CLI executable. The default value is the MSBuild executable on the PATH of the environment in which the agent performs the scan. The agent ignores this directive if the custom_dotnet_exec directive specifies an executable.

Example:

custom_msbuild_exec: C:\build_tools\msbuild.exe

custom_nuget_exec:

String attribute that specifies the full path to a custom NuGet CLI executable. The default value is the NuGet executable on the PATH of the environment in which the agent performs the scan. The agent ignores this directive if either the custom_dotnet_exec or custom_msbuild_exec directive specifies an executable.

Example:

custom_nuget_exec: C:\build_tools\nuget.exe

C/C++

make_build_target:

This directive specifies the command-line arguments for the make command that builds the project. By default, the make command runs without any command-line arguments for building the project.

Example:
make_build_target: all

make_clean_target:

This directive specifies which command-line argument for cleaning the project to run with the make command.

Default value: clean

Example:
make_clean_target: distclean

make_output_file:

This directive specifies the path, relative to the project root, to the text file that contains the output of the make command. If you use this directive, the scan agent parses the text file to obtain information about dependencies instead of running the make command to build the project.

Example:
make_output_file: make_log.txt

Automatic Pull Requests

You can use the following scan directives to configure when Veracode SCA automatically generates a pull request.
pr_on
Determines the risk level of vulnerability in your results that triggers a pull request. The values are:
  • Never: Never generate a pull request.
  • Methods: Generate a pull request when libraries contain calls to vulnerable methods.
  • Low: Generate a pull request when libraries contain calls to vulnerable methods or vulnerabilities with a risk level of low or higher. Default value.
  • Medium: Generate a pull request when libraries contain calls to vulnerable methods call chains or vulnerabilities with a risk level of medium or higher.
  • High: Generate a pull request when libraries contain calls to vulnerable methods or vulnerabilities with a risk level of high.
no_breaking_updates
Controls whether automatic pull requests include upgrades that the update advisor considers potentially build-breaking. If you set this directive to true, the breaking column in the pull request contains only non-breaking updates. The values are:
  • True: Do not include potentially build-breaking upgrades in a pull request.
  • False: Include upgrades in a pull request even if they could break the build. Default value.
ignore_closed_prs
Controls whether the agent creates pull requests when a closed pull request contains the exact same changes.
By default, the agent does not create pull requests that contain the exact same changes as any existing PR, either open or closed. The values are:
  • True: Generate a pull request if there are no open pull requests with the exact same changes.
  • False: Generate a pull request if there are no pull requests of any status with the exact same changes. Default value.
Example:
pr_on: medium
no_breaking_updates: true
ignore_closed_prs: false