Manage agents and scans

SCA Agent-based Scan uses an agent, or scanner, to connect your repositories to the Veracode Platform. The agent builds and scans your code to find third-party libraries, the vulnerabilities contained in those libraries, and to assess the risk of your open-source licenses.

You can set up SCA agents on your desktop, for running scans locally using a CLI, or integrate SCA agents with your continuous integration (CI), source code management (SCM), or ticketing tools.

To set up an SCA agent and run a scan using the SCA CLI, see the quickstart.

Prerequisites

Ensure your environment meets these requirements.
Ensure your repositories have the supported languages and package managers.
Ensure that the applications you want to scan build successfully.
To create and manage workspace agents for specific workspaces, you must have the Workspace Administrator, Workspace Editor, or Submitter role. To manage any workspace agent, you must have the Security Lead role.
To create and manage organization agents, you must have the Security Lead role.
By default, the agent you create is not visible to team members. To allow visibility, invite teams to your workspace.

SCA agent levels

You can create SCA agents at one of two levels: workspace agents, which are agents for specific workspaces, and organization agents, which are agents that are available to all workspaces.

Workspace agents

Use workspace agents to scan projects and store their scan results in a specific workspace. When you create a new workspace, you can set up at least one agent for that workspace to scan projects into that workspace. The agent only scans into the specified workspace.

Organization agents

Use organization agents to scan in any workspace. Because one agent can scan into any workspace, these agents can minimize setup for new workspaces. You simply identify a workspace at scan time using a flag, called a workplace slug, or an environment variable.

Command-line interface

The SCA agent command-line interface (CLI) is a tool designed for you to install and run SCA agents from your desktop. You can set up SCA agents on Mac OS X 10 or Linux, with installation and updates using the HomeBrew system on Apple, and as a downloadable installer for other operating systems. The CLI is designed for users who want to test their source code locally before pushing it to a repo, or who want to scan their code manually. The CLI reports scan results as output or JSON, and generates detailed and customizable results in the Veracode Platform. See the commands.

If you can build or package a project with default options, the agent can complete its analysis. If your application uses a complex build process or requires advanced configuration, the agent might not be able to complete its analysis. For example, if it requires access to private repositories or environmental settings that aren't available from your desktop. The CLI is a one-time analysis tool that does not automatically re-scan when you change source code or rebuild software. You can point the CLI at a Git URL or local Git-based folder on the file system, which then performs a shallow clone of the repository located at the URL, runs a scan, and deletes the cloned repository from your local file system.

Set up SCA agents

To manage and run SCA scans on your desktop, set up SCA CLI agents and use the commands. This CLI is not related to the Veracode CLI.

To manage and run SCA scans in your repos, integrate the SCA agent with your repos and manage scans using environment variables.

If you encounter issues with SCA Agent-based Scan in your pipelines, you can use the command-line agent to run scans locally for troubleshooting purposes.

Set up an SCA CLI agent

Set up an SCA agent on your desktop to scan local or public repositories and review the results using a CLI. You can use the CLI to develop scripts.

To configure the agent, use the parameters in the agent.yml file. To run scans, use the commands. To configure scanning options, use the scan directives.

Alternatively, set up an agent using PowerShell.

Before you begin:

Ensure your local system meets the requirements.
If you are using Homebrew and have an older version of the agent installed, uninstall the older version before upgrading.

To complete this task:

In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
Select the Agent-Based Scan tab.
Select Start a Scan > Create an Agent. Alternatively, select a workspace, select Agents under Manage Workspace, then select Actions > Create.
On the Set Up Scanner page, select your operating system to open the Command Line Interface page.
Select the tab for your preferred method of installation for your OS type (curl, apt-get, yum, homebrew).
Open a terminal window and follow the instructions to install the agent.
Copy the srcclr activate command for activating the agent and paste it in your terminal.
Copy the activation token under the srcclr activate command.
Run the activate command for your region from the agent server:
- Commercial region: srcclr activate
- European region: srcclr activate --region ER
- United States Federal region: srcclr activate --region FED
Paste the token you copied into your terminal and press Enter. If necessary, you can regenerate tokens.

Your agent.yml configuration file installs to the ~/.srcclr folder. If that file already exists, you are prompted to enter a profile name. This profile name allows you to choose which token you use when scanning.
- For workspace agents, we recommend using the name of the workspace associated with the token.
- For organization agents, if you plan on creating more than agent one to use with different teams or workspaces, we recommend indicating that in the profile name.
If you are using YUM, add your repo to your list of YUM repos.
To verify the agent, run one of the following commands to try scanning a specific package manager.
- Ant: srcclr test --ant
- Bower: srcclr test --bower
- Cocoapods: srcclr test --cocoapods
- Composer: srcclr test --composer
- Glide: srcclr test --glide
- Go Get: srcclr test --go
- Godep: srcclr test --godep
- Govendor: srcclr test --govendor
- Gradle: srcclr test --gradle
- Ivy: srcclr test --ivy
- Maven: srcclr test --maven
- NPM: srcclr test --npm
- Python: srcclr test --pip
- Ruby Gems: srcclr test --gem
- SBT: srcclr test --sbt
- Trash: srcclr test --trash
- Yarn: srcclr test --yarn
- Nuget: srcclr test --nuget

If the agent installs successfully, you can view all the tests with a result of PASSED.

Set up an SCA CLI agent using PowerShell

If you are running a scan in a Windows environment and do not want to use Chocolatey to install SCA CLI agents, you can use PowerShell.

To complete this task:

In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
Select Agent-Based Scan.
Select a workspace.
Select Agents > Actions > Create > Windows.
Select PowerShell.
Select Create Agent & Generate Token.
Set the $Env:SRCCLR_API_TOKEN environment variable to the authentication token you just generated.
If your Veracode account is in the Commercial region, skip this step. If your Veracode account is in the European or United States Federal region, set the $Env:SRCCLR_REGION environment variable to one of the following:
- European region: ER
- United States Federal region: FED
In your PowerShell terminal, set execution policy to AllSigned.
```
Set-ExecutionPolicy AllSigned -Scope Process -Force
```
By default, PowerShell does not permit scripts to run.

To download the script, run:

$ProgressPreference = "silentlyContinue"; iex ((New-Object System.Net.WebClient).DownloadString('https://sca-downloads.veracode.com/ci.ps1'))

Add your repo to your YUM repos

If you are using YUM, add your repository to your list of YUM repositories by creating a file /etc/yum.repos.d/SRCCLR.repo with the following content.

[SourceClear] name=SourceClear baseurl=https://sca-downloads.veracode.com/redhat/x86_64/
enabled=1 gpgcheck=1 gpgkey=https://sca-downloads.veracode.com/redhat/SRCCLR-GPG-KEY

To update and install, run:

sudo yum update sudo yum install srcclr

The first time you run this command, you are prompted to accept the GPG key.

Uninstall older agents using Homebrew

If you are using Homebrew and have previously installed version 3.8.30 or earlier of the SCA agent:

brew uninstall srcclr
brew untap srcclr/srcclr
brew tap veracode/srcclr
brew install srcclr

Integrate an SCA CI agent

The continuous integration (CI) server agent runs on your network and connects with your CI and SCM systems to scan your repos. You can use a cURL command that pulls down the latest version of the agent and performs a scan for any CI software within a Linux-based environment.

The plugin for CI servers inherits the advantages and disadvantages of the plugins for build and package managers with the added advantage that they report directly into the same reporting and alerting system that already exists in the CI server. There are numerous configuration options for the CI agent, as it uses the same code base as the CLI agent.

After you integrate an agent, you can manage it and run scans using environment variables.

You can also integrate the agent with ticketing systems and import findings into these systems.

Build and package managers

SCA Agent-based Scan provides plugins for Maven and Gradle. These plugins are designed to be run from within the continuous integration or continuous delivery pipeline of your team, or alternatively on local builds on a developer desktop. These plugins typically install and run automatically each time a build job is executed based on the build settings in the team source code management system.

Plugins for build and package managers are designed for teams and individual developers who are familiar with making configuration changes and want full control over their software build process. When used centrally as part of the continuous integration pipeline, the plugins allow teams to check the security quality of their open-source code every time you build code. When used locally, the plugins allow developers to check their local copy of their software for defects before committing changes to the team.

Configure proxies

If you use the SCA agent with a CI tool that is behind a proxy, connect the agent to your proxy server.

Before you begin:

If your proxy performs TLS interception, you must provide the certificate chain to the agent.
If your Veracode account is in the United States Federal region, running the SCA agent behind a proxy server is not supported.

To complete this task:

To make the Java virtual machine (JVM) aware of the root certificate, run the appropriate command for your operating system:
- Linux or Mac:
```
export SRCCLR_SSL_CERT_FILE="/path to certificate file/"
```
- Windows PowerShell:
```
$env:SRCCLR_SSL_CERT_FILE='/path to certificate file/'
```
To make the agent aware of the proxy, make one of these configurations:
- Set the https_proxy environment variable containing a URL that points to the proxy server. For example:
  - Linux or Mac:
    export https_proxy="http://127.0.0.1:8080"
  - Windows Powershell:
    $env:https_proxy='http://127.0.0.1:8080'
- Set the agent configuration values relevant to proxy identification and authentication, such as proxyHost and proxyPort, in ~.srcclragent.yml or in another YML configuration file defined with the --config= option.
  
  For example, include proxyHost: 127.0.0.1 and proxyPort: 8080 in ~/.srcclr/agent.yml.

To complete the connection, run the appropriate command to establish communication between the agent and the proxy server. For example:

Linux or Mac:

curl -sSL https://sca-downloads.veracode.com/ci.sh | env DEBUG=1 SRCCLR_SSL_CERT_FILE="/path to certificate file/" bash -s scan --skip-collectors "ant,npm"

Windows PowerShell:

$Client = New-Object -TypeName System.Net.WebClient
$Client.Proxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials
$Script = $Client.DownloadString('https://sca-downloads.veracode.com/ci.ps1')
Invoke-Command -ScriptBlock ([scriptblock]::Create($Script)) -ArgumentList @('scan', '--skip-collectors', 'ant,npm')

Important

If you do not use the https_proxy environment variable or set proxyHost and proxyPort in ~/.srcclr/agent.yml, you must include '--config=/path to configuration file/' in this command.

Scan repos

To scan repositories, use the scan command. To configure scanning options, use the scan directives. If your repos are behind a proxy, configure proxy settings.

To scan public repositories, run:

srcclr scan --url https://github.com/veracode/example-ruby

To clone and scan local repositories, run:

srcclr scan FILE_PATH

View workspace agents

For information on viewing agents with the SCA REST API, see Using the Veracode SCA REST API.

Before you begin:

You must have the Security Lead, Workspace Administrator, Workspace Editor, or Submitter role.

To complete this task:

In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
Select Agent-Based Scan.
Select a workspace.
From the Manage Workspace dropdown, select Agents.

View organization agents

Before you begin:

You must have the Security Lead role.

To complete this task:

In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
Select Agent-Based Scan.
Select Agent-Based Scan Settings > Agents.

Rename SCA agents

Before you begin:

To rename an organization agent, you must have the Security Lead role.
To rename a workspace agent, you must have the Security Lead, Workspace Administrator, Workspace Editor, or Submitter role.

To complete this task:

In the Veracode Platform, navigate to the Agents page at either the workspace or organization level.
Select an agent.
Select the pencil icon.
Enter the new agent name.
Select Save.

Delete SCA agents

You can also delete agents with the SCA REST API.

Before you begin:

To delete an organization agent, you must have the Security Lead role.
To delete a workspace agent, you must have the Security Lead, Workspace Administrator, Workspace Editor, or Submitter role.

Caution

Deleting agents cannot be undone. When you delete an agent, any subsequent scans using the token for that agent will fail.

To complete this task:

Navigate to the Agents page at either the workspace or organization level.
Select an agent.
Select the trash can icon.
Select Delete Agent.

Apply an organization agent to a workspace

When scanning with an organization agent in a pipeline, you can apply the agent to a workspace using a scan directive or an environment variable. To specify a workspace, use the workspace's slug.

Regenerate SCA agent tokens

To connect to your organization to Veracode during scanning, Veracode SCA uses an agent authentication token, which acts as a password.

If another user gets access to your token, that person can use the Veracode SCA agent as if they were you. For workspace agent tokens, they can scan into the workspace linked to that agent, which taints your data. For organization agents tokens, if they can identify a workspace in your organization, they can scan into that workspace. Keep your token private.

You may want to regenerate this token if you believe it was compromised. Regenerating a token will invalidate the old token. Any agents using this token will no longer be able to scan.

You can also regenerate agent tokens with the SCA REST API.

Before you begin:

To regenerate an organization agent token, you must have the Security Lead role.
To regenerate a workspace agent token, you must have the Security Lead, Workspace Administrator, Workspace Editor, or Submitter role.

To complete this task:

In the Veracode Platform, navigate to the Agents page at either the workspace or organization.
Select an agent.
Select Regenerate Token. A new token displays. If you close the page, the token disappears, and you must generate it again.
Copy this token and paste it into the relevant configuration file.
Update your environment variables with the new token.

Turn on the update advisor

The update advisor provides safe versions of libraries we recommend you use to resolve vulnerabilities. If you configure it in your build automation script, it also indicates if the update might break a build.

The update advisor determines the potential of breaking a build only for Java, .NET, Python, and Ruby libraries.

To complete this task:

Add the --update-advisor argument to your command or build script. For example:
```
EXTRA_ARGS='--update-advisor'
```
Add the argument to the scan command.
- If you scan with a CI tool, add the argument to the build script for your project. For example:
```
curl -sSL https://sca-downloads.veracode.com/ci.sh | bash -s – scan $EXTRA_ARGS
```
- If you scan local repos, add the argument to your agent.yml file. For example:
```
srcclr scan <example_path>/example-java-maven --EXTRA_ARGS 
```

Next steps:

After you perform a scan with the update advisor enabled, your results include a Breaking Update column in the Update Advisor section.

SCA agent configuration

You can configure SCA agents using the [parameters in the agent.yml] file or, alternatively, using environment variables.

`agent.yml` parameters

You configure the following key names in the agent.yml file, which is created when you activate the SCA agent. Alternatively, you can configure these settings as environment variables.

`agentAuthorization`

(Required) Bearer token used to authenticate API calls.

`apiUrl`

The URL for the Veracode Platform backend API that the SCA agent uses to manage scans. Valid values are:

https://sca-api.veracode.com - Commercial Region. The default.
https://sca-api.veracode.eu - European Region.
https://sca-api.veracode.us - United States Federal Region.

`maxErrorLines`

The maximum number of lines of build error messages that the CLI transmits to the REST API when reporting a build failure.

`proxyType`

One of the strings HTTP or SOCKS which will indicate the kind of proxy the Agent should use when connecting to proxyHost and proxyPort.

`proxyHost`

The IP or hostname that the Agent should use for proxy communication.

`proxyPort`

The integer value of the port on the IP or hostname specified in proxyHost.

`proxyUsername`

The username that the agent uses to authenticate against the proxy specified by proxyHost and proxyPort.

`proxyPassword`

The password that the agent uses to authenticate against the proxy specified by proxyHost and proxyPort.

`region`

The region-specific server where Veracode stores your results. Overrides apiUrl. Valid values are:

COM - Commercial Region. The default.
ER - European Region.
FED - United States Federal Region.

`skipVersionCheck`

A boolean which determines whether the agent attempts to check for the latest version.

`scmType`

One of the following supported source code management systems: GITHUB, GITHUBENTERPRISE, GIT, STASH.

`scmToken`

A GitHub or GitHub Enterprise API token which may also be used to clone private repos.

`scmUrl`

The endpoint used to communicate with the API of your source code management system.

`scmUsername`

Used to authenticate the scmUrl above.

`scmPassword`

Password associated with the scmUsername

Environment variables

As an alterative to the parameters set in the agent.yml file, you can configure SCA agents using the following environment variables.

`SRCCLR_API_TOKEN`

Provides an alternate means of supplying the agentAuthorization token required to use the REST API. If present, this variable supersedes the configuration file.

`SRCCLR_API_URL`

Specifies the URL for the Veracode Platform backend API that the SCA agent uses to manage scans. Overrides SRCCLR_REGION. Valid values are:

https://sca-api.veracode.com - Commercial Region. The default.
https://sca-api.veracode.eu - European Region
https://sca-api.veracode.us - United States Federal Region

`SRCCLR_REGION`

Region-specific server where Veracode stores your results. Valid values are:

COM - Commercial Region. The default.
ER - European Region.
FED - United States Federal Region.

`SRCCLR_TLS_EXPAND`

When set to TRUE, the SCA agent can use an expanded set of ciphers to connect to the Veracode Platform. When set to FALSE, the agent can only use FIPS-compliant ciphers. Valid values are:

TRUE - The default value for the Commercial and European Regions.
FALSE - The default and only valid value for the United States Federal Region.

`SRCCLR_SBOM_SCAN`

When set to the default value TRUE, the agent scans all found SBOMs when performing a --quick scan. When set to FALSE, the agent ignores any SBOMs it finds when performing a --quick scan.

`JAVA_OPTS`

Permits altering the behavior, or system properties, of the underlying Java runtime system that is used by the srcclr command.

`VIRTUALENV_PYTHON`

Specifies which Python interpreter version virtualenv uses when creating a virtual Python environment. The default value is the interpreter version used to install virtualenv on your machine.

`SRCCLR_CONFIG`

Provides an explicit means of specifying the scan configuration file location. If this variable is populated, the program will use that path in addition to the system and user locations, but is still subject to override by the --config command line flag. If it is populated but points to an invalid path, the program halts in error.

`SRCCLR_NPM_SCOPE`

Specifies the scope for scans of NPM and Yarn projects. Valid values are:

production or prod - Restricts scans to production dependencies, including the optional dependencies you can install. The default value.
development or dev - Restricts scans to development dependencies.
all - Scans production and development dependencies.

`SRCCLR_SCOPE`

For scope options, see the multi-language scan directives.

`https_proxy` or `http_proxy`

If you set either of these values, and they contain a URL that points to a proxy which speaks the HTTP proxy protocol, the agent uses them for outbound HTTP requests, just as curl and git behave. Also like the other programs, the agent accepts inline credentials in the URL, such as http://myUser:[email protected]. If the URL does not contain an explicit port, the traditional ports for the protocol of the URL are implicitly inserted: 80 for http:// and 443 for https://. Unlike those other programs, the agent accepts either environment variable name (https_proxy or http_proxy) and uses that proxy information for all HTTP requests. Be aware that proxy values in any configuration file provided to the agent, the default location or values provided by –config supersede any proxy specification in these environment variables.

You can also use scan directives as environment variables 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

`SRCCLR_DOWNLOAD_URL`

Downloads the SourceClear agent.

sca-downloads.veracode.com - The recommended URL
download.sourceclear.com - The old URL that will be eventually deprecated

`SRCCLR_WORKSPACE_SLUG`

Specifies the workspace for an SCA agent using the workspace slug.

SCA agent commands

This section lists the primary commands you can use with SCA agents, as well as arguments you can add to alter the functionality of each command.

`activate`

Activates your Veracode SCA agent with an initialization token and installs an agent.yml file to a directory of your choosing.

Example: $ srcclr activate

You can activate multiple agents on a single machine. In the instance where you are activating a second agent, you will be asked to enter a profile name. This allows the user to identify the agent key with which they are scanning. A suggestion for a profile name is the name of the Workspace associated with the agent.

`scan`

Performs a scan of a supported code repository, outputting vulnerability information for libraries in usage and, optionally, uploads information to the Veracode Platform. When scanning with an organization agent, append a workspace flag and slug after the scan command.

Syntax: you must perform the scan command in the correct syntax for your command tool:

Using the CLI

Workspace agent:

  $ srcclr scan --url https://github.com/veracode/example-java-maven --{parameter-1} --{parameter-2}

Organization agent:

$ srcclr scan --url https://github.com/veracode/example-java-maven --ws={workspace slug} --{parameter-1} --{parameter-2}

Using cURL

Workspace agent:

curl -sSL https://sca-downloads.veracode.com/ci.sh | sh -s scan --{parameter-1} --{parameter-2}

Organization-level agent:

curl -sSL https://sca-downloads.veracode.com/ci.sh | sh -s scan --ws={workspace slug} --{parameter-1} --{parameter-2}

Options

--ws=: scan using an organization agent into a specific workspace, using the workspace slug. For more information, see About Veracode SCA agent management.
--json: output the scan results in JSON format. Add ={filepath} to send the pure JSON output to a specific file. See Scan exports for details on output.
- Example: $ srcclr scan --json=/my/project
--no-graphs: do not include dependency graphs in the JSON output.
--allow-dirty: allow scans on repositories which contain differences that are not committed to the project.
--install-first: run the install target of your project before analyzing.
--unmatched: show coordinates for all unmatched libraries. Unmatched libraries are typically proprietary and unreleased versions of libraries.
--skip-compile: Java only. Do not compile the project before analyzing.
--loud: show raw build output.
--no-upload: prevent scan results from being uploaded to the Veracode Platform.
--do-not-collect: specify which information to not collect from git commit logs. Only supports the default value, emails.
--quick: perform a quick scan which does not require build tools. A lockfile is required.
--uri-as-name: use the exact source code management (SCM) URI as the project name.
--url: specify a remote Git URL to scan.
--recursive: perform a recursive scan on a directory structure.
--ref: use with --url to specify a branch or tag name to scan the specified branch or tag. Example: $ srcclr scan --url https://github.com/veracode/example-java-maven --ref 1.0.0
--scan-collectors: specify which build types to scan, rather than scanning all discovered build systems by default. See SCA agent scan directives for configuration options.
--skip-collectors: specify which build types to skip during the scan, rather than scanning all discovered build systems by default. See SCA agent scan directives for configuration options.
--skip-vms: specify whether to skip vulnerable methods analysis in your repository scan. Example: $ srcclr scan /my/project --skip-vms
--scan-analyzers: for container scans, specify which build types to scan, instead of scanning all discovered build tools. See SCA agent scan directives for configuration options.
--skip-analyzers: for container scans, specify which build types to skip during the scan, instead of scanning all discovered build tools. See SCA agent scan directives for configuration options.
--scope: to limit the dependency resolution to dependencies within a specified scope, see Multi-language scan directives see for configuration options. The Veracode SCA agent also supports scans that include per-scan directives known as scan directives. You can specify scan directives on a per-project basis by placing a srcclr.yml file at the root of the scan.

Example of srcclr.yml:

    scope: testCompile
    gradle_location: ../gradlew
    gradle_tasks: clean classes
    skip_collectors: gem

This example indicates that we only wish to include dependencies that are in the testCompile scope, or a scope from which testCompile inherits. It specifies that the gradlew file exists in the parent folder, and that we should execute using the clean and classes tasks. Last, it specifies that even though a Gemfile might exist in the repository directory, the agent should skip that particular build system. For details on all the scan directives, see SCA agent scan directives.

CLI output example

When a scan completes, the bottom of the output in your terminal includes a URL for the Veracode Platform where you can view the scan results in more detail.

Licenses
    Unique Library Licenses              3
    Libraries Using GPL                  0
    Libraries With No License            1
    
    Full Report Details                  https://sca.analysiscenter.veracode.com/teams/abzs0qx/scans/22679557

`debug`

Description: enables the debug mode on the Veracode SCA agent. This outputs additional information for identifying issues encountered when scanning.

Example: $ srcclr scan --debug

`test`

Description: test the environment in which the agent is installed and verify that all requirements for completing a scan for the specified package manager are present.

Options

--ant: perform an ANT-based test clone and scan operation.
--bower: perform a BOWER-based test clone and scan operation.
--cocoapods: perform a COCOAPODS-based test clone and scan operation.
--composer: perform a COMPOSER-based test clone and scan operation.
--gem: perform a GEM-based test clone and scan operation.
--glide: perform a GLIDE-based test clone and scan operation.
--go: perform a GO GET-based test clone and scan operation.
--godep: perform a GODEP-based test clone and scan operation.
--govendor: perform a GOVENDOR-based test clone and scan operation.
--gradle: perform a GRADLE-based test clone and scan operation.
--ivy: perform a IVY-based test clone and scan operation.
--maven: perform a MAVEN-based test clone and scan operation.
--npm: perform a NPM-based test clone and scan operation.
--pip: perform a PIP-based test clone and scan operation.
--sbt: perform a SBT-based test clone and scan operation.
--trash: perform a TRASH-based test clone and scan operation.
--yarn: perform a YARN-based test clone and scan operation.
--nuget: perform a NUGET-based test clone and scan operation.

Example: $ srcclr test --npm

`config`

Description: allows the user to list values from their agent.yml file.

Options

--get: display a single configuration value
--list: display the configuration in its entirety

Example: $ srcclr config --list

`lookup`

Description: use the agent to look up the release and vulnerability information found in the SCA Vulnerability Database for a single library.

Options

--json: required. Output the lookup results in JSON format. This is the only available output format of the lookup verb. See the example results output for details on output.
--coord1: the primary library name in all cases except for type=maven, where the first coordinate identifies the groupId in Maven nomenclature. The case sensitivity of the coord1 depends on whether the underlying registry distinguishes packages by case. PyPI, for example, is not case-sensitive while Maven is case-sensitive. In the case of Go libraries, coord1 should be the domain and top-level package name. For example: github.com/docker/docker
--coord2: optional, but required for Maven. If you include type=maven, this specifies the artifactId of the library to lookup.
--platform: optional. Specify the target platform of a library located in the registry, such as freebsd or py3, depending on the package and registry used.
--type: the type of registry that contains the library one is going to specify using the coord options. Acceptable values are displayed in lookup --help and are as follows:
- gem to identify a Ruby Gem dependency as one would find on rubygems.org
- maven to identify a Maven dependency as one would find on repo.maven.apache.org
- npm to identify a JavaScript dependency as one would find on npmjs.com
- pypi to identify a Python dependency as one would find on pypi.python.org
- cocoapods to identify a CocoaPods dependency as one would find on cocoapods.org
- go to identify a Go dependency as one would find on the common Go repositories such as github.com, bitbucket.org, gopkg.in, golang.org
- packagist to identify a PHP dependency as one would find on packgist.org
- nuget to identify a .NET dependency as one would find on nuget.org
--version - The version number, as specified in the registry that you identify with the --type parameter, of the library to lookup. For Go, the version can be:
- A release tag in the library repository
- A prefix of a commit hash of at least seven digits
- In v0.0.0-{datetime}-{hash} format

Example:

$ srcclr lookup --type=maven --coord1=org.springframework --coord2=spring-core \
                --version=4.1.0.RELEASE --json

Global options

You can use the following options with the SCA agent commands.

`--help`

Description: Displays a command summary.

Example: $ srcclr --help

`--profile=`

Description: If you activate multiple agents on one machine, Veracode prompts you to provide a profile name. This is an identifier you assign to this agent. Using the profile command you can choose which profile to use. Must be placed before the scan command.

Example: $ srcclr --profile=Engineering scan

`--config=CONFIG-FILENAME`

Description: Read in an additional configuration file that overrides the default one, described in CONFIG-FILENAME.

Example:$ srcclr --config=$HOME/.srcclr/agent-test.yml scan ~/Projects/test-java-maven

`--insecure`

Description: Suppress the file permission check for every configuration file provided, which includes the default one.

Example: $ srcclr --insecure scan --url https://github.com/veracode/example-java-maven

`--version`

Description: Print the current version and exit.

Example: $ srcclr --version

`--scope`

For scope options, see Multi-language scan directives.

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

Prerequisites​

SCA agent levels​

Workspace agents​

Organization agents​

Command-line interface​

Set up SCA agents​

Set up an SCA CLI agent​

Set up an SCA CLI agent using PowerShell​

Add your repo to your YUM repos​

Uninstall older agents using Homebrew​

Integrate an SCA CI agent​

Build and package managers​

Configure proxies​

Scan repos​

View workspace agents​

View organization agents​

Rename SCA agents​

Delete SCA agents​

Apply an organization agent to a workspace​

Regenerate SCA agent tokens​

Turn on the update advisor​

SCA agent configuration​

agent.yml parameters​

agentAuthorization​

apiUrl​

maxErrorLines​

proxyType​

proxyHost​

proxyPort​

proxyUsername​

proxyPassword​

region​

skipVersionCheck​

scmType​

scmToken​

scmUrl​

scmUsername​

scmPassword​

Environment variables​

SRCCLR_API_TOKEN​

SRCCLR_API_URL​

SRCCLR_REGION​

SRCCLR_TLS_EXPAND​

SRCCLR_SBOM_SCAN​

JAVA_OPTS​

VIRTUALENV_PYTHON​

SRCCLR_CONFIG​

SRCCLR_NPM_SCOPE​

SRCCLR_SCOPE​

https_proxy or http_proxy​

SRCCLR_DOWNLOAD_URL​

SRCCLR_WORKSPACE_SLUG​

SCA agent commands​

activate​

scan​

Using the CLI​

Using cURL​

Options​

CLI output example​

debug​

test​

Options​

config​

Options​

lookup​

Options​

Global options​

--help​

--profile=​

--config=CONFIG-FILENAME​

--insecure​

--version​

--scope​

SCA agent scan directives​

General​

scan_collectors​

skip_collectors​

scan_analyzers​

skip_analyzers​

vuln_methods_ignored_directories​

Prerequisites

SCA agent levels

Workspace agents

Organization agents

Command-line interface

Set up SCA agents

Set up an SCA CLI agent

Set up an SCA CLI agent using PowerShell

Add your repo to your YUM repos

Uninstall older agents using Homebrew

Integrate an SCA CI agent

Build and package managers

Configure proxies

Scan repos

View workspace agents

View organization agents

Rename SCA agents

Delete SCA agents

Apply an organization agent to a workspace

Regenerate SCA agent tokens

Turn on the update advisor

SCA agent configuration

`agent.yml` parameters

`agentAuthorization`

`apiUrl`

`maxErrorLines`

`proxyType`

`proxyHost`

`proxyPort`

`proxyUsername`

`proxyPassword`

`region`

`skipVersionCheck`

`scmType`

`scmToken`

`scmUrl`

`scmUsername`

`scmPassword`

Environment variables

`SRCCLR_API_TOKEN`

`SRCCLR_API_URL`

`SRCCLR_REGION`

`SRCCLR_TLS_EXPAND`

`SRCCLR_SBOM_SCAN`

`JAVA_OPTS`

`VIRTUALENV_PYTHON`

`SRCCLR_CONFIG`

`SRCCLR_NPM_SCOPE`

`SRCCLR_SCOPE`

`https_proxy` or `http_proxy`

`SRCCLR_DOWNLOAD_URL`

`SRCCLR_WORKSPACE_SLUG`

SCA agent commands

`activate`

`scan`

Using the CLI

Using cURL

Options

CLI output example

`debug`

`test`

Options

`config`

Options

`lookup`

Options

Global options

`--help`

`--profile=`

`--config=CONFIG-FILENAME`

`--insecure`

`--version`

`--scope`

SCA agent scan directives

General

`scan_collectors`

`skip_collectors`

`scan_analyzers`

`skip_analyzers`

`vuln_methods_ignored_directories`