Integrate SCA CI agents

Create SCA CI agents to integrate SCA Agent-based Scan into most continuous integration (CI) systems, source code management (SCM) tools, and ticketing systems. The integration requires you to create an SCA CI agent, then add the agent token and scan command to your CI project.

SCA Agent-based Scan integrates into the build process to prevent the delivery of insecure software to production. It easily integrates with your continuous delivery workflow. You can also integrate SCA scanning in your repos using scripting.

Ensure your repositories have the supported languages and package managers.

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

By default, the agent you create is only visible to members of the workspace in which you created the agent. To allow visibility, invite teams to your workspace.

Before you begin:

• You have the Security Lead, Submitter, Workspace Administrator, or Workspace Editor role.
• Contact your IT department to confirm your client meets the requirements for setting up agent-based scans.

To complete this task:

1. In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.

2. Select Agent-Based Scan.

3. Select a workspace.

4. Select Agents > Actions > Create.

5. Select any option from the Integration Options section. The option you select does not affect the agent or your scan results.

6. Select Create Agent & Generate Token.

7. In your CI project, store your agent token as a secret environment variable called SRCCLR_API_TOKEN. See the documentation for your CI system for instructions on setting secret environment variables.

8. 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 SRCCLR_REGION environment variable to one of the following:

   • European region: ER
   • United States Federal region: FED

9. Add this command to your CI project to download the agent and start scanning:

   curl -sSL https://sca-downloads.veracode.com/ci.sh | sh

   For example, in GitLab, add the command after the after_script step in the .gitlab-ci.yml file.

   You can customize this command to enable additional scanning features.

10. Configure the agent and run scans.

Integrate with 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.

Integrate scanning with a script

You can add commands and environment variables to the script in your continuous integration tool to customize your SCA agent-based scans.

For all CI scripts, you must set the SRCCLR_API_TOKEN environment variable to successfully authenticate for scanning.

Custom SCA agent commands

The default functionality of the CI script used in the curl -sSL https://sca-downloads.veracode.com/ci.sh | sh command is to run the srcclr scan agent command in the current directory. Users can optionally specify their own custom command by appending -s -- {agent_commands} to the curl command. These examples use customized SCA commands with the CI script:

The CLI equivalent of:

srcclr test --maven

curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh -s -- test --maven

The CLI equivalent of:

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

curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh -s -- scan --url https://github.com/veracode/example-ruby --no-upload

Environment variables

You can use these environment variables in the scanning environment to enable various features when scanning in your development pipeline with this shell command: curl -sSL https://sca-downloads.veracode.com/ci.sh | sh.

DEBUG

Description: When enabled, provides more verbose output during the scan. The default is 0, which disables the variable.

Possible values: 0 to disable, 1 to enable

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | DEBUG=1 sh

OR

export DEBUG=1
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

NOCACHE

Description: When enabled, the Veracode SCA agent is not cached when the curl command is run. The default is 0, which disables the variable.

Possible values: 0 to disable, 1 to enable

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | NOCACHE=1 sh

OR

export NOCACHE=1
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

CACHE_DIR

Description: Allows the user to specify which directory location to store the Veracode SCA agent. The default value for this is the /tmp directory.

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | CACHE_DIR="/home/applications" sh

OR

export CACHE_DIR="/home/applications"
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

NOSCAN

Description: When enabled, the Veracode SCA agent does not perform a scan on the repository. The default is 0, which disables the variable.

Possible values: 0 to disable, 1 to enable

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | NOSCAN=1 sh

OR

export NOSCAN=1
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

SCAN_DIR

Description: Allows the user to specify which directory location to scan. The default value for is the directory from which the curl command runs.

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | SCAN_DIR="./path/to/dir" sh

OR

export SCAN_DIR="./path/to/dir"
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

SRCCLR_CI_JSON

Description: When enabled, the Veracode SCA agent outputs the scan results in JSON format. The default is 0, which disables the variable.

Possible values: 0 to disable, 1 to enable

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | SRCCLR_CI_JSON=1 sh

OR

export SRCCLR_CI_JSON=1
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

CUSTOM_JRE_DIR

Description: Allows the user to specify which JRE to use for the Veracode SCA agent. The default scan functionality is to provide supported JREs for both Debian-based and OS X operating systems. Specifying this value enables other operating systems to utilize SCA Agent-based Scan.

Example:

curl -sSL  https://sca-downloads.veracode.com/ci.sh | CUSTOM_JRE_DIR=/opt/jdk/jre/lib/amd64 sh

OR

export CUSTOM_JRE_DIR=/opt/jdk/jre/lib/amd64
curl -sSL  https://sca-downloads.veracode.com/ci.sh | sh

Use the SCA agent with an SCM other than Git

You can use the Veracode SCA agent to scan a repository that uses a source code management (SCM) system other than Git, including Subversion (SVN), Mercurial, and Team Foundation Version Control (TFVC).

The SCA agent normally interacts with a Git repository to learn the branch, commit, working directory state, and similar attributes to make the scan reports the most meaningful to the reader. However, not every organization uses Git and thus the agent needs a mechanism through which the scan data can be associated with the underlying source control metadata.

Connect SCM metadata to an SCA agent

The Veracode SCA agent accepts SCM metadata from the caller through the following environment variables.

Environment variable	Equivalent scan option	What it controls
SRCCLR_SCM_URI	--scm-uri	Required. The URI you use to connect to the SCM system. For example: https://svn.example.com/svn/repos or https://hg.example.com. NOTE: This value becomes the default project name in Veracode SCA after the first scan.
SRCCLR_SCM_REF	--scm-ref	Required. A meaningful name for the current state of the working directory, such as a branch, tag, or similar SCM concept.
SRCCLR_SCM_REF_TYPE	--scm-ref-type	Required. The type of reference specified in SRCCLR_SCM_REF. Accepted values (case-insensitive): branch, tag, or commit. The default value is commit.
SRCCLR_SCM_REV	--scm-rev	Required. The revision identifier for the current state of the working directory. Examples: a Subversion change number or a Mercurial revision ID.
SRCCLR_SCM_SUB_PATH	n/a	Optional. Use only if the project is located in a subdirectory within the SCM repository, such as with a multi-project Mercurial repository. If you use Subversion or similar directory addressable source control systems, we recommend specifying the full path to the project root as the SRCCLR_SCM_URI.
SRCCLR_NO_GIT=1	n/a	Optional. SCA agent-based scans require that your project be in a version control system, such as Git. To scan a project that is not in version control, set this variable to 1.

Example

Check out the source as you normally would and change to the working directory.

$ svn checkout https://svn.code.sf.net/p/properties-mvn/svn/ properties-mvn
$ cd properties-mvn

To gather the information, use the source control tool to inspect its status.

$ svn info
Path: .
Working Copy Root Path: /Users/mdaniel/.tmp/properties-mvn
URL: https://svn.code.sf.net/p/properties-mvn/svn
Relative URL: ^/
Repository Root: https://svn.code.sf.net/p/properties-mvn/svn
Repository UUID: a38e15f5-c4e9-4b0a-8018-68579ae2876f
Revision: 10
Node Kind: directory
Schedule: normal
Last Changed Author: ayanul
Last Changed Rev: 10
Last Changed Date: 2010-09-29 04:28:27 -0700 (Wed, 29 Sep 2010)

Now you can capture the relevant pieces of metadata in environment variables and invoke the srcclr scan command to begin scanning.

$ export SRCCLR_SCM_URI=https://svn.code.sf.net/p/properties-mvn/svn
$ export SRCCLR_SCM_REF=trunk
$ export SRCCLR_SCM_REF_TYPE=branch
$ export SRCCLR_SCM_REV=10
$ srcclr scan

The results print a summary to the terminal and provide a hyperlink to the full details in the Veracode Platform.