# pi-codex-security

A [pi](https://github.com/earendil-works/pi-coding-agent) package that brings [OpenAI Codex Security](https://github.com/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

```bash
pi install npm:pi-codex-security
```

Or try it without installing:

```bash
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](https://github.com/openai/codex-security). This package is the interactive/agent side of that workflow.

## Development

```bash
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:

```bash
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