Supply Chain Guard (SCG)

An incident-response toolkit for npm/yarn and Python (pip/poetry/uv) supply chain attacks — free, local, dependency-free.

SCG is not a scanning engine that competes with commercial tools on coverage. It is a Claude Code skill and standalone shell toolkit that does three things well: (1) gives you a fast, repeatable first response when a specific incident drops ("is my machine affected right now?"), (2) orchestrates existing OSS scanners (npm audit, osv-scanner, pip-audit) into one structured pass, and (3) documents hard-won design-hygiene lessons — especially for AI development environments — that generic scanners don't cover.

It was built and hardened during real incidents, including:

• [email protected] RAT incident (2026-03-31) — npm maintainer account takeover (UNC1069/DPRK-APT) injecting a phantom dependency RAT
• Starlette BadHost (CVE-2026-48710, 2026-05-22) — Python HTTP framework Host header path injection → SSRF/RCE, affecting FastAPI, vLLM, LiteLLM, and the broader AI agent ecosystem

What's new in v4 (2026-05-27)

• Python supply chain scan — scripts/project-scan-py.sh with pip-audit / osv-scanner / CVE-flagged version detection
• CVE-flagged version layer (L3-CVE) — track known vulnerable versions of legitimate packages with strict semver-spec evaluation (BadHost CVE-2026-48710 included out of the box)
• Design hygiene guideline — stdio-first MCP transport, version pin discipline, GCP default compute SA editor hardening (see SKILL.md §D.7 DesignHygiene)
• Guild-CLI Devil lense integration — invoke SCG as a Devil lense from guild-cli workflows (see "Guild-CLI Devil Integration" below)

Table of Contents

• Why This Exists
• How SCG Differs from Existing Tools
• What SCG Is (and Isn't)
• Architecture
• Quick Start
• Scan Modes
• Threat Intelligence
• Devil Gate Framework
• Standalone Scripts
• CI/CD Integration
• Response Playbook
• IOC Reference
• Disclaimer
• Limitations
• Integrity Verification
• License

Why This Exists

On March 31, 2026, the widely-used axios npm package (v1.14.1 and v0.30.4) was compromised through a maintainer account takeover attributed to UNC1069/DPRK-APT (per Google Threat Intelligence Group). The attack injected a phantom dependency ([email protected]) that deployed a cross-platform RAT via postinstall scripts, disguised as legitimate system processes.

Supply Chain Guard (SCG) was built during the incident to provide:

1. Immediate detection — Is my machine or project affected right now?
2. Structured assessment — How severe is it? What's the blast radius?
3. Guided response — Step-by-step remediation with safety confirmations
4. Ongoing defense — An 8-gate verification framework to prevent recurrence

How SCG Differs from Existing Tools

SCG is not a replacement for existing security tools. It combines multiple detection layers with a structured verification framework and guided remediation — designed for use during active incidents or as a periodic check alongside your existing tooling.

When to use SCG:

• A supply chain incident just dropped and you need to check your machines and projects right now
• You want a structured, repeatable process for verifying that a compromise has been fully addressed
• You need a lightweight check that runs locally without SaaS dependencies

When to use something else:

• You need continuous real-time monitoring → Snyk, Socket.dev
• You need license compliance scanning → Snyk, FOSSA
• You need coverage beyond npm/yarn → osv-scanner (supports pip, cargo, go, etc.)

What SCG Is (and Isn't)

We'd rather be honest about the boundaries than oversell. SCG is three things:

1. An incident-response playbook, as code. When a named incident drops (axios RAT, Shai-Hulud, a fresh CVE), SCG turns "am I affected, and if so what do I do?" into an executable checklist — 8 verification gates, a severity matrix, and a remediation script where every destructive action needs explicit [y/N] confirmation. This is its primary value: the fast, structured first response that commercial monitoring tools aren't shaped for.

2. An orchestrator of existing OSS scanners. The L1/L2 layers wrap npm audit / pip-audit / osv-scanner. Most of the raw detection power is borrowed; SCG's contribution is bundling them into one pass, adding filesystem/IOC checks the registry tools don't do, and making the output readable and actionable.

3. Documentation of real design-hygiene lessons (SKILL.md §D.7) — things we actually hit or investigated: MCP transport choice, GCP default-SA hardening, install-time execution vectors, and threats that target AI dev tooling (Shai-Hulud reading .claude/settings.json, SANDWORM_MODE poisoning MCP configs). This niche — supply-chain hygiene for AI-assisted development — is where SCG is genuinely differentiated.

What SCG is deliberately NOT

• Not a coverage competitor. The threat database (SKILL.md D.2, the L3 static lists) is hand-maintained — it holds the incidents we've read about, not the tens of thousands of malicious packages a live commercial feed tracks. A hand-curated list cannot keep pace with the real rate of new threats, and we don't pretend it does.
• Not a behavioral analysis engine. SCG matches known patterns. Obfuscated payloads and true zero-days with no public advisory are out of scope by construction.
• Not continuous monitoring. It's a point-in-time check you run during an incident or as a periodic sweep — not a service watching your dependency graph.

Where SCG is headed

Because a hand-curated database can't win on coverage, we're intentionally investing where SCG is hard to replace rather than where it will always lose:

• Deeper incident-response playbooks (#1) — better first-response ergonomics, more incident templates.
• AI-development-environment hygiene (#3) — detection and guidance for threats aimed at Claude Code / Cursor / MCP servers and similar tooling, which commercial supply-chain scanners largely don't address.

The static threat DB (#2) will keep getting updated when notable incidents land, but it is explicitly not the direction we're trying to compete on.

Architecture

SCG follows a Domain-Driven Design (DDD) architecture with three layers:

+-----------------------------------------------------+
|  Domain Layer                                        |
|  Threat models, known threats DB, severity matrix,   |
|  Devil Gate definitions                              |
+-----------------------------------------------------+
|  Application Layer                                   |
|  Use cases, scan pipeline, response protocols,       |
|  Devil execution loop                                |
+-----------------------------------------------------+
|  Infrastructure Layer                                |
|  Scanner scripts (npm audit, OSV, static list,       |
|  IOC filesystem, network, lockfile integrity)        |
+-----------------------------------------------------+

Scan Pipeline

The same 5-layer pipeline applies to both ecosystems with ecosystem-specific scanners at each layer:

L1 ──→ L2 ──→ L3 ──→ IOC ──→ LF ──→ assess(SeverityMatrix) ──→ VERDICT

Both pipelines feed the same SeverityMatrix and Devil Gate Framework.

Quick Start

As a Claude Code Skill

Copy SKILL.md into your Claude Code skills directory:

# Global (all projects)
cp SKILL.md ~/.claude/skills/supply-chain-guard.md

# Or project-specific
mkdir -p .claude/skills
cp SKILL.md .claude/skills/supply-chain-guard.md

Then invoke in Claude Code:

> /supply-chain-guard
> "Check this project for supply chain issues"
> "Is my machine affected by the axios compromise?"

As Standalone Scripts

# Environment-wide scan (IOC + all projects)  [READ-ONLY]
./scripts/env-scan.sh

# npm/yarn project scan (requires package.json in cwd)  [READ-ONLY]
./scripts/project-scan.sh

# Python project scan (requires pyproject.toml / requirements*.txt / poetry.lock / uv.lock in cwd)  [READ-ONLY, added in v4]
./scripts/project-scan-py.sh

# IOC-only scan (filesystem + network artifacts)  [READ-ONLY]
./scripts/ioc-scan.sh

# Remediation (interactive, every action requires confirmation)
./scripts/respond.sh --critical              # Full RAT cleanup (npm + Python)
./scripts/respond.sh --high axios 1.14.0     # Pin npm package to safe version
./scripts/respond.sh --high urllib3 2.7.0    # Pin Python package (auto-detects pip/poetry/uv)

Python remediation is conservative by design. For npm, --high applies the override automatically. For Python it guides: it detects your manager (pip/poetry/uv), prints the exact pin command, and applies only the safe step — lockfile-mutating and venv-rebuild commands are shown for you to run. This avoids a false positive triggering a collateral force-reinstall across the fragmented Python packaging ecosystem.

For a polyglot repository (npm + Python), run both project scanners sequentially from the relevant subdirectories.

Safety design: All scan scripts are strictly read-only — they never modify, delete, or install anything. The remediation script (respond.sh) is the only script that performs destructive operations, and every single action requires explicit [y/N] confirmation with a default of NO.

Scan Modes

Environment Scan (env_scan)

Scans your entire development machine for compromise indicators.

Triggers: "this PC", "environment check", "machine-wide"

Project Scan — npm/yarn (project_scan)

Deep scan of a single npm/yarn project. Run from a directory containing package.json.

Triggers: "this project", "npm audit", or package.json present in cwd

Project Scan — Python (project_scan_py, added in v4)

Deep scan of a single Python project. Run from a directory containing pyproject.toml, requirements*.txt, poetry.lock, or uv.lock.

Triggers: "this project" with Python files present, or any of pyproject.toml / requirements*.txt / poetry.lock / uv.lock in cwd

Dependencies note: L1 (pip-audit) and L2 (osv-scanner) gracefully SKIP with a hint when their respective CLI is absent. L3 is the always-on layer and does not require any external tool, but accurate L3-CVE evaluation needs pip install packaging.

Threat Intelligence

Known Threats Database

T001 Kill Chain (axios RAT)

Credential theft → npm publish (bypass CI) → Inject phantom dep (plain-crypto-js)
    → postinstall exec → RAT drop → C2 beacon (sfrclak.com:8000) → Persist

Safe Versions

Advisory IDs

• GHSA-fw8c-xr5c-95f9
• MAL-2026-2306

Devil Gate Framework

SCG uses an 8-gate verification framework organized into 4 categories, executed as a serial chain with convergence loop.

Gates

Chain Execution

S1: Dependency (G1+G2)
  → S2: Runtime (G3+G4)
    → S3: Integrity (G5+G6)
      → S4: Environment (G7+G8)
        → Any fail? → Fix → Re-run entire chain
        → All pass? → "No concerns" → Done
        → 3 rounds without convergence? → Escalate to user

Severity Matrix

Safety: CRITICAL/HIGH responses involve destructive operations. SCG always presents findings and asks for explicit user confirmation before executing remediation.

Standalone Scripts

scripts/env-scan.sh

Full environment scan. Checks IOC artifacts, scans all lockfiles under $HOME (configurable), and reports compromised packages.

./scripts/env-scan.sh [scan_root_dir]
# Default: $HOME

scripts/project-scan.sh

Project-level scan. Run from a directory containing package.json.

cd my-project
/path/to/scripts/project-scan.sh

scripts/ioc-scan.sh

IOC-only scan. Checks filesystem artifacts, running processes, and network connections against known C2 indicators. Cross-platform (macOS/Linux/Windows via PowerShell).

./scripts/ioc-scan.sh

scripts/respond.sh

Interactive remediation. Every destructive action requires [y/N] confirmation (default: NO).

# CRITICAL: Full RAT cleanup (kill → remove → reinstall)
./scripts/respond.sh --critical

# HIGH: Pin compromised package to safe version
./scripts/respond.sh --high axios 1.14.0        # npm
./scripts/respond.sh --high event-stream 3.3.5  # npm
./scripts/respond.sh --high urllib3 2.7.0       # python (pip/poetry/uv auto-detected)

Steps in --critical mode:

1. Network isolate (block C2 domain via /etc/hosts)
2. Kill RAT processes
3. Remove persistence (LaunchAgents / crontab / scheduled tasks)
4. Delete node_modules and lockfile, clear npm cache
   • 4b (Python): purge pip cache (safe, auto); venv-rebuild shown as manual steps
5. Reinstall dependencies
6. Prompt for verification scan (project-scan.sh and/or project-scan-py.sh)

Each step checks whether action is actually needed (e.g., skips "kill" if no RAT process is running) and shows exactly what will be executed before asking for confirmation.

For HIGH mode, npm applies the override automatically; Python is guided (detect manager → print pin command → apply only the safe step). See the Python remediation note in Quick Start.

CI/CD Integration

GitHub Actions

name: Supply Chain Guard
on:
  pull_request:
    paths:
      - 'package.json'
      - 'package-lock.json'
      - 'yarn.lock'

jobs:
  scg-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies (hardened)
        run: npm ci --ignore-scripts

      - name: Run SCG project scan
        run: |
          chmod +x ./scripts/project-scan.sh
          ./scripts/project-scan.sh

      - name: Run IOC scan
        run: |
          chmod +x ./scripts/ioc-scan.sh
          ./scripts/ioc-scan.sh

Hardening Recommendations

# Always use in CI:
npm ci --ignore-scripts          # Block postinstall execution
# npm ci already enforces lockfile integrity by design (errors on mismatch)

# Yarn equivalent:
yarn install --frozen-lockfile --ignore-scripts

Pin actions by SHA, not tag. The example above uses actions/checkout@v4 for readability, but tags can be moved. In production, pin to a full commit SHA to prevent action supply chain attacks:

root@kitploit:~

- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
- uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af  # v4.1.0

Response Playbook

If CRITICAL (RAT detected)

Do not panic. Follow these steps in order. Each step requires your explicit confirmation.

1. Network Isolate — Block C2 domain via /etc/hosts
2. Kill Processes — Terminate RAT processes (com.apple.act.mond, ld.py, wt.exe)
3. Remove Persistence — Delete LaunchAgents, crontabs, scheduled tasks
4. Clean npm — Remove node_modules and package-lock.json, clear npm cache
5. Reinstall — Fresh npm install && npm ci
6. Rescan — Re-run full pipeline, expect CLEAR

If HIGH (compromised version installed)

1. Pin safe version using respond.sh:

   root@kitploit:~

   ./scripts/respond.sh --high axios 1.14.0
   

   This adds overrides (npm) or resolutions (yarn) to package.json, reinstalls, and prompts for verification.

2. Or manually in package.json:

   root@kitploit:~

   { "overrides": { "axios": "1.14.0" } }
   

   Yarn: { "resolutions": { "axios": "1.14.0" } }

3. Reinstall: npm ci

4. Verify: Re-run scan

IOC Reference

Filesystem Artifacts

Persistence Mechanisms

Network Indicators

Disguise Techniques

Output Format

SCG ──────────────────────────────────
[L1:audit]    CLEAR|!!sev
[L2:osv]      CLEAR|!!vuln-ids
[L3:static]   CLEAR|!!pkg
[IOC:fs]      CLEAR|!!C:artifact
[IOC:net]     CLEAR|!!C:c2
[LF:integ]    CLEAR|!!drift
─── Devil Gate(8) ────────────────────
G1:direct_dep  G2:transitive  G3:rat_fs
G4:postinstall G5:lockfile    G6:provenance
G7:network     G8:cicd
─── Devil Chain(R.N) ─────────────────
S1:dependency → S2:runtime → S3:integrity → S4:environment
─── Loop ─────────────────────────────
R.N → converge|continue
[VERDICT] CLEAR|HIGH|CRITICAL
───────────────────────────────────────

References

Guild-CLI Devil Integration

If you use guild-cli (or any project that exposes a Devil lense workflow), SCG can be invoked as one of the security lenses during a review pass.

Recommended invocation pattern

# Inside a guild-cli review session, in the project root:
~/path/to/supply-chain-guard/scripts/project-scan.sh       # for npm/yarn projects
~/path/to/supply-chain-guard/scripts/project-scan-py.sh    # for Python projects

# Capture the scan output as evidence for a judgment:
SCG_OUTPUT=$(~/path/to/supply-chain-guard/scripts/project-scan.sh 2>&1 || true)

# (a) Record it as a new judgment (fast-track — no prior review needed):
gate fast-track --from "$USER" \
  --action "SCG supply-chain scan (Devil lense)" \
  --reason "$SCG_OUTPUT"

# (b) Or attach it as the Devil lense on an existing review request <id>:
gate review <id> --lense devil --verdict concern --note "$SCG_OUTPUT"

Flag notes (verified against guild-cli): gate review requires an existing <id>, --lense (guild-cli spells it "lense"), and --verdict (ok / concern / reject). It has no --area flag. To log a fresh finding with no prior review object, use gate fast-track as in (a).

Why pair SCG with Devil

Devil's Advocate ("壊しにいく") and SCG share the same posture: assume the worst, scan systematically, then converge. SCG provides the supply-chain dimension of a Devil pass — what the project's dependencies might be doing behind your back — alongside other lenses (security / correctness / architecture / user / operations).

Limitations of the Devil pairing

• SCG runs read-only; the Devil lense won't push fixes. Use respond.sh separately when remediation is required (with explicit user confirmation)
• SCG output may exceed Devil context budgets in large repos; pipe through tail -50 if needed
• For polyglot repos, run both project-scan.sh and project-scan-py.sh and merge findings

Disclaimer

SCG is a detection tool, not a security guarantee. Being upfront about what it can and cannot do is part of the design.

This software is provided "as-is" without warranty of any kind. By using Supply Chain Guard, you acknowledge and agree to the following:

• Not a substitute for professional security. SCG is a supplementary detection tool, not a comprehensive security solution. It does not replace professional incident response, endpoint detection and response (EDR) software, or security audits.
• No guarantee of detection. A CLEAR verdict means no matches were found against the tool's known threat patterns. It does not mean your system or project is free from compromise. Novel, unknown, or modified attacks may not be detected.
• No guarantee of remediation. The remediation steps provided (respond.sh) address known indicators of specific threats. They may not fully remove all traces of a sophisticated compromise. If you suspect active compromise, engage a professional incident response team.
• Use at your own risk. The authors are not liable for any damages, data loss, or security incidents arising from the use or inability to use this tool. This includes but is not limited to: false negatives (missed detections), false positives (incorrect detections), or unintended consequences of running remediation scripts.
• Not legal or compliance advice. This tool does not satisfy regulatory, compliance, or legal requirements for security scanning. Consult appropriate professionals for compliance needs.

Limitations

Understanding what SCG cannot do is as important as knowing what it can.

Detection Boundaries

Threat Database Freshness

The Known Threats database (D.2 in SKILL.md) is manually maintained. It is not connected to any live threat feed. There is inherent latency between a new supply chain incident being discovered and this database being updated.

• Last updated: 2026-05-27 (v4: Python support, BadHost CVE-2026-48710 added)
• Coverage: 3 npm threat families (T001-T003) + 4 Python hijacked/typosquat entries + 1 Python CVE-flagged version entry (BadHost)
• Python coverage scope (v4): primarily lockfile-based scanning (uv.lock / poetry.lock / requirements.txt). The CVE-flagged version layer is best-effort — it only flags packages that match _L3_CVE_LIST entries with strict semver-spec evaluation, and depends on packaging being installed for accurate version matching

Always cross-reference with live sources such as npm advisories, OSV.dev, and vendor security blogs listed in the References section.

False Positive Risk

The following IOC paths may, in rare cases, conflict with legitimate software:

Always verify IOC findings before running remediation. The ioc-scan.sh script reports findings for human review — it does not take any action. The respond.sh script requires explicit confirmation for every destructive action (default: NO) precisely because of this risk.

Network Scanning Limitations

• lsof-based network checks only detect currently active connections. A C2 beacon that connects intermittently may not be active at scan time.
• DNS cache checks are best-effort and OS-dependent. Cleared caches will not show historical connections.
• Encrypted or tunneled C2 traffic cannot be detected by port/IP matching alone.

Scope

• npm/yarn and Python (pip/poetry/uv). Does not cover cargo, go modules, or other package ecosystems.
• Known threats only. This is a pattern-matching tool, not a behavioral analysis engine.
• Point-in-time scan. Results reflect the state at the moment of execution. Continuous monitoring requires repeated execution or integration with CI/CD.

Integrity Verification

Verify that your copy of SCG has not been tampered with. Compare these SHA-256 checksums against your local files:

67ac6216cbe18fdf7050fd267bce4157c016e5c60cd4f84f63b8cf71e80ae3b9  scripts/env-scan.sh
da01f8362563b55b1553f923a748f07d24f24522366e0545e6ba0c09801f8e54  scripts/project-scan.sh
77e7ebba6d44ea020e511a49bc2cbc974d01495de40d35e8dfb7fcc93008954b  scripts/project-scan-py.sh
82aaa4ed898ce354addc064ccf84cca9a498ef4e90fe58613e1110146577609f  scripts/ioc-scan.sh
72ed333838b5584c3b1faf889edc81b0e3195c27396c3b36c62aaebf5f952117  scripts/ioc-scan.ps1
0e6b30e57c959180e22e0ba16f860e9fdc7304045947995084703fb14381d12e  scripts/respond.sh
a44be79d909058c9d216e7cbc5cca736cf8816a492c8d35a6b90c74c042abf5b  SKILL.md

To verify:

shasum -a 256 scripts/*.sh scripts/*.ps1 SKILL.md

Note: These checksums correspond to the latest release. If you have modified any files locally, the checksums will differ. When SCG is updated, this section is updated alongside the code changes.

License

MIT

Built by Eris — because your dependencies shouldn't be someone else's attack surface.