Choose the route that matches your report or account. Each route uses a different source of finding IDs.
| Starting point | What to collect | Destination |
|---|---|---|
| CLI or CI report | A Code-only JSON or self-contained SARIF 2.1.0 file, optionally gzipped. Native JSON keeps Semgrep severity and available snippets. | Local or Cloud |
| Hosted AppSec Platform MCP | Selected rule-based Code (SAST) findings from a verified project and Git ref. | Local or Cloud |
| Guardian in Codex | Selected Code or Supply Chain findings through the connected Guardian account. | Local or Cloud |
| Selected Web API IDs | Original project response and SAST findings pages for one full Git ref. Use the SDK to save a selection or import it directly. | Local or Cloud |
| Whole Platform project | All findings for one project, full ref and product using a Web API token. | Local or Cloud |
From the scanned checkout root, choose a saved report or run Semgrep in the same shell.
Saved report. Set the path to your Code report. For a semgrep ci
artifact, check that the job scanned only Code. The policy and baseline
determine which matches the report contains. Exit 1 can mean the job found
blocking matches and produced a valid report.
semgrep_report=../reports/semgrep.jsonRun Semgrep. Supply your SAST rules and write the JSON to a private directory outside the checkout. Semgrep CLI reference
semgrep_report=
report_dir=$(mktemp -d) &&
semgrep scan --config /path/to/sast-rules.yaml --json-output "$report_dir/semgrep.json" . &&
semgrep_report="$report_dir/semgrep.json"Preview the report. Replace the example URL with the checkout's credential-free HTTP(S) URL. Use a stable source key for the organization, project and branch.
codex-security publish findings "$semgrep_report" --to local --repository . \
--provider semgrep --source-repository-url https://github.com/example/project \
--source-key example/project/main --dry-run --format jsonCheck the findings, exclusions and source URL. If the preview has no accepted findings, verify the URL against the checkout's Git remote yourself. Keep the same URL and key when you save locally or publish to Cloud.
Native JSON retains the result, rule, CWE IDs, range, snippets and ignored
state when present. SARIF retains the selected rule and result, including
traces and fixes. SARIF error imports as high even if Semgrep assigned
critical severity. Check Cloud exclusions for deeply nested traces.
Semgrep output fields
The match ID comes from JSON extra.fingerprint or SARIF matchBasedId/v1.
Under the same source key and repository, the fingerprint lets you update a
match when it moves. If the fingerprint is missing or says requires login,
the ID comes from the rule, literal path and range. Moving that match
creates a new record. Imported evidence and identity
For CLI/CI JSON and SARIF, use SAST-only rules. The reader excludes results
it recognizes as Supply Chain or Secrets, but SARIF can omit product metadata.
Scan errors or an unsuccessful SARIF invocation stop the import. Direct artifact URIs and native
%SRCROOT% paths can supply locations. The reader preserves the scanner's path
spelling, including backslashes in POSIX filenames and Windows paths.
Indexed artifacts and unresolved bases
stay in the raw evidence and need a fingerprint for identity. Keep the original
report for run-wide inventories, matching explanations and timing. Individual
findings keep their own match data.
If you call the JSON or SARIF normalizer from the SDK, pass sourceRepositoryUrl.
When calling prepareNormalizedLocalImport directly, pass the original SARIF
repository references in the third argument's sourceRepositories. Use
{ url, platform: "github" } for a verified custom GitHub host.
Use Semgrep’s hosted AppSec Platform MCP (beta) at semgrep.dev to import
existing rule-based Code (SAST) findings. You can save the same capture to a
local workbench. Workspaces with Semgrep import enabled in Codex Security
Cloud can also publish to a private findings inbox or a connected repository.
Add the read-only server to Codex. Sign in to the Teams or Enterprise organization (including trials) that owns the project. If adding the server completes browser sign-in, skip the second command.
codex mcp add semgrep --url https://semgrep.dev/api/mcp/read-only
codex mcp login semgrepReload MCP servers or start a new Codex session. Ask Codex to list open Code findings for your repository and full Git ref, then choose the IDs you want to import. For example, give Codex this request with your own values:
Use the hosted Semgrep MCP to capture rule-based Code findings
101and103fromhttps://github.com/example/projectonrefs/heads/main. Save the capture to/path/to/private/capture.jsonfor the Codex Security hosted MCP import example.
For the capture, use semgrep_account to identify the organization and
ProjectsService_ListProjects to match the project by its SCM URL. Its
display name can differ from the repository path. Call
ProjectsService_GetProject for that project and IssuesService_ListIssues
with body.issueTypes: ["ISSUE_TYPE_SAST"] and the project ID, full ref
and requested string IDs in body.filter.repositoryIds, refs and ids.
Follow the cursor until every selected ID is accounted for. Save the
original selected structuredContent.issues rows programmatically, including
the nested issue and sibling fields. This captures list-level evidence.
For snippets or dataflow traces, inspect the issue with IssuesService_GetIssue. The capture contains deploymentId
(string), ref, findingIds (requested strings), project (from
structuredContent.project) and issues (the selected rows).
Semgrep connection and authentication guide
Copy the import example and capture into a private directory outside the checkout. From that directory, install the SDK used by the example:
npm install @openai/codex-security@0.9.1Local workbench. In your own terminal, compare the intended remote's
effective fetch URL (git -C /path/to/checkout remote get-url origin)
with the capture’s project.url. A remote URL can contain credentials.
Keep it out of the Codex transcript. For a custom transport helper, verify
its configured target. Preview using the root of that worktree.
node semgrep-hosted-mcp.mjs capture.json /path/to/checkoutAfter checking the source URL, checkout and selected findings, save the same capture and read back the records.
node semgrep-hosted-mcp.mjs capture.json /path/to/checkout --save
./node_modules/.bin/codex-security findings imported /path/to/checkout --format jsonCodex Security Cloud. Your Cloud workspace must support the Semgrep provider separately from your Semgrep MCP access. The SDK also needs a file-backed ChatGPT sign-in. If you need one, run these commands from the private example directory and choose the intended account. Keep the same state directory for previews, saves and retries.
export CODEX_SECURITY_STATE_DIR="$PWD/cloud-state"
mkdir -p -m 700 "$CODEX_SECURITY_STATE_DIR" "$CODEX_SECURITY_STATE_DIR/codex-home"
CODEX_HOME="$CODEX_SECURITY_STATE_DIR/codex-home" codex login -c 'cli_auth_credentials_store="file"'Pass cloud and the connected repository’s SCM URL. If several connectors
share the URL, use the intended Cloud repository ID instead. Check the
account, repository, selected findings and exclusions before confirming.
node semgrep-hosted-mcp.mjs capture.json cloud https://github.com/example/projectIf the repository resolves but the preview reports HTTP 400 for the Semgrep source, check that Cloud import is enabled for Semgrep in that workspace. You can use the same capture locally while waiting for access. After a successful Cloud preview, save and review the receipt.
node semgrep-hosted-mcp.mjs capture.json cloud https://github.com/example/project --saveIf the preview shows privateImport, check the completed private job and
its counts. If it shows repository requests, check the receipts and verified
count for the selected reports. Keep the capture and source key for retries.
Verify the Cloud import · Resume an interrupted submission
Sign in to Semgrep Guardian for Codex. Ask Codex to import the selected Code or Supply Chain findings from Guardian into the local workbench or the matching Cloud repository. Specify the deployment, repository and full Git ref. Guardian handles authentication through its existing connection.
Codex calls get_semgrep_sast_findings or get_semgrep_supply_chain_findings
with that scope. If you already selected rows from that tool, Codex can reuse
the successful response. It saves the exact string IDs and original selected
rows from structuredContent.findings. Guardian returns only the repository
name, so verify its SCM URL before saving the capture. The importer checks that URL against the checkout or the selected Cloud repository.
A missing or ambiguous selected ID stops the import. Guardian defaults to 20
open or reviewing results and returns at most 1,000 per call.
For SDK callers, guardianClient below is your connected Guardian MCP client.
Pass the filters used for your selection, including states for any closed or
ignored findings. Save the capture in a private directory outside the checkout.
import { writeFile } from "node:fs/promises";
import { collectSelectedSemgrepGuardianFindings } from "@openai/codex-security";
const capture = await collectSelectedSemgrepGuardianFindings(
{
request: {
name: "get_semgrep_sast_findings",
arguments: {
deployment_name: "example",
repository_name: "example/project",
ref: "refs/heads/topic",
},
},
findingIds: ["123"],
sourceRepositoryUrl: "https://github.com/example/project",
},
{ callTool: (request) => guardianClient.callTool(request) },
);
await writeFile("guardian.json", JSON.stringify(capture), {
flag: "wx",
mode: 0o600,
});Preview the selected findings for the intended destination.
codex-security publish findings /path/to/private/guardian.json --provider semgrep \
--to local --repository /path/to/project --source-key example/project/topic --dry-run --format jsonFor Cloud, replace --to local --repository /path/to/project with
--to cloud --repository https://github.com/example/project, using the URL
or Cloud ID of the repository you verified. After reviewing the destination,
findings and exclusions, repeat without --dry-run and confirm. Keep the
same capture and source key for a retry.
For normalized SDK imports, select the semgrep provider and keep each generated
Guardian ID with its original finding and collection scope. The repository URL
in each finding must agree with the report's mapping.
In the preview, check the rule and message in evidence.title and
evidence.description, the selected ref in branch, and the file and
starting line in locations. The verified SCM URL identifies the repository.
The original Guardian row is in source_data.finding. Guardian supplies
no end line, CWE IDs, package versions or fix versions in this summary. Guardian and Web API records keep
separate identities even when their IDs look identical. To verify a pair,
identify the same occurrence independently by deployment, mapped project,
product, full ref, rule and location. Then compare the complete ID strings,
preserving every digit.
Use these steps to select individual SAST findings by their Web API IDs.
With a read-authorized Web API token, save the native
project response
and the Findings API pages
for that deployment, project ID and fully qualified Git ref (for example,
refs/heads/release or refs/tags/release), using issue_type=sast and
dedup=false. Read through the pages until you have the requested IDs. Use a
project with an HTTP(S) repository URL.
Each selected finding must match the requested ref. When the finding includes
a repository URL or project ID, each must match the selected project. If the URL
is absent, the native project ID and full repository name must match the decoded
path of the project URL.
Pass the response text directly to the selector to preserve numeric IDs and other numeric evidence exactly. Keep the responses and selection together in a private directory outside the checkout. Run this example in that directory with the SDK installed. Local preview compares the project URL with the checkout's fetch URLs offline. If it cannot read the checkout's legacy remote metadata, add a named fetch URL you have verified against that project.
import { readFile, writeFile } from "node:fs/promises";
import { selectSemgrepPlatformFindings } from "@openai/codex-security";
const selected = selectSemgrepPlatformFindings({
deployment: "example",
ref: "refs/heads/release",
projectResponse: await readFile("project.json", "utf8"),
findingsResponses: [await readFile("page-0.json", "utf8")],
findingIds: ["101", "103"],
});
await writeFile("selected.json", JSON.stringify(selected), {
flag: "wx",
mode: 0o600,
});From the directory that contains selected.json, preview the saved selection for the local checkout.
codex-security publish findings selected.json --to local --provider semgrep \
--repository /path/to/project --source-key example/project/release/platform --dry-run --format jsonFor Cloud, preview the same file and source key against the connected repository.
codex-security publish findings selected.json --to cloud --provider semgrep \
--repository https://github.com/example/project --source-key example/project/release/platform --dry-run --format jsonCheck the repository, finding IDs and exclusions for the destination you chose.
Cloud verifies the project's repository. After review, repeat the matching
command without --dry-run and confirm. Verify the import.
To preview the saved file with the SDK, run this in the same private directory.
After checking the destination and exclusions, call await publication.publish()
on the prepared object to confirm.
import { prepareExternalPublication } from "@openai/codex-security";
const publication = await prepareExternalPublication("selected.json", {
provider: "semgrep",
repository: "https://github.com/example/project",
sourceKey: "example/project/release/platform",
});
console.log(JSON.stringify(publication.preview, null, 2));If you already have an in-memory selection, call
normalizeSemgrepPlatformFindings(selected, repositoryUrl, "cloud") and
pass the result to prepareNormalizedExternalPublication().
Use the project and SAST responses described above.
On each page containing a selected ID, the SDK checks every row for conflicting
product information. Where rows contain only shared fields, the request's
issue_type=sast filter establishes the product.
Check the project and ref. Use the full ref from the findings. Verify the checkout's credential-free
HTTP(S) URL. The native project.url must match it exactly. Check the
repository fields on each selected finding.
- If a finding has a
repository.url, it must match the verified URL exactly. That URL is enough when the ID is absent, even if display names differ. If several projects share the URL and ref, choose IDs from the intended project. - If a finding supplies
repository.id, it must matchproject.id. A finding without a URL also needs the matching ID and arepository.nameequal to the decoded, namespace-qualified URL path, such asexample/project.
Preview the selection.
In a Node.js project you control outside the scanned checkout, install
@openai/codex-security and save this script as preview-semgrep.mjs.
Set the deployment, ref, repository URL, source key and finding IDs. Use
positive decimal strings without leading zeros to preserve 64-bit IDs.
import { readFile } from "node:fs/promises";
import {
normalizeSelectedSemgrepPlatformFindings,
prepareNormalizedLocalImport,
} from "@openai/codex-security";
const [checkout, projectFile, ...findingsFiles] = process.argv.slice(2);
const sourceRepositoryUrl = "https://github.com/example/project";
const selected = normalizeSelectedSemgrepPlatformFindings({
deployment: "example",
ref: "refs/heads/release",
sourceRepositoryUrl,
projectResponse: await readFile(projectFile, "utf8"),
findingsResponses: await Promise.all(
findingsFiles.map((file) => readFile(file, "utf8")),
),
findingIds: ["101", "103"],
});
const prepared = await prepareNormalizedLocalImport(
selected,
{
provider: "semgrep",
sourceKey: "example/project/release/platform",
repository: checkout,
},
{ sourceRepositories: [{ url: sourceRepositoryUrl }] },
);
console.log(JSON.stringify(prepared.preview, null, 2));From your SDK project, pass the checkout, project response and each findings page as absolute paths.
node preview-semgrep.mjs /path/to/checkout /path/to/reports/semgrep-project.json \
/path/to/reports/semgrep-findings-1.jsonCheck the repository, findings and exclusions. To save the selection, append
await prepared.import() to a copy of the script and run the copy with the
same inputs. Read back the local records.
Each occurrence uses the deployment, project ID, SAST product, full ref and
native finding ID. Reuse the same source key for later imports. The stored
evidence includes the selected finding and the project's ID, name and URL.
The SDK preserves large positive IDs exactly. Key order and equivalent numeric
spellings (such as 2 and 2.0) leave the stored record unchanged.
The preview excludes findings that lack both a native rule name and a message. It verifies the selected project's repository even when every finding is excluded. Only repository-relative files become locations. URI-like and directory-only paths stay in the native evidence.
With a Web API token in SEMGREP_APP_TOKEN, collect all findings returned for a
project, exact ref and product. The collector looks up the project ID, requests
every page with server-side deduplication disabled, and stops on a failed or
overlapping page. Offset pagination does not provide a point-in-time snapshot.
For a multi-page result the collector also checks whether the first page's
membership has changed. Retry the collection if it reports a change.
Troubleshoot collection errors and rate limits.
Run the following commands from a trusted working directory outside the project checkout. Each collection gets a new owner-only file. A failed collection leaves earlier exports available for replay.
report=$(mktemp ./semgrep-backlog.XXXXXX) &&
codex-security import semgrep example/project --deployment example \
--ref refs/heads/topic --semgrep-product sast --format json > "$report" &&
codex-security publish findings "$report" --to local --repository /path/to/project \
--provider semgrep --source-key example/project/topic --dry-run --format jsonTo preview this saved backlog in Cloud, keep its source key and choose the authorized repository.
codex-security publish findings "$report" --to cloud --provider semgrep \
--repository https://github.com/example/project --source-key example/project/topic --dry-run --format jsonCheck the finding IDs and exclusions, then confirm the import for the chosen destination.
Use --semgrep-product sca for Supply Chain or ai_sast for AI-powered
detection. The default is sast. Use --source-repository-url on collection
when the project has no repository URL. The report records that mapping in
sourceRepositoryUrl, and stored finding evidence retains a null native project URL.
For SSH projects, the report stores the original address in nativeProjectUrl and the resolved HTTP(S) address in project.url.
It records any supplied mapping separately. Save the complete output from a successful
command. The importer checks the recorded finding count and repository/ref
claims. It retains each original finding as JSON text so large IDs survive replay.
A finding that identifies its repository only by name can use the project name,
the Git URL path, or the final path component of either. For any other name,
at least one finding in the collection must pair that name with the project's
repository ID or a matching repository URL. That finding can appear on any
page. Collection fails if the name has no such match. When one finding proves another
finding’s alias, the importer saves the verified label and resolved project ID in
source_data.repositoryWitnessJson on the name-only finding. The proving finding
retains its original repository fields in source_data.semgrepPlatformFindingJson.
SDK callers can pass a verified GitHub Enterprise repository as
sourceRepositories: [{ url, platform: "github" }] to
collectSemgrepPlatformFindings and the local reader. The reference must match
the selected project. It allows equivalent GitHub path casing, .git suffixes
and supported SSH URLs on that host.
To import a collected backlog with the TypeScript SDK, pass the normalized report to the local importer. Reuse the source key when replaying the report. You may filter the normalized findings array and retain the original read count. Only submitted findings are imported.
const findings = normalizeSemgrepPlatformFindings(report);
const prepared = await prepareNormalizedLocalImport(findings, {
provider: "semgrep",
sourceKey: "example/project/topic",
repository: checkout,
});
await prepared.import();Supply Chain findings include native package versions, matching fix recommendations and advisory IDs when Semgrep supplies them. With the same source key, importing identical Code findings that qualify for individual selection reports them as unchanged when switching between a selection and a full collection. See the Semgrep Findings API.
For an older semgrep-platform-findings/v1 export, rerun cs import semgrep
with the selected deployment, project, product and ref to collect a current export.
Check its IDs and scope before saving or publishing it.
Semgrep's native signed 64-bit finding IDs match across file and SDK imports. Keep the original spelling and JSON type of each selected ID and the full Git ref in the saved capture.
Repository mapping. Local preview compares the project URL with the checkout's
named fetch URLs. For an IP address, use its canonical spelling, such as
127.0.0.1 or [::1]. For an internationalized SSH hostname, use its ASCII
(Punycode) spelling. A verified custom host can be supplied in the
SDK's sourceRepositories option when selecting and preparing findings.
Use platform: "github" for GitHub Enterprise or platform: "gitlab" for a
self-managed GitLab instance. The latter allows the usual .git suffix.
Native evidence. Each selection keeps the native row as JSON text under
source_data.semgrepPlatformFindingJson, including locations that cannot be
mapped to the checkout. A valid relative location.file_path preserves its
spelling, including literal backslashes. Reordering JSON keys leaves stored
evidence unchanged. Use a separate source key for CLI scans.
Normalized SDK records. Keep each generated source_finding_id with its
native row and original deployment, project, ref and product. If you assign
your own opaque ID, retain that scope in a marked Platform batch. The SDK checks
the serialized native row. Keep unrelated metadata in a separate field.
Cloud retries. Cloud checks the original project's repository, including for Supply Chain findings without a typed repository field. Retry the original selection with the same account and destination. Retry a Cloud submission.