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

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.

Set up SCA agents

You can set up SCA CLI agents on your desktop, for running scans locally using a CLI, or integrate SCA CI 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.

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.

Scan repos

After setting up an SCA agent, use the scan command to scan your repos. 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:

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

View organization agents

Before you begin:

You must have the Security Lead role.

To complete this task:

1. In the Veracode Platform, select Scans & Analysis > Software Composition Analysis.
2. Select Agent-Based Scan.
3. 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:

1. In the Veracode Platform, navigate to the Agents page at either the workspace or organization level.
2. Select an agent.
3. Select the pencil icon.
4. Enter the new agent name.
5. 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:

1. Navigate to the Agents page at either the workspace or organization level.
2. Select an agent.
3. Select the trash can icon.
4. 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 might 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:

1. In the Veracode Platform, navigate to the Agents page at either the workspace or organization.
2. Select an agent.
3. Select Regenerate Token. A new token displays. If you close the page, the token disappears, and you must generate it again.
4. Copy this token and paste it into the relevant configuration file.
5. 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:

1. Add the --update-advisor argument to your command or build script. For example:

   EXTRA_ARGS='--update-advisor'

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