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.
Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into Subimage's managed vault. See Secrets for details.
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
- In Semgrep AppSec Platform, go to Settings → Tokens → API tokens and click Create new token.
- Copy the Secrets value. Semgrep shows it only once.
- 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 Foundon/api/v1/deployments. Read-only cannot read Semgrep Secrets findings, so Subimage skips Secrets on every sync. - Click Save.
- In Subimage, choose the Cloud tab in the Semgrep module.
- Enter the token in
semgrep_app_token, or provide its AWS Secrets Manager ARN. - Optionally set
semgrep_dependency_ecosystemsif you want Semgrep dependency data ingested. - If your Semgrep endpoint is private, set
tailscale_hostnameand run through a Subimage Outpost. - 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
- Run Semgrep CLI and produce JSON report artifacts for the repositories you want to ingest.
- Create a repository mapping YAML file and point
semgrep_oss_sourceat it. - In Subimage, choose the OSS tab in the Semgrep module.
- Enter the local path or object-store URI for the mapping file.
- Save the module configuration.
Repository Mapping File Requirements
The mapping file must:
- Be valid UTF-8 YAML.
- Contain a top-level
repositorieslist. - Give each repository entry
provider,owner,repo,url,branch, and a non-emptyreportslist. - Use
reportsentries 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_INrelationships for OSS findings, matching repository nodes must already exist in the graph. - For GitHub repositories, the
GitHubRepository.idmust match the repositoryurldeclared in the mapping file. - If matching repository nodes do not exist yet, Subimage can still ingest
SemgrepSASTFindingnodes, 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.