Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(plugin): choose configured tools for scanner and Cloud findings (#2213)

Michael D'Angelo3b6be79771a0
diff --git a/docs/plugin-connectors.md b/docs/plugin-connectors.md
index 3157e3fee..ce1fe6b97 100644
--- a/docs/plugin-connectors.md
+++ b/docs/plugin-connectors.md
@@ -1,12 +1,19 @@
# Plugin connectors
-Codex Security uses optional connected apps for ticket intake and finding tracking. Their identities are declared in `plugins/codex-security/.app.json`.
-
-| App | Workflows |
-| --------- | ------------------------------------------------- |
-| Linear | Ticket intake and finding tracking |
-| GitHub | Finding intake, source lookup, and issue tracking |
-| Atlassian | Jira Cloud ticket intake and finding tracking |
+Codex Security uses optional connected apps for Cloud reads, finding intake
+and tracking. The [app manifest](../plugins/codex-security/.app.json)
+declares their identities.
+
+| App | Workflows |
+| -------------------- | --------------------------------------------------------- |
+| Codex Security Cloud | Read existing findings, evidence, reports and scan status |
+| Linear | Ticket intake and finding tracking |
+| GitHub | Finding intake, source lookup and issue tracking |
+| Atlassian | Jira Cloud ticket intake and finding tracking |
+
+For scanner imports, use a connected tool or signed-in CLI to obtain the
+requested records. Follow the [scanner import guide](scanner-imports/README.md)
+to select and preview the evidence for your destination.
Finding tracking and CLI publication share issue associations when they use the same local state directory, including reuse across scan occurrences. The tracking skill reads them with `get_codex_security_finding_issues` and records accepted writes or verified reuse with `record_codex_security_finding_issues`. Provider reads still confirm saved candidates and search for unrecorded duplicates. Accepted writes remain recorded even when follow-up reads fail. The tools accept sealed scan bundles without requiring their original local scan history and keep receipts outside those bundles.
diff --git a/docs/scanner-imports/README.md b/docs/scanner-imports/README.md
index 619dd2506..d72dcb32f 100644
--- a/docs/scanner-imports/README.md
+++ b/docs/scanner-imports/README.md
@@ -3,6 +3,15 @@
Choose the guide for your report. Each guide shows how to preview the findings
in a local checkout and which source key to reuse on later imports.
+Use a supported report or retrieve the full records for the requested repository
+and ref with a connected tool or signed-in CLI. Fetch selected IDs directly when
+the provider supports it. If a saved report or collector covers more findings,
+use the provider's selection controls or retain only the selected native records
+where the report format permits. Check the accepted findings and their evidence
+in the JSON preview against the requested selection before saving or publishing.
+Use an API response only for an input and destination supported by the provider
+guide. Otherwise, ask for a supported report. A fresh scan produces new results.
+
| Guide | Supported input |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Amazon Inspector](inspector.md) | Inspector2 `ListFindings` JSON for one Code Security repository |
diff --git a/plugins/codex-security/skills/cloud-findings/SKILL.md b/plugins/codex-security/skills/cloud-findings/SKILL.md
index e75ddb7ca..a33f9a2f7 100644
--- a/plugins/codex-security/skills/cloud-findings/SKILL.md
+++ b/plugins/codex-security/skills/cloud-findings/SKILL.md
@@ -24,6 +24,8 @@ For a finding link, accept the selected Cloud `webOrigin` with the path `/codex/
## List and inspect findings
+When the findings list or detail tool offers `api_version`, select `v2` for requests that include imported scanner findings. The default `v1` view covers native findings. For an imported-only list, also set `source` to `imported` if exposed. Use only provider values advertised by the selected tool. If you filter returned evidence locally, follow every page in the requested scope and say how you filtered it.
+
Use `defense_factory_findings_list` with the discovered repository URL in `repo` and the user's filters; `repo` accepts comma-separated URLs, not repository IDs. Workflow tools use the returned repository ID in `repo_id`. Filters may include severity (`criticality`), lifecycle `status`, `source`, `q`, `path_prefix`, `start_at`, `end_at`, `scan_id`, `review_run_id`, `validated`, `has_patch`, `author`, and `assignee`; use the tool's current schema for available filters and their accepted values. `assignee` accepts comma-separated recorded user emails and is separate from commit authorship. Do not invent an assigned-team filter.
Follow returned cursors with the same filters and sort order when a complete list or count is requested. Reset the cursor if the filters change. State when only a page or a subset was read. For repository-run findings, use `source: repository_scan` and `scan_id` equal to the run ID. Inspect selected finding IDs with `defense_factory_findings_get` before describing their evidence, assignment, patches, or verification.
diff --git a/plugins/codex-security/skills/publish-findings/SKILL.md b/plugins/codex-security/skills/publish-findings/SKILL.md
index 0b1752c60..323f972bf 100644
--- a/plugins/codex-security/skills/publish-findings/SKILL.md
+++ b/plugins/codex-security/skills/publish-findings/SKILL.md
@@ -11,7 +11,7 @@ Use `codex-security import sonar` for [live SonarQube Cloud issues](#sonarqube-c
## Select the evidence
-Prefer the provider's supported native JSON from its authenticated CLI, plugin, or API. Keep the original records and complete the requested pagination. A JSON summary or a different product's API response is not interchangeable with the documented report. Use SARIF or CSV only when the installed provider reader supports that profile and native JSON is unavailable or the user supplies that format. Do not convert a richer JSON report to SARIF for import.
+Use a supplied report, connected tool or signed-in CLI that provides the requested native records for the selected account, repository and ref. Follow the [scanner import guide](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/README.md) to narrow broader reports and verify the selection in the JSON preview. Use a direct API only when the provider guide supports its response for the selected destination. Otherwise ask for a supported report. A fresh scan produces new findings. Keep the original records and complete the requested pagination. A JSON summary or a different product's API response is not interchangeable with the documented report. Use SARIF or CSV only when the installed provider reader supports that profile and native JSON is unavailable or the user supplies that format. Do not convert a richer JSON report to SARIF for import.
Use the same acquisition format for repeated imports. Check the provider's identity rules before switching formats: another format can create a separate record or replace a richer snapshot with less detail. Importing findings does not reconcile equivalent vulnerabilities across formats. `--format json` controls command output, not the input report format; readers detect their supported inputs.
@@ -86,7 +86,7 @@ Prefer native Code/SAST CLI or CI JSON for this reader; use self-contained SARIF
For a user-requested new scan, use the installed Semgrep CLI from the source repository root with the selected SAST rules: `semgrep scan --config /path/to/sast-rules.yaml --json-output /path/to/semgrep.json .`. Existing CI jobs can produce the same artifact using `--json-output`; authenticated `semgrep ci --code` follows the job's policy and baseline scope. Explain that this generates fresh scan findings, and do not substitute it for a request to retrieve existing Platform findings.
-For existing findings, the official [Semgrep Guardian Codex plugin](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex) can help select and inspect them. Importing its output needs a separate qualified response mapping and complete pagination for the selected repository/ref. The local `semgrep_findings` MCP tool and Platform REST API also use contracts distinct from CLI reports. Do not reshape a summary into a scan report or claim that a limited tool response is a complete export.
+For selected Semgrep Platform SAST findings, follow the [local SDK example](https://github.com/openai/codex-security/blob/main/docs/scanner-imports/semgrep.md#import-selected-semgrep-platform-sast-findings-with-the-sdk). It takes the original Web API project response, SAST findings pages and selected IDs. The [Semgrep Guardian Codex plugin](https://docs.semgrep.dev/semgrep-guardian/ide-setup/codex) can help select and inspect findings. Guardian and the `semgrep_findings` MCP tool return different records from the SDK inputs.
Import the native report with `--provider semgrep`, a stable organization/project/branch `--source-key`, and `--source-repository-url` identifying the actual source repository. Use `--to local --repository /path/to/project` for local storage or `--to cloud --repository URL_OR_ID` for Cloud. The source URL is checked against configured local Git remotes or the Cloud destination. Preview with `--dry-run --format json` before confirming the import.