pi-codex-security

A pi package that brings OpenAI Codex Security into your agent sessions: scan repositories for vulnerabilities, review severity-ranked findings, and fix them — all without leaving pi.

What you get

| Piece | Name | What it does | |-------|------|--------------| | Tool | security_scan | Runs a Codex Security scan, streams progress, returns a severity-ranked findings summary plus report/SARIF paths | | Tool | security_auth_status | Checks Codex Security authentication (ChatGPT sign-in or API key) | | Command | /security-scan | Ask the agent to scan: /security-scan [path] [--deep] [--diff base[:head]] [--auth mode] | | Command | /security-status | Show authentication status | | Skill | codex-security | Teaches the agent scan targeting, result triage, and fix workflows |

Install

pi install npm:pi-codex-security

Or try it without installing:

pi -e npm:pi-codex-security

Requirements

• Node.js ≥ 22 and Python ≥ 3.10 (required by @openai/codex-security)
• Authentication — one of:
  • npx codex-security login (interactive ChatGPT sign-in)
  • OPENAI_API_KEY or CODEX_API_KEY environment variable (CI / non-interactive)

Run /security-status inside pi to verify.

Usage

Just ask in natural language:

Scan this repo for security vulnerabilities

Review my uncommitted changes for security issues

Fix the critical findings from the last scan

Or use the command for precise control:

/security-scan                          # whole repo, standard mode
/security-scan --deep                   # thorough (slower, higher cost)
/security-scan --diff main              # only working-tree changes vs main
/security-scan --diff main:HEAD         # only changes in main...HEAD
/security-scan ./packages/api           # scan a subdirectory

The agent calls security_scan, gets back a ranked summary, reads the full report.md, and offers to fix findings highest-severity-first. After fixing, it re-scans to verify.

security_scan parameters

| Param | Type | Default | Description | |-------|------|---------|-------------| | path | string | cwd | Repository or directory to scan | | mode | standard | deep | standard | Scan depth | | auth | auto | chatgpt | api-key | auto | Credential selection | | diffBase | string | — | Scan changes vs this git ref (working tree) | | diffHead | string | — | With diffBase: scan the base...head ref range | | minSeverity | severity | low | Minimum severity listed individually (counts always cover everything) | | maxCostUsd | number | — | Abort if estimated cost exceeds this | | outputDir | string | Codex state dir | Where scan artifacts are written |

Artifacts

Each scan produces:

• report.md — full human-readable report
• findings.json — machine-readable findings (locations, CWEs, evidence, remediation)
• exports/results.sarif — SARIF export for CI / GitHub code scanning
• coverage.json — what the scan covered

CI

Set OPENAI_API_KEY and use the Codex Security CLI directly for gating (--fail-on-severity, SARIF upload). See the upstream docs. This package is the interactive/agent side of that workflow.

Development

npm install
npm run typecheck
npm test

Release

Publishing is manual; the tag-driven workflow (.github/workflows/release.yml) verifies the build and creates the GitHub Release:

npm version patch   # or minor / major — bumps version, commits, tags vX.Y.Z
npm publish         # manual publish (requires npm login)
git push --follow-tags

On the tag push the workflow re-runs typecheck + tests, skips npm publish when the version is already on the registry, and creates a GitHub Release with generated notes. If an NPM_TOKEN secret (or npm Trusted Publisher) is configured later, the workflow publishes automatically whenever the tagged version isn't on npm yet.

License

MIT