Agent Management

SourceClear Software Composition Analysis

The SourceClear agent, also referred to as the scanner, is the program that builds and scans your code to find third party libraries and the vulnerabilities contained in those libraries.

Workspace agents let you scan projects and put their 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.

For organizations wishing to minimize setup for new workspaces, we offer agents at the organization level. This means that one agent can scan into any workspace. You simply identify which workspace at scan time using a flag or environment variable.

Workspace Agents

Users with the role of organization owner or organization administrator can manage any workspace agent.

Users with workspace administrator rights can manage agents for that particular workspace.

Organization-Level Agents

This feature is available to trial accounts and organizations with the Enterprise plan.

Within those organizations, users with the role of organization owner or organization administrator can create, view, update, and delete organization-level agents.

Workspace Agents

From your Portfolio list, click a workspace to open it.

Under the Manage Workspace section, click Agents.

Organization-Level Agents

Click the cog icon to navigate to the Manage Organization area.

Click Agents in the left navigation.

Creating and Deleting Agents

  • Click Actions > Create
  • Choose your desktop operating system or CI
  • For desktop operating systems:
    • Install the agent
      • Choose the tab showing 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.
    • Activate the agent
      • Copy the command to activate the agent and paste it in your terminal.
      • Copy the activate token and paste it in your terminal.
      • After entering your activation token, your agent.yml configuration file will be installed to the ~/.srcclr folder. If that file already exists you will be prompted to enter a profile name. This profile name allows you to choose which token you are using when scanning.
        • For workspace agents, the suggested naming scheme is the workspace name which the token is associated with.
        • For organization-level agents, if you plan on creating more than one to use with different teams or workspaces, it is suggested that you indicate that in the profile name.
    • Verify the agent (same as step 7 here)

Scanning with an Organization-Level Agent for Desktop Operating Systems

When scanning with an organization-level agent, append the workspace flag and slug after the scan command:

srcclr scan --ws=<workspace slug>

To find the workspace slug, select the desired workspace from the menu and copy the slug from the field below.

The workspace slug can also be found in the URL of the workspace when you are on any workspace page.

Scanning with an Organization-Level Agent for Desktop Operating Systems Using CI

For organization-level agents, it’s basically the same instructions as the workspace agent instructions (located in the Continuous Integration section here), except you also need to add an environment variable SRCCLR_WORKSPACE_SLUG to the appropriate config file. The value of this variable will be the same as above.

Renaming and Deleting Agents

To rename an agent, navigate to the Agents list at either the workspace or organization level, and click the pencil icon. Change the agent name and save.

To delete an agent, click the trash can icon. Deleting agents is permanent and cannot be undone. When you delete an agent, any subsequent scans using the token for that agent will fail.

Regenerating the Agent Token

To connect to your organization during scanning, SourceClear uses an agent auth token which acts as a password.

If another user gets access to your token, that person will be able to use the SourceClear 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-level agent 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.

To regenerate the token, click the Regenerate Token button. A new token will be displayed, and will only be displayed while you remain on this page. Copy this token and paste it into the relevant configuration file. Please keep the token safe. Remember to update your environment variables with the new token.

Downgrading From Trial or Enterprise Plans

Organization-level agents are available to trial accounts and organizations with the Enterprise plan. When your trial runs out, or if you downgrade from an Enterprise plan, your organization-level agents will cease to scan. To continue scanning, create workspace agents for each of the workspaces you wish to scan.