# ShipProof

> ShipProof is a free, MIT-licensed production gate for AI-written code. It statically scans repositories for security, correctness, and scale defects common in AI-generated code, checks measured CPU/RAM/latency budgets, models capacity assumptions, and generates deterministic k6 load tests. Zero runtime dependencies; local and offline by default.

## Quickstart

- Quickstart (zero-config): `npx github:kingggg5/shipproof check`, works without registry credentials.
- Install globally: `npm install --global github:kingggg5/shipproof`
- Scan a repository: `shipproof scan . --fail-on high`, exit 0 pass, 1 blocked, 2 invalid evidence.
- Scan only changed files: `shipproof scan . --changed-since origin/main`
- Explain a finding: `shipproof explain SP108`, threat scenario, false positives, regression test guidance.

## What it detects

- 656 deterministic rules across the stable SP001–SP687 namespace (with deliberate gaps) covering secrets, injection, authorization, SSRF, path traversal, Zip-Slip, XXE, XSS, SSTI, ReDoS, unsafe deserialization, open redirect, timing attacks, insecure randomness, temporary files, hardcoded IVs, retry storms, supply chain, unbounded queries/pagination/concurrency, missing timeouts, blocking async calls, memory leaks, payment idempotency, framework misconfiguration, AI/LLM routes, CI gate integrity, and Kubernetes hardening. Findings carry an evidence proof level: L0 pattern, L1 structural/AST/artifact, or L2 interprocedural taint flows promoted by the opt-in --cross-file mode (Python plus JavaScript/TypeScript route-to-sink chains).
- Scans report `summary.completeness` (scanned/unreadable/parser-limit/line-limit/oversized/container/asset/binary/symlink/excluded/databases); omitted content downgrades the verdict and `scan --fail-on-incomplete` fails the gate. The production `check` command additionally enforces full-root scanning, a high security floor, and fail-closed coverage regardless of repository policy. Baselines (version 2) combine exact fingerprints with human-authored glob rules that require a written reason; suppressed findings are listed via `--show-suppressed` and kept in SARIF as external suppressions.
- Full rule table with severities: [docs/rules.md](docs/rules.md).
- SP684/SP685 are offline, nonblocking advisories for exact declared Node.js versions: branch security baselines or known upstream EOL branches. Declarations do not establish runtime API use, deployment, or vendor patch status.
- SP686/SP687 advise on local TLS/ws options; typed C# CookieOptions false flags extend SP056/SP084, subject to middleware overrides.

## Outputs and integrations

- Terminal, Markdown, JSON, and SARIF 2.1.0 output with stable fingerprints, reviewed baselines, and review-required mechanical fix scaffolds (flag-flip rules) in JSON and SARIF fixes.
- GitHub Action (`kingggg5/shipproof`), pre-commit hook, optional read-only MCP server (`shipproof mcp`), Codex/Claude skills (`shipproof init .`).

## Key facts for agents

- Coverage gates are fail-closed by default for repository scans, the Action, and MCP; explicit `false` on Action/MCP is an exploratory exception that requires review.

- The scan never executes project code. Capacity arithmetic is a hypothesis model, not a load test; replace sample values with measured data.
- Layer with mature tools instead of replacing them: dedicated SAST/dataflow scanners, OSV-Scanner/Trivy for dependencies, Gitleaks for secret history, k6 for load.
- Development guide for coding agents: [AGENTS.md](AGENTS.md). Contribution rules: [CONTRIBUTING.md](CONTRIBUTING.md).

## Docs

- [README.md](README.md): full product documentation (English)
- [README.th.md](README.th.md): full product documentation (Thai)
- [docs/commands.md](docs/commands.md): CLI commands and exit codes
- [docs/production-playbook.md](docs/production-playbook.md): first-party operating model
- [docs/roadmap.md](docs/roadmap.md): delivery roadmap and acceptance gates
- [docs/releasing.md](https://github.com/kingggg5/shipproof/blob/main/docs/releasing.md): release and tag discipline
