Skip to content

agent-workflows.md

Latest commit

 

History

History
120 lines (92 loc) · 10.4 KB

agent-workflows.md

File metadata and controls

120 lines (92 loc) · 10.4 KB
Raw

Security workflows in Codex

Use Codex Security to scan code, investigate a supplied finding, or make and verify a security fix. Choose the task that matches the evidence you already have; a repository scan is the default when you are looking for new findings.

Get started

Open your repository in Codex. Find Codex Security in the desktop plugin browser, or enter /plugins in the interactive Codex CLI. Install the plugin, confirm it is enabled, and start a new chat. See the plugin quickstart for host setup and access requirements.

Ask for the task in plain language, including the repository or paths and any security context:

Scan this repository with Codex Security. Focus on authorization boundaries, use the existing SECURITY.md, and return the saved report and coverage limits.

The task map below also gives explicit skill names. Local scans do not require the optional Cloud connection. To read existing Cloud findings, follow the separate Cloud setup.

The terminal package includes the plugin used by its own scans. You can follow the CLI quick start without setting up an interactive Codex plugin session.

Choose a task

Task In Codex From the terminal
Find vulnerabilities in a repository or selected paths $security-scan: one Standard audit. cs scan ., optionally --path src.
Review a PR, commit, branch diff, or working-tree patch $security-diff-scan: review changes and trace their supporting code. cs scan . --diff origin/main for committed changes, or cs scan . --working-tree for local changes.
Investigate a repository or paths deeply $deep-security-scan: repeated independent audits; excludes diff reviews. cs scan . --mode deep.
Triage supplied reports or claims $triage-finding: one static-evidence verdict per finding, with proof gaps. cs validate findings.json also assesses supplied claims using static evidence; its output contract differs from plugin triage. See validation.
Fix a security finding Explicitly request $fix-finding with the finding and affected repository. cs patch --scan SCAN_ID; see patching for individual findings and options.
Check an existing security fix Explicitly request $verify-fix with the original finding and current checkout. Verification leaves repository files unchanged. cs verify-fix --scan SCAN_ID; see fix verification.

A scan or triage request does not request a code change. Ask to fix a specific finding when you want a patch. Standalone fix verification is a separate request and reports fixed, still_vulnerable, or inconclusive with evidence.

Policy generation is optional. Existing root and component SECURITY.md files already guide scans. Use policy generation when that guidance needs to be drafted or updated.

Read the result

For a completed scan, start with the generated report and its saved findings, coverage, and threat model when present. Use the completion summary to locate the saved results. Use source locations and validation evidence to assess a finding; review coverage for assessed surfaces, exclusions, deferred candidates, and remaining questions.

A completed scan can retain unresolved questions. No reported findings does not establish that every path was reviewed or that the repository is secure. Static triage establishes what the source supports; it does not claim runtime testing. An inconclusive fix verification identifies the evidence still needed.

For automation, scan exit codes distinguish these outcomes:

  • 0: the scan completed without triggering a configured findings threshold.
  • 1: findings meet the configured --fail-on-severity threshold.
  • 2: execution, target-integrity, or required-output failure.

Coverage gaps and investigation notes do not by themselves fail a completed scan. See scan output and SDK results for the saved fields and failure output.

Give an agent CLI guidance

The full plugin, generated CLI skills, and CLI MCP registration serve different purposes:

Integration What it provides
Codex Security plugin The security workflow skills above, their MCP tools, and optional connected apps.
cs skills add Generated guidance for an agent using CLI commands. This does not install the full security plugin.
cs mcp add The CLI's read-only info tool. It does not expose scan or patch tools; this transport cannot cancel active commands.

An agent using the terminal can discover current commands and their schemas:

cs --llms
cs scan --schema --format json
cs scan --help

Use the CLI reference for integrations and output formats.

Recover an interrupted task

Symptom Next step
cs is missing or resolves to another program Check the npm executable directory on PATH, or use codex-security or npx @openai/codex-security. See CLI setup.
The session has CLI guidance but no security workflow skills Install and enable the full plugin through your host when available, then start a new chat. skills add and mcp add do not install it.
A skill is visible but required scan tools are unavailable Resolve the plugin server/setup error before starting the scan. Preserve any existing scan identity and report the blocker. A skill alone does not establish working tools or a completed scan.
Authentication fails on a headless machine Use the documented device or SSH login, or configured API credentials for CI.
A Deep Scan stops waiting in chat Keep the existing scan ID. Ending a turn or detaching a waiter does not cancel the durable scan; ask Codex to continue that same scan.
A scan fails or completion reports an error Preserve its ID, output directory, and exact error. Inspect that run before choosing recovery; retained artifacts do not imply successful completion.

For terminal scans, inspect an explicit ID so history commands refer to the same run:

cs scans show SCAN_ID
cs scans logs SCAN_ID

Without an ID, scans show selects the latest completed scan, while scans logs selects the latest scan of any status. An interrupted Deep Scan still marked running can use cs scans resume SCAN_ID with its original checkout, output, session, and state directory. Completed, failed, and canceled scans need a new attempt with cs scans rerun SCAN_ID. A rerun uses the current checkout and may need the original custom prompt files supplied again. See resume requirements and runtime troubleshooting.