### 扫描管道

相同的 5 层管道适用于两个生态系统，每一层都有针对特定生态系统的扫描器：```
L1 ──→ L2 ──→ L3 ──→ IOC ──→ LF ──→ assess(SeverityMatrix) ──→ VERDICT

然后在 Claude Code 中调用：```
> /supply-chain-guard
> "Check this project for supply chain issues"
> "Is my machine affected by the axios compromise?"

> **Python 修复方案在设计上偏向保守。** 对于 npm，`--high` 会自动应用
> override。对 Python 则是 *引导式*：它会检测你的包管理器
> (pip/poetry/uv)，打印出精确的固定（pin）命令，并且只执行安全步骤 —
> 会显示修改锁文件和重建 venv 的命令供你运行。这样可避免
> 误报导致在碎片化的 Python 打包生态系统中触发连带性强制重装。

对于包含多语言（npm + Python）的仓库，请分别在相关子目录中依次运行两个项目扫描器。

> **安全设计：** 所有扫描脚本均为严格只读 — 它们绝不修改、删除或安装任何内容。修复脚本 (`respond.sh`) 是唯一执行破坏性操作的脚本，并且**每个操作都需要明确的 `[y/N]` 确认**，默认值为 NO。

---

## 扫描模式

### 环境扫描 (`env_scan`)

扫描整个开发机器以查找失陷指标。

| 检查 | 描述 |
|-------|-------------|
| **IOC：文件系统** | RAT 二进制文件、持久化机制、暂存文件 |
| **IOC：网络** | 活跃的 C2 连接（IP + 域名） |
| **IOC：进程** | 正在运行的恶意进程 |
| **跨项目** | 扫描所有 `package-lock.json` 文件以查找已受侵害的版本 |
| **恶意包** | 任何锁文件中的已知恶意包名 |

**触发词：** "this PC"、"environment check"、"machine-wide"

### 项目扫描 — npm/yarn (`project_scan`)

对单个 npm/yarn 项目进行深度扫描。在包含 `package.json` 的目录中运行。

| 层级 | 扫描器 | 描述 |
|-------|---------|-------------|
| **L1** | `npm audit` | 通过 npm registry 发现的已知漏洞 |
| **L2** | `osv-scanner` / OSV.dev API | Google 的开源漏洞数据库 |
| **L3** | 静态列表 | 硬编码的已知恶意包检查 |
| **IOC** | 文件系统 + 网络 | RAT 工件检测 |
| **LF** | 锁文件完整性 | `npm ci --dry-run` + 完整性哈希计数 |

**触发词：** "this project"、"npm audit"、或当前工作目录中存在 `package.json`

### 项目扫描 — Python (`project_scan_py`，v4 新增)

对单个 Python 项目进行深度扫描。在包含 `pyproject.toml`、`requirements*.txt`、`poetry.lock` 或 `uv.lock` 的目录中运行。

| 层级 | 扫描器 | 描述 |
|-------|---------|-------------|
| **L1** | `pip-audit` | 通过 PyPI 公告数据库发现的已知漏洞（可选 — 若未安装则跳过；建议执行 `pip install pip-audit`） |
| **L2** | `osv-scanner` | 针对 `uv.lock` / `poetry.lock` / `requirements*.txt` 使用 Google 的开源漏洞数据库（可选 — 若未安装则跳过） |
| **L3-MAL** | 静态恶意列表 (`_L3_LIST`) | 已知的被劫持 / 域名仿冒包名。匹配 PEP 621 列表、Poetry 内联声明以及 requirements 风格声明（参见 [PR #4](https://github.com/eris-ths/supply-chain-guard/pull/4)）。命中即失败 |
| **L3-CVE** | 静态 CVE 标记版本列表 (`_L3_CVE_LIST`) | 已知合法包的易受攻击版本（例如 [BadHost CVE-2026-48710](https://cryptobriefing.com/starlette-badhost-vulnerability-ai-agents/) 对应的 `starlette<1.0.1`）。通过 Python 的 `packaging` 库进行严格的 semver 规范评估。确认匹配即失败。若包已声明但不存在锁文件则发出警告（无法评估版本） |
| **IOC** | 文件系统 + 进程 | Python 风格的工件检查（可疑脚本、可疑进程） |
| **LF** | 锁文件完整性 | 验证 `uv.lock` / `poetry.lock` / `requirements*.txt` 能否干净解析并包含固定版本 |

**触发词：** "this project" 且存在 Python 文件，或当前工作目录中有 `pyproject.toml` / `requirements*.txt` / `poetry.lock` / `uv.lock` 中的任意一个

> **依赖项说明：** 当相应的 CLI 不存在时，L1 (`pip-audit`) 和 L2 (`osv-scanner`) 会优雅地跳过并给出提示。L3 是始终启用的层级，不需要任何外部工具，但要准确评估 L3-CVE，需要执行 `pip install packaging`。

---

## 威胁情报

### 已知威胁数据库

| ID | 日期 | 包 | 威胁行为者 | 攻击向量 |
|----|------|---------|-------------|--------|
| **T001** | 2026-03-31 | `[email protected]`, `[email protected]` | UNC1069/DPRK-APT | 维护者账户失陷 → 幽灵依赖 → RAT |
| **T002** | 2018-11 | `[email protected]` | 未知 | 依赖注入 → 加密货币窃取 |
| **T003** | 持续中 | `crossenv`, `loadsh`, `crypto-js-esm` | 多个 | 域名仿冒 → 安装后数据外泄 |

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

### 严重性矩阵

| 级别 | 条件 | 操作 |
|-------|-----------|--------|
| **CRITICAL** | 发现 RAT 工件或安装了恶意包 | 网络隔离 → 终止进程 → 移除持久化 → 重新安装 |
| **HIGH** | 正在使用被入侵的版本 | 固定安全版本 → 覆盖 → `npm ci` → 验证 |
| **MEDIUM** | 可疑的 postinstall 脚本 | 人工审查 → 加入白名单或移除 |
| **LOW** | 锁文件漂移 | `npm ci` 重新同步 |
| **CLEAR** | 所有检查通过 | 无需操作 |

> **安全性：** CRITICAL/HIGH 响应涉及破坏性操作。SCG 始终先呈现发现的结果，并在执行修复前要求用户明确确认。

---

## 独立脚本

### `scripts/env-scan.sh`

完整的环境扫描。检查 IOC 工件，扫描 `$HOME`（可配置）下的所有锁文件，并报告受损包。```bash
./scripts/env-scan.sh [scan_root_dir]
# Default: $HOME

### `scripts/ioc-scan.sh`

仅IOC扫描。检查文件系统痕迹、运行进程和网络连接，与已知的C2指标进行比对。跨平台（macOS/Linux/Windows，通过PowerShell）。```bash
./scripts/ioc-scan.sh

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](#quick-start).

---

## CI/CD Integration

### GitHub Actions```yaml
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

> **按 SHA 固定 Actions，而不是标签。** 上面的示例为了可读性使用了 `actions/checkout@v4`，但标签可以被移动。在生产环境中，请固定到完整的提交 SHA，以防止 GitHub Actions 供应链攻击：
> ```yaml
> - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
> - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af  # v4.1.0
> ```

---

## 响应手册

### 如果严重（检测到 RAT）

> **不要惊慌。** 按顺序执行以下步骤。每个步骤都需要你的明确确认。

1. **网络隔离** — 通过 `/etc/hosts` 阻止 C2 域名
2. **终止进程** — 终止 RAT 进程（`com.apple.act.mond`、`ld.py`、`wt.exe`）
3. **清除持久化** — 删除 LaunchAgents、crontabs、计划任务
4. **清理 npm** — 删除 `node_modules` 和 `package-lock.json`，清除 npm 缓存
5. **重新安装** — 全新 `npm install && npm ci`
6. **重新扫描** — 重新运行完整管道，预期结果为 CLEAR

### 如果高危（已安装被入侵的版本）

1. **固定安全版本** 使用 respond.sh:   ```bash
   ./scripts/respond.sh --high axios 1.14.0

---

## References

| Source | Description |
|--------|-------------|
| [Zenn (JP)](https://zenn.dev/gunta/articles/0152eadf05d173) | 日文早期报告 |
| [Elastic Security Labs](https://elastic.co/security-labs/axios-one-rat-to-rule-them-all) | 技术分析（RAT 反汇编、C2 协议、时间线） |
| [SANS](https://sans.org/blog/axios-npm-supply-chain-compromise-malicious-packages-remote-access-trojan) | 企业事件响应流程 |
| [Huntress](https://huntress.com/blog/supply-chain-compromise-axios-npm-package) | YARA 签名 |
| [Elastic Detections](https://elastic.co/security-labs/axios-supply-chain-compromise-detections) | SIEM 检测规则（YARA/osquery/KQL） |
| [Semgrep](https://semgrep.dev/blog/2026/axios-supply-chain-incident-indicators-of-compromise-and-how-to-contain-the-threat/) | 静态分析规则、遏制指南 |
| [SOCRadar](https://socradar.io/blog/axios-npm-supply-chain-attack-2026-ciso-guide/) | CISO 指南及 IOC 时间线 |
| [Wiz](https://wiz.io/blog/axios-npm-compromised-in-supply-chain-attack) | 云影响分析、容器扫描 |
| [NVD CVE-2026-48710](https://nvd.nist.gov/vuln/detail/CVE-2026-48710) | **主要** — NVD 权威条目（发布于 2026-05-26，CVSS 3.1 基础分 6.5 中危，AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N） |
| [GHSA-86qp-5c8j-p5mr](https://github.com/Kludex/starlette/security/advisories/GHSA-86qp-5c8j-p5mr) | **主要** — 针对 `Kludex/starlette` 的 GitHub 安全公告（发布于 2026-05-21）："缺少 Host 头验证会污染 request.url.path，从而绕过基于路径的安全检查" |
| [Starlette v1.0.1 发布说明](https://github.com/Kludex/starlette/releases/tag/1.0.1) | **主要** — 修复版本（发布于 2026-05-21）。锁定 `starlette>=1.0.1`（以及 `fastapi>=0.119` 以进行传递依赖解析） |
| [Starlette BadHost 报道（KuCoin）](https://kucoin.com/news/flash/starlette-vulnerability-exposes-millions-of-ai-agents-to-hackers) | 次要 — Python 生态系统影响，AI 智能体视角 |
| [BadHost AI 智能体分析（CryptoBriefing）](https://cryptobriefing.com/starlette-badhost-vulnerability-ai-agents/) | 次要 — FastAPI / vLLM / LiteLLM 下游影响视角 |

---

## Guild-CLI Devil 集成

如果你使用 [guild-cli](https://github.com/eris-ths/guild-cli)（或任何暴露 Devil lense 工作流的项目），SCG 可以在审查过程中作为安全透镜之一被调用。

### 推荐的调用模式```bash
# 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"

<!-- CHECKSUMS-END -->

要验证：```bash
shasum -a 256 scripts/*.sh scripts/*.ps1 SKILL.md