SCA agent scan directives

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

When you include a comma-separated list in a directive, enclose the string in quotation marks.

To use each scan directive as an environment variable in your CI configuration, add SRCCLR_ before the directive name and change the directive name to all uppercase. For example:

export SRCCLR_SCAN_COLLECTORS=pip

General

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:

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

When you run the SCA agent with the --quick option, the possible values for scan_collectors are:

Language	Collector
Java	"jar quickscan"
Scala	"jar quickscan"
Go	"glide quickscan" "godeps quickscan" "dep quickscan" "go mod quickscan" "govendor quickscan" "trash quickscan"
Python	"Pipfile.lock quickscan"
JavaScript	"bower quickscan" "yarn quickscan" "npm quickscan" "node_modules quickscan"
Objective-C	"podfile.lock quickscan"
Ruby	"gemfile.lock quickscan"
PHP	"composer quickscan"
C/C++	"sofile quickscan"
C#/.NET	"dotnet quickscan" "dll quickscan"
SBOM	SbomQuickScanCollector

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:

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

When you run the SCA agent with the --quick option, the possible values for skip_collectors are:

Language	Collector
Java	"jar quickscan"
Scala	"jar quickscan"
Go	"glide quickscan" "godeps quickscan" "dep quickscan" "go mod quickscan" "govendor quickscan" "trash quickscan"
Python	"Pipfile.lock quickscan"
JavaScript	"bower quickscan" "yarn quickscan" "npm quickscan" "node_modules quickscan"
Objective-C	"podfile.lock quickscan"
Ruby	"gemfile.lock quickscan"
PHP	"composer quickscan"
C/C++	"sofile quickscan"
C#/.NET	"dotnet quickscan" "dll quickscan"
SBOM	SbomQuickScanCollector

Example:

skip_collectors: "godep,govendor,go get"

Important

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 the scans to ignore during a vulnerable method 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 method 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

scope

For scope options, see Multi-language scan directives.

Automatic pull requests

You can use these scan directives to configure when an SCA agent 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

Multi-language

scope

You can use the scope directive with Ruby, Java, NPM, Yarn, Bower, and PHP projects. It 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. The default value.
• development or dev to restrict the scan to development dependencies.
• all to scan production and 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. The default value.
• development or dev to restrict the scan to development dependencies.
• all to scan production and development dependencies.

For .NET, you can set the scope directive to one of the following values:

• runtime to restrict the scan to runtime dependencies. The default value.
• all to scan runtime and compile 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
• .NET: runtime

Example:

The following example indicates that you only want to include dependencies that are in the testCompile scope, or a scope from which testCompile inherits.

# Java example
scope: testCompile

# Prevent scanning 'devDependencies' for an NPM project
scope: production

.NET

skip_dotnet_restore

Boolean value that skips the restore step for NuGet packages in MSBuild during the scan. We recommend using this directive in the following 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.

Important

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

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

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

Go

force_go_install

Boolean value that forces the Veracode SCA agent to download the Go dependencies for Glide, Go get, Godep, Govendor, and Trash projects before scanning for them.

Default value: false

Example:

force_go_install: false

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 submodules, based on whether that submodule contains the specified task. In the example below, the scan is limited to submodules 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

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

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

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

use_virtualenv

Boolean attribute that specifies to create a virtual environment using virtualenv for scanning with the pip package manager.

Default value: true

Example:

use_virtualenv: false

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