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