setup

Semgrep

Purpose

Pulls code security findings into Subimage from either Semgrep Cloud Platform or Semgrep OSS JSON reports. Correlating these with infra metadata helps prioritize fixes.

tip

Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.

important

If your Semgrep Cloud endpoint is self-hosted and not publicly reachable, set tailscale_hostname and run the collector via a Subimage Outpost.

Configuration Modes

Subimage supports two Semgrep modes:

  • Cloud: pull findings and dependency data from Semgrep Cloud Platform APIs
  • OSS: ingest Semgrep CLI JSON reports through a repository mapping file

Choose the mode in the module configuration blade before saving.

Cloud Setup

Fields

Field Secret? Description
semgrep_app_token Yes Semgrep API token with the Web API scope
more organizations Yes (Optional) Other Semgrep organizations to sync, each with its own token
semgrep_dependency_ecosystems No (Optional) Comma-separated ecosystems such as npm,pip for dependency sync
tailscale_hostname No (Optional) Internal hostname resolved via Outpost

Steps

  1. In Semgrep AppSec Platform, go to Settings → Tokens → API tokens and click Create new token.
  2. Copy the Secrets value. Semgrep shows it only once.
  3. Under Token scopes, select Web API. Scopes are mutually exclusive. The default Agent (CI) scope cannot call the API, and the sync fails with 404 Not Found on /api/v1/deployments. Read-only cannot read Semgrep Secrets findings, so Subimage skips Secrets on every sync.
  4. Click Save.
  5. In Subimage, choose the Cloud tab in the Semgrep module.
  6. Enter the token in semgrep_app_token, or provide its AWS Secrets Manager ARN.
  7. Optionally set semgrep_dependency_ecosystems if you want Semgrep dependency data ingested.
  8. If your Semgrep endpoint is private, set tailscale_hostname and run through a Subimage Outpost.
  9. Save the module configuration.

Multiple Organizations

A Semgrep token belongs to one organization. To sync more than one, add each extra organization under more organizations with its slug and a token created in that organization (steps 1 to 4 above, signed in to it). The slug is the part after /orgs/ in your Semgrep dashboard URL; pasting the whole URL works too. All organizations share the dependency ecosystems and Outpost settings above.

An organization that fails to sync does not stop the others. The sync is marked degraded and its logs name the organization that failed. If two tokens turn out to belong to the same organization, the second one is reported as failed instead of being synced twice.

Removing an organization from the list stops syncing it. The data it already synced stays in the graph.

OSS mode reads one repository mapping file; list every repository in that file rather than configuring several sources.

OSS Setup

Fields

Field Secret? Description
semgrep_oss_source No Repository mapping file path or URI for OSS ingestion

Steps

  1. Run Semgrep CLI and produce JSON report artifacts for the repositories you want to ingest.
  2. Create a repository mapping YAML file and point semgrep_oss_source at it.
  3. In Subimage, choose the OSS tab in the Semgrep module.
  4. Enter the local path or object-store URI for the mapping file.
  5. Save the module configuration.

Repository Mapping File Requirements

The mapping file must:

  • Be valid UTF-8 YAML.
  • Contain a top-level repositories list.
  • Give each repository entry provider, owner, repo, url, branch, and a non-empty reports list.
  • Use reports entries that each point to exactly one Semgrep OSS JSON artifact.

For sharded or monorepo scans, list each JSON artifact separately under reports. Do not point a reports entry at a directory or object-store prefix containing multiple files.

Example:

repositories:
  - provider: "github"
    owner: "simpsoncorp"
    repo: "sample_repo"
    url: "https://github.com/simpsoncorp/sample_repo"
    branch: "main"
    reports:
      - "/path/to/sample_repo-semgrep.json"
  - provider: "github"
    owner: "different-org"
    repo: "different-repo"
    url: "https://github.com/different-org/different-repo"
    branch: "main"
    reports:
      - "s3://security-artifacts/semgrep/different-repo/report-1.json"
      - "s3://security-artifacts/semgrep/different-repo/report-2.json"

OSS Prerequisites And Behavior

  • Semgrep OSS JSON does not include repository identity, so the repository mapping file is required.
  • To create FOUND_IN relationships for OSS findings, matching repository nodes must already exist in the graph.
  • For GitHub repositories, the GitHubRepository.id must match the repository url declared in the mapping file.
  • If matching repository nodes do not exist yet, Subimage can still ingest SemgrepSASTFinding nodes, but they will not attach to repositories.

Notes

  • Cloud-only Semgrep fields such as finding state, fix status, opened time, and assistant data are only populated for Semgrep Cloud findings.
  • OSS mode is aimed at Semgrep SAST findings from Semgrep CLI JSON artifacts, not Semgrep Cloud API data.