npm supply-chain security for AI agents.

Sentinel is a transparent auditing proxy in front of registry.npmjs.org: it serves real packages unchanged, but intercepts every tarball, scores it with a deterministic audit engine, and attaches a verdict — so an agent or a human sees the risk before install-time code runs. It has since grown into a first-class registry: audit-gated publishes, verified namespace ownership, and time-locked retraction — the capabilities a proxy structurally cannot offer.

npm can't retract bad releases, has no install-time permissions, and lets attackers squat names. The event-stream pattern — a clean package ships a trojaned patch release — still works today, and agents install with zero risk signaling.

The demo

A previously-clean package ships a patch release with a postinstall that harvests secrets. Sentinel's verdict, and what npm install sees when it fetches the bad tarball:

$ sentinel audit color-stream 1.4.1

  color-stream@1.4.1
  ────────────────────────────────────────────────────────
  install    ⚠ runs lifecycle scripts
  score      ░░░░░░░░░░ 0/100
  verdict    BLOCK
  findings (7)
  critical [install-scripts] postinstall reads environment variables,
                              decodes an encoded blob
  critical [secret-exfil]    reads sensitive material (~/.npmrc, AWS
                              credentials) with a network egress sink
  high     [network-egress]  connects to a hardcoded IP address
  high     [obfuscation]     uses eval()

$ npm install --registry http://localhost:4873 color-stream
  HTTP 403  x-sentinel-verdict: block  x-sentinel-score: 0

# and a clean package passes untouched
$ sentinel audit is-odd 3.0.1
  is-odd@3.0.1  → score 100/100  ALLOW  (signed, no install scripts)

How it works

• Transparent proxy: resolves and serves real npm packages unchanged; the verdict rides response headers, and block policy turns a bad tarball into a 403 at install time
• Deterministic scoring — start at 100, weighted penalties per finding, any critical forces block — fully reproducible in CI; an LLM adapter only adds context, never the score
• Policy and approval gate: signed per-enterprise policy — with a lint and a dry-run impact preview against real audit history before signing — capability manifests, and a hard privilege boundary: the agent can request an approval, only a human can grant it, enforced by signed Ed25519 role tokens on the control plane
• Deny-by-default sandbox (macOS Seatbelt, Linux bubblewrap + Landlock): lifecycle scripts get no network, no credential env vars, no writes outside a fixed floor, no $HOME reads, and no executing binaries outside an approved floor — each denial lifted only by an approved capability; detected violations can quarantine that exact tarball fleet-wide (auto-quarantine is opt-in and auth-gated). The same sandbox is reusable directly: sentinel exec runs any command under it — no shell; argument boundaries preserved
• A real write path: an npm-compatible, audit-gated publish route — every version is scored before it is accepted and commits atomically — with a deterministic native-vs-mirror resolution rule, so a claimed name is served only from Sentinel's own store and can never be shadowed by public npm (dependency confusion closed by construction)
• Verified namespace claims: ownership is proven by a DNS TXT challenge on the organization's apex domain and shipped as a signed, offline claim corpus verified at boot; claims renew yearly and freeze on failure — a lapsed name never falls through to public npm and never auto-transfers to a domain's new owner
• Time-locked retraction: a publisher can pull a bad release only while it is younger than 72 hours and under 1,000 cumulative downloads — past either bound, immutability is absolute. Retracted versions leave a 410 tombstone, the identifier is permanently spent, and a retraction advisory flags any lockfile still pinning it
• Release-cooldown overlay: policy can hold freshly published versions for a wall-clock window before installers see them — the counter to burst attacks that ship trojaned releases within hours — and last-known-good suggestions respect the hold
• Agent-native surfaces: a stdio MCP server for agent hosts and a CLI whose exit codes make sentinel audit a CI gate; sentinel explain turns a verdict into per-finding remediation and a suggested last-known-good version — advisory only, it never rewrites a lockfile
• Whole-tree gates: audit every package in an npm/yarn/pnpm lockfile, write a CycloneDX SBOM, post the verdict to the PR via a GitHub Action
• Signed audit attestations (DSSE/in-toto, Ed25519) verified offline as a deploy-time gate, plus known-malicious advisory and CVE-range (SCA) detection
• Identity and history signals: typosquat and dependency-confusion detection, release-anomaly findings — maintainer takeover, dormancy resurrection, new capabilities in a patch release — and native-payload loader detection: raw-byte magic classification plus loader-chain analysis catch binaries smuggled in as source files
• Drop-in for real installers: npm, pnpm, Yarn (1 and Berry), and bun work unmodified against the registry surface; leaving registry mode requires an explicit acknowledgement and emits a revert manifest, so claimed names cannot silently flip back to public npm
• Durable history and observability (opt-in, zero-dependency SQLite): verdict trends, top-flagged packages, and a violation timeline on the dashboard, the CLI, and /-/metrics
• Hardened trust boundary: tarball fetches pinned to allowlisted origins (no SSRF), Host-header spoofing refused, byte caps and opt-in rate limits on expensive routes

Status

What started as the audit-proxy wedge has grown into the full layer (July 2026): signed per-enterprise policy and install-time permission manifests, a deny-by-default capability sandbox, offline signature and Sigstore-provenance verification, known-malicious (GHSA) and CVE-range detection, supply-chain identity and release-anomaly heuristics, whole-tree lockfile auditing with SBOMs and signed attestations, a CI-native GitHub Action, an agent-native MCP server, durable observability, and a hardened network trust boundary. The registry evolution (Phases 30–33, ADRs 0045–0048) is implemented as of 2026-07-13: audit-gated publishes, verified namespace claims, time-locked retraction, and an npm/pnpm/Yarn/bun-compatible surface with a safe exit path. Sentinel is pre-1.0 and not yet production-hardened, but it is now installable: the first alpha, v0.1.0-alpha.1, is published to npm — all seven @git-agentic/sentinel-* packages, under the alpha dist-tag. The next milestone is design-partner evidence — blocked incidents, false-positive rate, audit latency. The long arc is policy and install-time permissions for the whole ecosystem.

$ npm install -g @git-agentic/sentinel-cli@alpha @git-agentic/sentinel-proxy@alpha

Docs: README · Architecture · ADRs