ccs-mcp-server 1.2.17 → 1.4.0

package/README.md

@@ -1,28 +1,48 @@
-# CCS Runtime Evidence MCP Server
+# CCS MCP Server · Agent 运行时验证与收据验签
 
 [![IETF Internet-Draft](https://img.shields.io/badge/IETF-draft--correctover--ccs-blue)](https://datatracker.ietf.org/doc/draft-correctover-ccs/)
 [![npm version](https://img.shields.io/npm/v/ccs-mcp-server.svg)](https://www.npmjs.com/package/ccs-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/ccs-mcp-server.svg)](https://www.npmjs.com/package/ccs-mcp-server)
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that brings **CCS runtime verification** to any MCP-compatible client — Claude Desktop, Cursor, Windsurf, and more.
+> **给 AI Agent 配一个运行时保安：它删库、偷密钥、闯内网、被注入诱导——当场拦下。**
+> 它是一道**运行时拦截层**，不是事后审计工具：危险动作在执行点就被挡住；每张 Ed25519 签名收据，都是拦截/放行时当场附带的裁决凭证。
 
-It verifies AI agent tool calls at runtime, blocks unsafe ones by default, issues **tamper-evident evidence records** for every decision, and verifies that actual tool arguments match the agent's declared intent — catching cross-model parameter drift.
+> **本包同时以 `agent-runtime-guard` 之名发布**，两者是同一份代码、同一个 bin 入口。已装 `agent-runtime-guard` 的用户无需迁移。
 
-> **Runtime evidence layer, not a static scanner.** Every decision is enforced at call time and produces independently verifiable cryptographic evidence.
+你给 Agent 接上 shell、网络、云凭证这些工具后，最大的风险是：**它手一抖，一条命令删掉整台机器；或被诱导，把密钥和数据偷偷传走。** 一个容易点过的"确认弹窗"挡不住。
+
+`ccs-mcp-server` 在 **Agent 与危险操作之间**站一道确定性的拦截层——工具调用、shell 命令、网络请求、输出结果全栈覆盖，危险动作在**真正执行前**被 fail-closed 拦下，无需人工点击。
+
+- ✅ **零运行时依赖**，纯 Node.js 标准库（Node ≥ 18），无 install 脚本
+- ✅ **全栈拦截**：命令注入 / 路径穿越 / SSRF（含云元数据）/ 凭证外泄 / 提示注入 / 跨工具攻击链
+- ✅ **fail-closed**：判危险、验证器出错或超时，都不转发、不执行
+- ✅ **Ed25519 证据收据**：每次决策双哈希 + 可链，第三方可离线验证
+- ✅ **随处可用**：MCP server（Claude Code / Cursor / Cline / Windsurf）、透明 stdio 代理、DeepSeek Harness 插件
 
 ---
 
-## ⚡ Quick Start — running in 30 seconds
+## ⚡ 一键安装
+
+**Cursor：**
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=ccs-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNjcy1tY3Atc2VydmVyIl19)
+
+**VS Code：**
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=ccs-mcp-server&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22ccs-mcp-server%22%5D%7D)
+
+手动安装：
 
 ```bash
 npx -y ccs-mcp-server
 ```
 
-Add it to any MCP client — paste this into your `mcpServers` config in Claude Desktop, Cursor or Cline:
+把它加进任意 MCP 客户端的 `mcpServers` 配置：
 
 ```json
 {
   "mcpServers": {
-    "ccs-runtime-evidence": {
+    "ccs-mcp-server": {
       "command": "npx",
       "args": ["-y", "ccs-mcp-server"]
     }
@@ -30,121 +50,105 @@ Add it to any MCP client — paste this into your `mcpServers` config in Claude
 }
 ```
 
-Or install from the official MCP Registry: search **"Correctover"** inside your client, or open [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) and find `io.github.Correctover/ccs`.
+无需 API key、账号或环境变量——首次运行自动生成 Ed25519 签名密钥（想固定持久密钥再设 `CCS_KEY_DIR` 或 `CCS_PRIVATE_KEY`/`CCS_PUBLIC_KEY`）。
 
-No API key, no account, no environment variables required — an Ed25519 signing key is generated automatically on first run (set `CCS_KEY_DIR`, or `CCS_PRIVATE_KEY`/`CCS_PUBLIC_KEY`, only if you want to pin a persistent key). Zero dependencies. Pure Node.js stdlib (Node ≥ 18). No install scripts.
+---
 
-### 🇨🇳 免费验证之外 · 支付宝 SkillPay
+## 🔍 命令行自检
 
-本服务的运行时验证与证据签发可免费使用。如果你需要人工深度审计或正式合规凭证，可以在支付宝 SkillPay 货架获取：
+不确定装没装对？不用起 MCP 客户端，直接问它：
 
-- 货架首页：https://skillpay.alipay.com/public/correctover
-- 也可以在支持「支付宝 AI 付」的智能体对话里直接输入对应服务名唤起购买：
-  - **MCP配置安全体检**：`请通过 SkillPay 购买并安装 Skill「MCP配置安全体检」`
-  - **CCS收据批量审计**：`请通过 SkillPay 购买并安装 Skill「CCS收据批量审计」`
-  - **CCS收据验签**：`请通过 SkillPay 购买并安装 Skill「CCS收据验签」`
+```bash
+npx -y ccs-mcp-server --version   # 打印版本号
+npx -y ccs-mcp-server --tools     # 列出全部工具及用途（不启动服务）
+npx -y ccs-mcp-server --help      # 完整用法
+```
 
-*Beyond the free verification: human-led deep audits and compliance evidence are available on the Alipay SkillPay shelf — open the link above, or type the service name (e.g. **CCS收据批量审计**) in an agent with Alipay AI Pay enabled.*
+`--tools` 会输出工具名与一句话说明，方便你在接入前先确认能力边界。
 
-## Tools
+---
 
-| Tool | Purpose |
+## 三种用法
+
+| 场景 | 怎么用 |
 |---|---|
-| `verify_tool_call` | 7-dimension runtime verification (Structure/Schema/Security/Identity/Integrity/Latency/Cost) + semantic attack-chain analysis + math overflow detection. **Blocks by default.** |
-| `issue_evidence` | Issue a tamper-evident evidence record (`content_hash` + `evidence_hash`, chainable). Produced for allowed AND denied calls. |
-| `audit_mcp_config` | Audit MCP configuration JSON for security risks. |
-| `verify_intent_binding` | Verify actual tool arguments match a declared intent — zero tolerance, zero LLM calls. Catches cross-model parameter drift (planner says `amount: 100`, executor writes `amount: 10000` → DENIED). |
-| `verify_receipt` | Offline-verify a CCS Ed25519-signed receipt: checks the signature against the embedded signer public key, reports tampering, and optionally pins an expected signer key or fingerprint. |
+| **MCP 客户端**（Claude Code、Cursor、Cline、Windsurf） | 配置上面的 `mcpServers`，工具调用先过保安 |
+| **DeepSeek Harness** | `dsh plugin add ccs-mcp-server`，默认 bundle patch 自动启用，住进 `tools/pre-execute` / `post-execute` |
+| **网络边界独立拦一道** | 用透明 stdio 代理 [`agent-runtime-proxy`](https://www.npmjs.com/package/agent-runtime-proxy) 包住目标 MCP server，不信宿主内任何插件 |
 
-## Intent Binding — Cross-Model Drift Detection
+---
 
-Agent planners (Claude, GPT) declare one thing; executors (Qwen, DeepSeek) sometimes write another. No existing protocol verifies that actual tool call arguments match the agent's declared intent:
+## 它拦什么
 
-- **AP2** signs human authorization — not LLM intent
-- **AgentPay** does baseline tolerance (1%) — not zero-tolerance equivalence
-- **ACS** runs policy decisions — not argument-level equivalence
-- **VAP** (draft-samal-vap-00) explicitly excludes argument semantics from its wire schema
+- **命令注入**：shell 元字符、`curl|sh`、`rm -rf`、`eval()`
+- **路径穿越**：`../`、`/etc/passwd`、`/proc/self/`
+- **SSRF**：`169.254.169.254` 云元数据、localhost、私网地址——跨任何工具
+- **跨工具攻击链**：读敏感文件 → 网络外传 = `exfil_chain`
+- **凭证外泄**：API key、secret、credential 出现在参数或输出
+- **混淆提权**：hex/base64 编码、提权信号
+- **数值安全**：整数溢出（>2^53-1）、NaN/Infinity
+- **提示注入**：工具结果里的"忽略以上指令"等诱导
 
-CCS Intent Binding fills this layer. The agent framework declares a structured intent before execution; CCS verifies actual arguments against it in sub-millisecond, zero-LLM time.
+## Tools
 
-### Example: amount drift
+| Tool | 用途 |
+|---|---|
+| `verify_tool_call` | 7 维运行时验证 + 语义攻击链分析 + 数值溢出检测，**默认拦截** |
+| `issue_evidence` | 出具防篡改证据（`content_hash` + `evidence_hash`，可链），放行和拦截都产生 |
+| `audit_mcp_config` | 审计 MCP 配置的安全风险 |
+| `verify_intent_binding` | 校验实际参数与声明意图是否一致——零容忍、零 LLM，抓跨模型参数漂移（规划写 `amount:100`，执行写成 `amount:10000` → 拦截） |
+| `verify_receipt` | 离线校验 Ed25519 收据签名、检测篡改，可固定可信签名者 |
+| `locate_tampering` | 字段级定位篡改点（RFC 6901 JSON Pointer），报出是哪个字段、多严重 |
 
-```json
-// Intent declared by planner
-{
-  "intent_id": "int-001",
-  "intent_type": "payment",
-  "fields": {
-    "amount": { "value": 100, "binding_mode": "exact" },
-    "recipient": { "value": "Alice", "binding_mode": "exact" }
-  },
-  "issued_at": 1755000000000,
-  "ttl_ms": 30000
-}
+## 证据链
 
-// Actual arguments from executor
-{ "amount": 10000, "recipient": "Alice" }
+每次决策产生双哈希（`content_hash` + `evidence_hash`）与链指针（`parent_evidence_hash`）。任何第三方都能独立验证证据未被篡改，无需信任运营方。收据为 Ed25519 签名、JSON 形态，可用内置 `verify_receipt` 或任意 Ed25519 库离线验证。
 
-// Result: DENIED — intent_arg_mismatch
-// field: amount, expected: 100, actual: 10000
-```
+## FAQ（给 AI Agent 配运行时保安，常见疑问）
+
+**黑名单为什么永远拦不全？** 危险命令可以用同义词、编码、拼接绕过，且新型调用不断出现。`ccs-mcp-server` 用语义判定（这段代码的意图是不是危险执行）而不是匹配关键词，未知攻击靠意图异常也能识别。
 
-### Three binding modes
+**`Bash(prefix*)` 放行规则够安全吗？** 不够。`git status*` 这类前缀规则会被 `git status; rm -rf /`、`&&`、管道拼接绕过。判定应基于 shell 解析后的实际命令结构，而不是字符串前缀。
 
-| Mode | Behavior | Example |
-|------|----------|---------|
-| `exact` | Deep equality with math normalization | `100`, `100.0`, `1e2` all match; `10000` does not |
-| `numeric_tolerance` | Absolute tolerance | `100 ± 0.01` matches `100.005` |
-| `pattern` | Regex match on string fields | `^[A-Z]{3}$` matches `"USD"` |
+**安全判定能依赖宿主模型/远程分类器吗？** 不建议。远程服务一挂，要么全部拒绝（业务瘫痪）要么被建议绕过（裸奔）。本层策略在本地、默认 deny，裁决与模型可用性完全解耦。
 
-No intent declared? Falls through to standard 7-dimension verification. Zero breaking changes.
+**子 agent 一开权限会被放大吗？** 会，这是真实出现过的问题：子 agent 把权限状态整个换成 allow-all。运行时权限状态应不可被子任务覆盖，并在每次实际调用时强制校验。
 
-## What It Detects
+**凭证为什么会自动泄露给子命令？** 子进程默认继承父进程全部环境变量，provider key、云凭证随之暴露给 `/run`、`/test` 等本不需要它们的命令。应按白名单最小化传递环境变量。
 
-- **Command injection**: shell metacharacters, `curl|sh`, `rm -rf`, `eval()`
-- **Path traversal**: `../`, `/etc/passwd`, `/proc/self/`
-- **SSRF**: `169.254.169.254` (cloud metadata), localhost, private ranges — across any tool
-- **Cross-tool attack chains**: read sensitive file → network exfil = `exfil_chain`
-- **Environment variable exfiltration**: API keys, secrets, credentials
-- **Obfuscation**: hex encoding, base64, privilege escalation signals
-- **Math safety**: integer overflow (>2^53-1), NaN/Infinity
-- **MCP config risks**: plain HTTP, weak secrets, `--insecure`, TLS disabled
+**拦了还是放了，事后怎么说清是谁的责任？** 每次裁决都出 Ed25519 签名收据（含内容哈希、时间、原因码、链指针），任何第三方可离线验证。这是把"AI 干的"变成可审计责任链的关键。
 
-## Evidence Chain
+---
 
-Every decision produces evidence with dual hashes (`content_hash` + `evidence_hash`) and chain linkage (`parent_evidence_hash`). Any third party can independently verify that evidence has not been tampered with — without trusting the operator.
+## 免费 vs 付费
 
-```
-evidence 1: allowed  (fs.read_file)       parent: null
-evidence 2: denied   (shell.exec curl|sh) parent: ev1
-evidence 3: denied   (http.fetch SSRF)    parent: ev2
-evidence 4: denied   (fs + curl exfil)    parent: ev3
-```
+运行时验证、证据签发、收据验签**全部免费**，工具全量开放，无需注册。
 
-Receipts are Ed25519-signed and JSON-based: verify them offline with the built-in `verify_receipt` tool, or independently with any Ed25519 library. Cross-tool receipt verification (same crypto, chain linkage, field mapping) is designed to work without this package installed.
+如果你需要**面向业务方的正式凭证**（而不是给开发者看的日志），下面三档在售：
 
-## The 7 CCS Dimensions
+| 档位 | 价格 | 你拿到什么 | 入口 |
+|---|---|---|---|
+| **单次扫描** | **¥9.9 / 次** | 上传你的 MCP 配置，出一份带评分的静态审计报告 + Ed25519 签名收据，可用于合规留档 | [correctover-pay](https://correctover-pay.pages.dev) |
+| **配置安全体检** | **¥49.90 / 月** | 支付宝 SkillPay 货架订阅，MCP 配置静态审计与 SSRF 检测，按月出具凭证 | [支付宝 SkillPay 货架](https://skillpay.alipay.com/public/correctover) |
+| **收据批量审计** | 按量 | 大量收据的哈希链验签与合规证据集打包，适合审计场景 | [支付宝 SkillPay 货架](https://skillpay.alipay.com/public/correctover) |
 
-1. **Structure** — valid tool name, argument format, nesting depth, payload size
-2. **Schema** — type, required fields, enums, ranges, string lengths
-3. **Security** — injection, traversal, SSRF, env exfiltration, obfuscation + semantic attack chains
-4. **Identity** — caller agent ID verification
-5. **Integrity** — request hash validation
-6. **Latency** — execution time budget
-7. **Cost** — cost budget
+> 三者都是**同一套引擎**的托管服务——免费版在自己机器上跑，付费版把结果和凭证托管出来。选哪个取决于你需要"自己看"还是"拿给别人看"。
 
-## Protocol Context
+## 协议背景
 
-- **IETF**: [draft-correctover-ccs](https://datatracker.ietf.org/doc/draft-correctover-ccs/) — an individual Internet-Draft; not an RFC or IETF endorsement, and the Datatracker page is authoritative for revision and status
-- **Complements**: [VAP draft-samal-vap-00](https://datatracker.ietf.org/doc/draft-samal-vap/) (scope/budget/purpose), [Microsoft ACS](https://github.com/microsoft/agent-governance-toolkit) (policy decisions), AP2 (human authorization)
-- **Does not replace**: authentication, payment networks, policy engines
+- **IETF**：[draft-correctover-ccs](https://datatracker.ietf.org/doc/draft-correctover-ccs/) —— 个人 Internet-Draft，**不是 RFC，也不代表 IETF 背书**，Datatracker 页面为权威状态
+- **互补**：VAP（范围/预算/目的）、Microsoft ACS（策略决策）、AP2（人工授权）
+- **不替代**：认证、支付网络、策略引擎
 
 ## Links
 
 - npm: https://www.npmjs.com/package/ccs-mcp-server
+- 同源别名 npm: https://www.npmjs.com/package/agent-runtime-guard
+- 官网: https://correctover.com
 - GitHub: https://github.com/DSHCorrectover/ccs-mcp-server
+- 透明代理: https://github.com/DSHCorrectover/agent-runtime-proxy
 - IETF Draft: https://datatracker.ietf.org/doc/draft-correctover-ccs/
-- PyPI (full verifier): https://pypi.org/project/ccs-verifier/
+- PyPI 完整验证器: https://pypi.org/project/ccs-verifier/
 
 ## License
 

package/dsh/cmdi.js

@@ -0,0 +1,98 @@
+/**
+ * @file Command injection detection — inspects subprocess argv and shell strings.
+ *
+ * Detects:
+ *  - Shell metacharacter injection (;, |, &&, ||, backticks, $())
+ *  - Reverse shell patterns
+ *  - Download-and-execute chains (curl|wget | sh, pip install from URL)
+ *  - Obfuscated commands (base64 -d | sh, hex encoding)
+ *  - Fileless execution (/dev/tcp, /dev/shm)
+ */
+
+const DANGEROUS_PATTERNS = [
+  // Shell chaining / injection
+  { pattern: /[;&|`$]\s*(?:\$\(|`|sh\b|bash\b|zsh\b|dash\b|python\b|perl\b|ruby\b|node\b)/i, weight: 5, label: 'shell metachar + interpreter' },
+  { pattern: /\|\s*(?:sh|bash|zsh|dash|python|perl|ruby|node)\b/i, weight: 6, label: 'pipe to interpreter' },
+  { pattern: /`[^`]{2,}`/, weight: 4, label: 'backtick command substitution' },
+  { pattern: /\$\([^)]{2,}\)/, weight: 4, label: '$() command substitution' },
+  { pattern: /;\s*(?:rm|mv|cp|chmod|chown|curl|wget|nc|bash|sh|python|cat|echo)\b/i, weight: 4, label: 'chained dangerous command' },
+
+  // Reverse shells
+  { pattern: /(?:bash|sh|zsh)\s+-i\s*>&?\s*\/dev\/(?:tcp|udp)\//i, weight: 7, label: 'reverse shell (/dev/tcp)' },
+  { pattern: /nc\b.{0,40}-e\s+(?:sh|bash|bin\/sh)/i, weight: 7, label: 'netcat reverse shell' },
+  { pattern: /ncat\b.{0,40}-e\s+(?:sh|bash)/i, weight: 7, label: 'ncat reverse shell' },
+  { pattern: /python.{0,60}socket.{0,40}(?:connect|send|recv)/i, weight: 6, label: 'python reverse shell' },
+
+  // Download-and-execute
+  { pattern: /(?:curl|wget)\b[^|;]{0,100}\|\s*(?:sh|bash|zsh|python|perl)/i, weight: 6, label: 'download-and-execute' },
+  { pattern: /(?:curl|wget)\b[^|;]{0,200}(?:-o|--output)[^|;]{0,60}(?:\/tmp|\/dev\/shm|\/var\/tmp)/i, weight: 4, label: 'download to temp (possible staging)' },
+
+  // Fileless / memory-only
+  { pattern: /\/dev\/(?:tcp|udp)\//i, weight: 5, label: '/dev/tcp or /dev/udp (network socket)' },
+  { pattern: /\/dev\/shm\//i, weight: 2, label: '/dev/shm (tmpfs, no disk trace)' },
+
+  // Obfuscation
+  { pattern: /base64\s+(?:-d|--decode)\s*\|?\s*(?:sh|bash|python|perl|eval)/i, weight: 6, label: 'base64 decode + execute' },
+  { pattern: /xxd\s+-p?\s*-r?\s*\|?\s*(?:sh|bash)/i, weight: 5, label: 'hex decode + execute' },
+  { pattern: /\\x[0-9a-fA-F]{2}\\x[0-9a-fA-F]{2}/, weight: 3, label: 'hex-encoded characters' },
+  { pattern: /\$\{IFS\}/, weight: 4, label: '${IFS} obfuscation' },
+  { pattern: /\$\{PATH:[\d:]+}/, weight: 4, label: 'PATH substring obfuscation' },
+
+  // Destructive
+  { pattern: /\brm\s+-[rf]+\s+(?:\/|~|\*|\.\.|\/\*|~\/\*)/i, weight: 7, label: 'destructive rm (root/home/glob)' },
+  { pattern: /\bmkfs\b/, weight: 7, label: 'mkfs (filesystem format)' },
+  { pattern: /\bdd\s+if=\/dev\/(?:zero|random|urandom)\s+of=\/dev\//i, weight: 7, label: 'dd to device' },
+  { pattern: /:\(\)\s*{\s*:\s*\|\s*:\s*&\s*};/, weight: 7, label: 'fork bomb' },
+
+  // Persistence
+  { pattern: /(?:>>|>)\s*(?:~\/)?\.(?:bashrc|zshrc|profile|bash_profile)/i, weight: 5, label: 'shell profile modification (persistence)' },
+  { pattern: /(?:chmod|chown)\s+[0-7]*777/, weight: 2, label: 'chmod 777 (overly permissive)' },
+
+  // Credential theft
+  { pattern: /cat\s+(?:~\/)?\.ssh\/id_rsa/, weight: 7, label: 'SSH private key read' },
+  { pattern: /cat\s+(?:~\/)?\.aws\/credentials/, weight: 7, label: 'AWS credentials read' },
+  { pattern: /(?:env|printenv)\s*\|/, weight: 3, label: 'environment dump piped' },
+];
+
+/**
+ * Scan a command string for injection patterns.
+ * @param {string} command
+ * @param {number} [threshold=8]
+ * @returns {{ score: number, hits: Array<{label: string, weight: number}>, blocked: boolean, reason?: string }}
+ */
+export function detectCommandInjection(command, threshold = 6) {
+  if (!command || typeof command !== 'string') return { score: 0, hits: [], blocked: false };
+
+  let score = 0;
+  const hits = [];
+
+  for (const { pattern, weight, label } of DANGEROUS_PATTERNS) {
+    pattern.lastIndex = 0;
+    if (pattern.test(command)) {
+      score += weight;
+      hits.push({ label, weight });
+    }
+  }
+
+  const blocked = score >= threshold;
+  return {
+    score,
+    hits,
+    blocked,
+    reason: blocked ? `command injection detected (score ${score} ≥ ${threshold}): ${hits.map(h => h.label).join(', ')}` : undefined,
+  };
+}
+
+/**
+ * Inspect a subprocess spawn spec for dangerous commands.
+ * @param {object} spec - spawn spec with argv and/or command.
+ * @param {number} [threshold]
+ * @returns {{ score: number, hits: Array<{label: string, weight: number}>, blocked: boolean, reason?: string }}
+ */
+export function inspectSpawn(spec, threshold = 6) {
+  const argv = Array.isArray(spec?.argv) ? spec.argv : [];
+  const command = typeof spec?.command === 'string' ? spec.command : '';
+  // Join argv into a string for pattern matching
+  const combined = command || argv.join(' ');
+  return detectCommandInjection(combined, threshold);
+}

package/dsh/cordis.patch.yml

@@ -0,0 +1,5 @@
+# agent-runtime-guard DSH plugin bundle layer:
+# auto-mounts when installed via `dsh plugin add agent-runtime-guard`.
+- insert:
+    - id: agent-runtime-guard
+      name: agent-runtime-guard/dsh

package/dsh/credentials.js

@@ -0,0 +1,169 @@
+/**
+ * @file Credential protection — detects and blocks credential exfiltration.
+ *
+ * Scans tool arguments and subprocess commands for:
+ *  - API keys, tokens, passwords in environment variables or arguments
+ *  - Credential file paths (~/.ssh, ~/.aws/credentials, .credentials.yaml)
+ *  - Patterns that look like secrets being sent to network destinations
+ */
+
+/** Patterns that indicate credential-like values. */
+const SECRET_PATTERNS = [
+  // OpenAI / Anthropic / generic API keys
+  { pattern: /sk-[A-Za-z0-9_-]{20,}/g, label: 'API key (sk-...)' },
+  { pattern: /ghp_[A-Za-z0-9]{36,}/g, label: 'GitHub token' },
+  { pattern: /gho_[A-Za-z0-9]{36,}/g, label: 'GitHub OAuth token' },
+  { pattern: /github_pat_[A-Za-z0-9_]{82,}/g, label: 'GitHub fine-grained PAT' },
+  { pattern: /xox[baprs]-[A-Za-z0-9-]{10,}/g, label: 'Slack token' },
+  { pattern: /AKIA[0-9A-Z]{16}/g, label: 'AWS access key' },
+  { pattern: /ASIA[0-9A-Z]{16}/g, label: 'AWS session token' },
+  // Private key blocks
+  { pattern: /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/g, label: 'private key block' },
+  // Generic high-entropy assignment patterns
+  { pattern: /(?:api[_-]?key|secret|token|password|passwd|auth|credential)["'\s:=]+["']?[A-Za-z0-9_\-]{16,}["']?/gi, label: 'credential assignment' },
+];
+
+/** Credential file path patterns that should never be read by untrusted tools. */
+const CREDENTIAL_PATHS = [
+  /\/\.ssh\//,
+  /\/\.aws\/credentials/,
+  /\/\.gnupg\//,
+  /\/\.netrc$/,
+  /\/\.pgpass$/,
+  /\.credentials\.ya?ml/,
+  /\/\.env(\.|$)/,
+  /\/\.docker\/config\.json/,
+  /\/\.kube\/config/,
+  /\/\.config\/gcloud\//,
+  /\/\.azure\//,
+  /id_rsa\b/,
+  /id_ed25519\b/,
+  /authorized_keys\b/,
+];
+
+/** Process environment variable names that hold secrets. */
+const SECRET_ENV_VARS = /^(?:.*_)?(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|AUTH|PRIVATE_KEY|ACCESS_KEY|SECRET_KEY)$/i;
+
+/**
+ * Scan a value (recursively) for secret patterns.
+ * @param {unknown} value - value to scan.
+ * @returns {Array<{label: string, snippet: string}>} findings.
+ */
+export function scanForSecrets(value) {
+  const findings = [];
+  const seen = new WeakSet();
+
+  function walk(val, path) {
+    if (val === null || val === undefined) return;
+    if (typeof val === 'string') {
+      for (const { pattern, label } of SECRET_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(val)) !== null) {
+          // Redact in snippet
+          const start = Math.max(0, match.index - 4);
+          const end = Math.min(val.length, match.index + match[0].length + 4);
+          const snippet = val.slice(start, end).replace(match[0], '[REDACTED]');
+          findings.push({ label, snippet: `...${snippet}...` });
+        }
+      }
+    } else if (typeof val === 'object') {
+      if (seen.has(val)) return;
+      seen.add(val);
+      if (Array.isArray(val)) {
+        val.forEach((v, i) => walk(v, `${path}[${i}]`));
+      } else {
+        for (const [k, v] of Object.entries(val)) {
+          // Check if the key name itself is secret-like
+          if (SECRET_ENV_VARS.test(k) && typeof v === 'string' && v.length > 4) {
+            findings.push({ label: `secret env/field "${k}"`, snippet: '[REDACTED]' });
+          }
+          walk(v, path ? `${path}.${k}` : k);
+        }
+      }
+    }
+  }
+
+  walk(value, '');
+  return findings;
+}
+
+/**
+ * Redact every known secret pattern inside a text string.
+ * Used by the post-execute hook to return cleaned output via
+ * `{ kind: 'accept', content }` under the v0.2.1 PostToolDecision contract.
+ *
+ * @param {string} text - text to clean.
+ * @returns {{ text: string, found: number, labels: string[] }} cleaned text,
+ *   match count, and de-duplicated pattern labels.
+ */
+export function redactSecretsInText(text) {
+  if (typeof text !== 'string' || text === '') return { text: text ?? '', found: 0, labels: [] };
+  let out = text;
+  let found = 0;
+  const labels = [];
+  for (const { pattern, label } of SECRET_PATTERNS) {
+    pattern.lastIndex = 0;
+    out = out.replace(pattern, (match) => {
+      found++;
+      if (!labels.includes(label)) labels.push(label);
+      return '[REDACTED]';
+    });
+  }
+  return { text: out, found, labels };
+}
+
+/**
+ * Check whether a file path targets a known credential location.
+ * @param {string} filePath
+ * @returns {string|null} matched pattern label, or null.
+ */
+export function isCredentialPath(filePath) {
+  for (const pattern of CREDENTIAL_PATHS) {
+    if (pattern.test(filePath)) {
+      return pattern.source;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check whether a subprocess command or environment includes secrets.
+ * @param {object} spec - subprocess spawn spec.
+ * @returns {Array<{label: string, detail: string}>} findings.
+ */
+export function scanSubprocessForCredentials(spec) {
+  const findings = [];
+
+  // Check argv for secret patterns
+  const argv = Array.isArray(spec?.argv) ? spec.argv : [];
+  const cmdStr = argv.join(' ');
+  if (cmdStr) {
+    const secretHits = scanForSecrets(cmdStr);
+    for (const hit of secretHits) {
+      findings.push({ label: hit.label, detail: `in command: ${hit.snippet}` });
+    }
+  }
+
+  // Check for credential file access in the command
+  for (const arg of argv) {
+    if (typeof arg === 'string') {
+      const credPath = isCredentialPath(arg);
+      if (credPath) {
+        findings.push({ label: 'credential file access', detail: `command references ${arg}` });
+      }
+    }
+  }
+
+  // Check environment variables being passed
+  const env = spec?.env;
+  if (env && typeof env === 'object') {
+    for (const [key, val] of Object.entries(env)) {
+      if (SECRET_ENV_VARS.test(key)) {
+        findings.push({ label: 'secret in subprocess env', detail: `env var ${key} exposed to child process` });
+      }
+    }
+  }
+
+  return findings;
+}