failproofai is an npm package that installs hooks into AI coding agents (Claude Code, Codex, and others) and runs locally in developers' environments, observing and gating agent actions. A compromised dependency would therefore run on our users' machines, inside their agent sessions — so we treat our supply chain as part of our users' trust boundary. This document covers how to report a vulnerability and how our dependency supply-chain scanning works.

Please report security issues privately — do not open a public issue.

• Preferred: open a private vulnerability report via GitHub Security Advisories.
• Or email failproofai@exosphere.host.

We aim to acknowledge reports within 3 business days and will keep you updated as we investigate and ship a fix. Please give us a reasonable window to remediate before any public disclosure.

Every pull request — including automated Dependabot dependency bumps — is scanned for supply-chain threats before it can merge, via two complementary layers.

.github/workflows/osv-scanner.yml runs OSV-Scanner against the resolved dependency tree (bun.lock). It checks every direct and transitive package against OSV.dev, which aggregates GitHub/npm security advisories and the OpenSSF malicious-packages feed (confirmed malware: typosquats, account-takeover injections, and the like).

Policy: block on any finding. The gate fails on any known-vulnerable or malicious package in the tree — not just newly introduced ones. It runs on every PR, on pushes to main, and weekly (to catch advisories disclosed after a dependency was already merged).

OSV-Scanner is advisory-based: it can only flag threats already cataloged. To catch novel attacks (malicious install scripts, suspicious network/filesystem access, obfuscation, sudden maintainer changes) before they reach any advisory database, we use Socket via its GitHub App, which comments on PRs that introduce risky dependency behavior. Socket is advisory (it comments); the deterministic blocking gate is OSV-Scanner.

When the OSV-Scanner gate fails on a PR:

1. Prefer fixing it. Bump the affected dependency to a patched version. For a transitive dependency that a parent pins to a vulnerable version, add a minimal overrides entry (as we do for postcss) and let CI validate the build.
2. Only if there is no fix, add a justified, time-boxed entry to osv-scanner.toml (id, reason, ignoreUntil). Never blanket-ignore. Re-review entries when their ignoreUntil date passes.

These steps live outside the repo and require admin access:

1. Install the Socket GitHub App on the repository to enable behavioral PR comments.
2. Make the OSV-Scanner check required: in branch protection for main, add the OSV-Scanner job (shown as OSV-Scanner) as a required status check, so a red scan blocks merge.
3. (Optional) For a Socket CI gate in addition to the App, add a SOCKET_SECURITY_API_KEY repository secret and the Socket CI action — deferred until tuned, since behavioral findings can have false positives.