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.

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

Steps

1. In Semgrep Cloud, open Organization Settings → API Tokens.
2. Create a token with org.read scope.
3. In SubImage, choose the Cloud tab in the Semgrep module.
4. Enter the token in semgrep_app_token, or provide its AWS Secrets Manager ARN.
5. Optionally set semgrep_dependency_ecosystems if you want Semgrep dependency data ingested.
6. If your Semgrep endpoint is private, set tailscale_hostname and run through a SubImage Outpost.
7. Save the module configuration.

OSS Setup

Fields

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.