proof-of-commitment

# Proof of Commitment

[![Commitment Score](https://poc-backend.amdal-dev.workers.dev/badge/npm/proof-of-commitment)](https://getcommit.dev/audit?packages=proof-of-commitment)
[![npm downloads](https://img.shields.io/npm/dw/proof-of-commitment)](https://www.npmjs.com/package/proof-of-commitment)
[![Mentioned in Awesome MCP Servers](https://awesome.re/mentioned-badge.svg)](https://github.com/punkpeye/awesome-mcp-servers)

> **Stars lie. Behavioral signals don't.**

An MCP server and web tool that scores npm packages, PyPI packages, Rust crates, Go modules, and GitHub repos on **behavioral commitment** — signals that are harder to fake than stars, READMEs, or download counts.

```text
$ npx proof-of-commitment axios zod chalk lodash minimatch
Scoring 5 npm packages... done in 3.0s

Package      Risk          Score   Publishers   Downloads      Age    Provenance
chalk        🔴 CRITICAL   72      1            432.9M/wk      14.6y  —
minimatch    🔴 CRITICAL   78      1            634.1M/wk      14.9y  —
lodash       🔴 CRITICAL   80      1            158.9M/wk      14.1y  —
zod          🔴 CRITICAL   83      1            161.2M/wk      6.3y   🔐 verified
axios        🔴 CRITICAL   88      1            115.7M/wk      11.8y  🔐 verified
                ⚠ COMPROMISED — axios token theft (2026-03-30)

⚠  5 CRITICAL packages found.
   CRITICAL = sole npm publisher + >10M weekly downloads (publish-access concentration risk)
```

`npm audit` flags none of these. They're not vulnerabilities — they're attack-surface concentration. One stolen npm token, one phished maintainer, and a single push reaches the whole ecosystem (axios, March 30 2026 — happened).

## The supply chain problem

26 of the 91 npm packages with >10M weekly downloads have a **single npm publisher**. Together they account for over 3 billion downloads per week. `npm audit` doesn't surface this. Stars don't either.

Four packages in a typical Node.js project are CRITICAL right now:
- **chalk** — 432M downloads/week, **1 npm publisher**
- **zod** — 185M downloads/week, **1 npm publisher** (30+ GitHub contributors)
- **lodash** — 156M downloads/week, **1 npm publisher**
- **axios** — 113M downloads/week, **1 npm publisher** (attacked March 30, 2026)

They won't appear in your `package.json` either — but these are in almost every project:
- **minimatch** — 625M downloads/week, **1 npm publisher**
- **glob** — 366M downloads/week, **1 npm publisher**
- **cross-spawn** — 215M downloads/week, **1 npm publisher**

Behavioral signals surface this. Stars and READMEs don't.

## Quick install (MCP)

No login required. Add to any MCP-compatible AI tool and start querying supply chain risk.

**Claude Desktop**

Open `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS ([config file reference](https://modelcontextprotocol.io/quickstart/user)) or `%APPDATA%\Claude\claude_desktop_config.json` on Windows, then add:

```json
{
  "mcpServers": {
    "commit": {
      "type": "streamable-http",
      "url": "https://poc-backend.amdal-dev.workers.dev/mcp"
    }
  }
}
```

Restart Claude Desktop. A tool icon appears in the chat input — ask it to audit your `package.json`.

**Cursor**

Open `~/.cursor/mcp.json` ([Cursor MCP docs](https://cursor.com/docs/mcp)) and add:

```json
{
  "mcpServers": {
    "commit": {
      "type": "streamable-http",
      "url": "https://poc-backend.amdal-dev.workers.dev/mcp"
    }
  }
}
```

**Smithery** (once indexed)

```bash
npx -y @smithery/cli install proof-of-commitment --client claude
```

---

## Try it now

**Terminal (zero install):**
```bash
# New in v1.8.0: zero-arg auto-detect — cd into any project, run once:
npx proof-of-commitment
# Picks the highest-coverage manifest in cwd (package-lock.json > yarn.lock >
# pnpm-lock.yaml > pnpm-workspace.yaml > package.json; requirements.txt;
# Cargo.toml; go.sum > go.mod). When multiple ecosystems are present, the
# file with the most recent mtime wins.

# Explicit package list still works:
npx proof-of-commitment axios zod chalk

# Or point at a specific file:
npx proof-of-commitment --file package.json
npx proof-of-commitment --file package-lock.json   # npm (transitive)
npx proof-of-commitment --file yarn.lock           # yarn
npx proof-of-commitment --file pnpm-lock.yaml      # pnpm
npx proof-of-commitment --file pnpm-workspace.yaml # pnpm monorepo
npx proof-of-commitment --pypi litellm langchain requests
npx proof-of-commitment --cargo serde tokio reqwest
npx proof-of-commitment --golang github.com/gin-gonic/gin golang.org/x/net
npx proof-of-commitment --file go.mod
npx proof-of-commitment --file go.sum              # full transitive Go set

# JSON output for downstream tools:
npx proof-of-commitment --file package-lock.json --json | jq '.criticalCount'
```

### CI integration (v1.8.0+)

`--fail-on=<level>` turns the CLI into a one-line CI gate. No GitHub Action required.

```yaml
# .github/workflows/supply-chain.yml
name: Supply Chain
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npx -y proof-of-commitment --fail-on=critical
```

Levels:

| `--fail-on` | Exit 1 when… |
|---|---|
| `critical` | any package is flagged CRITICAL (publish-access concentration) |
| `risky` | any package is CRITICAL **or** HIGH (score < 40) |
| `none` | never — report only |

Defaults: `critical` in CI (when `CI=true` is set, which every major CI runner does) and for `--json` output. Interactive (TTY, non-CI) keeps the v1.7 default of **exit 0** — running locally won't break your shell habits.

The dedicated [`piiiico/commit-action@v1`](https://github.com/piiiico/commit-action) is still the right choice when you want PR comments and step summaries; `--fail-on` is for minimal pipelines that just need a yes/no answer.

### SARIF output for GitHub Code Scanning (v1.26.0+)

`--sarif` outputs [SARIF 2.1.0](https://sarifweb.azurewebsites.net/) — the standard format for static analysis results. Upload it to GitHub Code Scanning and Commit findings appear in the Security tab alongside CodeQL and Snyk.

```yaml
# .github/workflows/supply-chain.yml
name: Supply Chain
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npx -y proof-of-commitment --file package-lock.json --sarif --fail-on=none > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif
          category: commit-supply-chain
```

CRITICAL and HIGH packages show as alerts in the repo's Security tab. Compromised packages (in the Commit incident registry) get a separate alert. `--fail-on` still controls the exit code independently — use `--fail-on=critical` to also block the PR.

**Web demo (no install):** [getcommit.dev/audit](https://getcommit.dev/audit) — paste your packages, see risk scores in seconds.

## IDE Hooks (Cursor + Claude Code + Windsurf)

`poc hook` installs a supply chain gate for **Cursor** ([`beforeShellExecution`](https://docs.cursor.com/context/hooks)), **Claude Code** ([`PreToolUse`](https://code.claude.com/docs/en/hooks)), and **Windsurf** ([`pre_run_command`](https://docs.windsurf.com/windsurf/cascade/hooks)) in one command. The same hook script intercepts package installs from any agent, auto-detects which client called it, and blocks CRITICAL packages before they run.

```bash
# Install for the current project (writes .cursor/hooks.json + .claude/settings.json + .windsurf/hooks.json):
poc hook

# Or protect every project for your user:
poc hook --global

# Narrow to one client:
poc hook --cursor          # only .cursor/hooks.json
poc hook --claude-code     # only .claude/settings.json
poc hook --windsurf        # only .windsurf/hooks.json

# Remove (cleans all three):
poc hook --uninstall
```

The hook writes `.cursor/hooks.json`, `.claude/settings.json`, and `.windsurf/hooks.json` (project) or the equivalents under `~/` (with `--global`). When Cursor, Claude Code, or Windsurf runs `npm install axios`, `pip install litellm`, `cargo add serde`, or `go get github.com/gin-gonic/gin`, the hook calls the Commit API and either blocks, warns, or allows — in under 500ms.

**What gets intercepted:**

| Package manager | Example command |
|---|---|
| npm / npx | `npm install <pkg>`, `npm add <pkg>` |
| pnpm | `pnpm add <pkg>` |
| yarn | `yarn add <pkg>` |
| pip / pip3 / uv | `pip install <pkg>` |
| cargo | `cargo add <pkg>`, `cargo install <pkg>` |
| go | `go get <module>`, `go install <module>` |

**Why this matters:** Supply chain attacks now happen in minutes. The Shai-Hulud worm (May 2026) compromised 637 packages in 39 minutes and specifically targeted AI coding assistants — planting persistence hooks in `.claude/settings.json` and `.vscode/tasks.json`. When your AI assistant installs a dependency, it bypasses the human review that used to be the last line of defense. `poc hook` puts a gate back in — same gate, whether Cursor, Claude Code, or Windsurf is driving.

**Default behavior:** CRITICAL packages (sole npm publisher + >10M downloads/week — the exact LiteLLM/axios attack profile) are blocked. HIGH packages trigger an "ask user" prompt (Cursor/Claude Code) or are blocked with a message (Windsurf). Set `COMMIT_HOOK_SEVERITY_BLOCK=HIGH` to block both.

**With an API key:** `poc login sk_commit_…` before running `poc hook` — the key is embedded in the hook config and lifts the rate limit.

---

## Get notified before the next attack

The CLI tells you what's risky today. A free API key unlocks **monitoring** — score recomputation across the packages you depend on, with alerts when one degrades (publisher drops, release stalls, score falls ≥10 points).

- **Open (free):** Watch 3 packages · weekly digest every Monda