Contrast Security

Applications, vulnerability findings (traces) and libraries for one Contrast Security organization, through the TeamServer “ng” REST API (/Contrast/api/ng/<orgUuid>/...), on SaaS or self-hosted. Every command reads; none changes anything. Verification level: unit.

Supported versions: The oldest Contrast TeamServer version toil supports hasn’t been established. toil calls the TeamServer “ng” REST API with an API key and a service key. No release has been verified yet.

Credential

Three values, all from User Settings → Your Keys in Contrast: your username, the organization’s API key and your service key, plus the organization UUID shown on the same page. toil sends two headers on every request:

• Authorization: base64(username:serviceKey), with no Basic prefix, which is Contrast’s own format
• API-Key: <apiKey>

There is no password or browser login. A redirect to another host is refused, so the API key never leaves the configured instance.

Configuration

There’s no CI fallback variable.

Environment variables (CI, or a one-off shell):

export TOIL_CONTRAST_BASE_URL=https://contrast.imagile.dev
export TOIL_CONTRAST_ORG_UUID=abc12345-0000-0000-0000-000000000000
export TOIL_CONTRAST_USERNAME=you@example.com
export TOIL_CONTRAST_API_KEY=<your API key>
export TOIL_CONTRAST_SERVICE_KEY=<your service key>

Or ~/.toil/config.json:

{
  "version": 2,
  "connections": {
    "corp-contrast": {
      "area": "contrast",
      "baseUrl": "https://contrast.imagile.dev",
      "orgUuid": "abc12345-0000-0000-0000-000000000000",
      "username": "you@example.com"
    }
  },
  "defaults": { "contrast": { "connection": "corp-contrast" } }
}

apiKey and serviceKey never go in this file; a plaintext one there is refused with CONFIG_INVALID. Run toil connections add corp-contrast --area contrast (or toil connections login corp-contrast for an existing connection) to keep them in the OS credential store, or set the env vars.

Commands

data is Contrast’s own response, as it came, except for library get.

• app list: List applications in the organization.
• app findings <app>: List vulnerability findings for an application. --severity and --status are sent as severities and statuses, as typed; a comma list such as HIGH,CRITICAL keeps its commas.
• finding get <app> <trace>: Get details for a specific vulnerability finding.
• app libraries <app>: List libraries used by an application, as shown on the Libraries tab.
• library get <app> <hash>: Get details for a specific library used by an application, by hash. It reads the application’s libraries 25 at a time until one’s hash matches exactly, or a page has fewer than 25, and returns that one library object. No match is NOT_FOUND. It stops with an error after 1,000 pages.

app list, app findings and app libraries take --limit (default 25) and --offset (default 0), sent to the server as given; they return one page, and you page by hand. The application ID, the trace ID and the org UUID go into the URL path as typed.

Over MCP the same commands are tools named after the path, with spaces as underscores (contrast_app_findings, contrast_library_get), taking the fields app, trace, hash, limit and offset.

toil contrast app list --limit 50
toil contrast app findings abc12345-0000-0000-0000-000000000000 --severity HIGH,CRITICAL
toil contrast library get abc12345-0000-0000-0000-000000000000 0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c