Pod

pod — least-privilege compiler for AI agents

Your agent ran for a week. pod compiles what it actually did into the smallest policy it needs.

让 AI Agent 只拥有它真正需要的权限——从真实行为编译最小权限策略。

Record → compile → enforce → prove.

Most agent security tools stop at one of two places: a scanner that tells you what your agent could touch, or a gateway that asks you to hand-write a policy. pod closes the loop — run your agent in record-only mode for a few days, compile a least-privilege policy from its real tool calls, enforce it, and keep tamper-evident evidence for everything that ran.

record real calls ──▶ compile least-privilege policy ──▶ enforce (deny > approve > allow)
       │                        │                                  │
       │                        │                                  ▼
       │                        │                    ┌──────────────────────────┐
       └── SHA-256 hash chain ───┴───────────────────▶│ tamper-evident audit     │
          (every call, hashes only)                  │ verify / export evidence │
                                                     └──────────────────────────┘

中文速览

• 不是又一个 MCP 网关：网关让你手写策略；pod 从 agent 的真实行为里编译出最小权限策略。
• 闭环：pod record（只录不拦）→ pod policy draft（生成策略 + 与基线 diff）→ 人工复核 → pod serve（执法）。
• 证据：每一次工具调用进入 SHA-256 哈希链，可校验、可导出为证据包（敏感内容只存哈希）。
• 本地优先：策略、审计、密钥不出你的机器；Pod Cloud 是可选控制平面。

See it in 5 minutes

No agent, no account, no data leaves your machine — everything runs in a temp directory:

git clone https://gitee.com/suhuisoftwares/pod.git && cd pod
pnpm install && pnpm build
bash scripts/demo-least-privilege.sh

It seeds a realistic week of tool calls (reads, writes, a delete, and one .env access), then compiles a policy from that corpus and diffs it against a permissive baseline:

## 策略 diff（baseline → draft）

| server     | tool                 | baseline | draft      | 变化     |
|------------|----------------------|----------|------------|----------|
| *          | *                    | allow    | deny       | 默认决策 |
| filesystem | read_file            | allow    | deny       | 收紧     |
| filesystem | write_file           | allow    | approve    | 收紧     |
| filesystem | delete_file          | allow    | deny       | 收紧     |
| github     | create_pull_request  | allow    | approve    | 收紧     |
| shell      | execute_command      | allow    | approve    | 收紧     |
| filesystem | get_file_info        | allow    | (unlisted) | 移除     |

**汇总**：收紧 8 · 新增 0 · 移除 1 · 放宽 0

Two details matter here: read_file is locked down because it touched .env once (observation beats guessing), and get_file_info is removed because it never appeared in the corpus (least privilege = don't grant what you didn't observe).

Install

# macOS / Linux — builds from source, no npm account needed
# 链接钉在发布版上（可复现）：想跟主干就把 v0.4.2 换成 main
curl -fsSL https://gitee.com/suhuisoftwares/pod/raw/v0.4.2/scripts/install.sh | sh
# 主源连不上时用 GitHub 镜像（同一个脚本）：
# curl -fsSL https://raw.githubusercontent.com/suhui-organization/pod/v0.4.2/scripts/install.sh | sh
pod --help

The installer clones v0.4.2 to ~/.pod/src, builds, and puts pod in ~/.local/bin. Override with POD_SRC, POD_BIN_DIR, POD_REPO_URL, POD_VERSION（POD_VERSION=main 跟主干）。

中文 / English：CLI 输出支持中英切换——pod --lang en-US <cmd>，或设一次 POD_LANG=en-US（也会读 LC_ALL / LANG）。默认中文；未翻译的句子原样显示， 不会出现空白或 key 名。pod guard 与 pod harden 的报表、威胁目录与交付物 整篇有英文（含 finding 正文与策略草稿的判定依据），由 CI 断言守门。 覆盖进度自查：bash scripts/i18n-coverage.sh （列出还没英文词条的串和词表里的僵尸键，--strict 有缺口时退出 1）；控制台另有 真机逐页验收 bash scripts/web-acceptance.sh（指到 k8s 后端、无头 Chrome 点一遍， 断言"每页都渲染了内容且没有非数据中文"）。

Run the MCP gateway as a container

同一个网关也能以自包含镜像运行：镜像里已经构建好 CLI、预装了上游 filesystem server， 默认用 baseline 策略（只读工具放行，写操作进审批），从 stdio 暴露 MCP。

docker build -f deploy/Dockerfile.mcp -t pod-mcp .
docker run -i --rm pod-mcp        # 接到任意 MCP 客户端即可（stdio）

要换成别的上游 server 或策略，覆盖 entrypoint 参数即可；默认等价于 pod serve --agent glama --server filesystem --command mcp-server-filesystem --arg /workspace。 （公开目录收录时要求的检查也是这两步：进程能启动、能响应 initialize / tools/list。）

Requires Node.js ≥ 22.13 (pnpm 11's runtime floor) and git.

What's in this repo

一个仓库包含完整闭环：本地在 agent 机器上执法，云端（可选）做跨机器视图。

能力与价值速览见 docs/FEATURES.md。

From source:

git clone --branch v0.4.2 --depth 1 https://gitee.com/suhuisoftwares/pod.git && cd pod
pnpm install && pnpm build
node apps/cli/dist/index.js --help

npm i -g @podsec/cli is not live yet — use the installer above until the package is published.

From zero to enforcement

pod scan                              # 1. see what is exposed (read-only)
pod onboard                           # 2. preview the takeover plan (dry-run)
pod onboard --yes                     #    wrap agents in record-only mode (backups kept)
# ... use your agents normally for a day or two ...
pod policy draft --diff <baseline>    # 3. compile least-privilege policy + show the diff
pod lint --policy ~/.pod/policies/draft.json
pod serve --agent <name> --server <name> --policy ~/.pod/policies/draft.json \
  --command <cmd> --arg <value>       # 4. switch to enforcement
pod watch                             # 5. approve high-risk calls from a second terminal
pod verify-audit                      #    tamper check over the whole chain
pod export-evidence                   #    verifiable evidence bundle

What pod is / is not

Compared with the rest of the market: platform-native sandboxes (Claude Code, Codex, Gemini CLI) protect one agent; MCP gateways (agentgateway, ToolHive, ContextForge, Docker) give you a place to enforce hand-written rules; scanners (Snyk Agent Scan, mcp-guard) tell you what is exposed. pod is the missing step between "what is exposed" and "what is allowed": it writes the policy for you from observed behavior, then proves what happened.

Core capabilities

• pod policy draft — compile a least-privilege policy from recorded calls. Read-only tools → allow, write/exec → approve, destructive → deny; any observed sensitive-path or secret hit forces deny. --diff <baseline.json> prints exactly what got tightened, added, removed or loosened.
• Policy gate — evaluated deny > secrets-input > approve > allow, fail-closed by default; unlisted servers/tools are denied.
• Approval gate — high-risk calls suspend and wait for a human; timeout fails closed; approvals are recorded with approver + reason.
• Tamper-evident audit — append-only SHA-256 hash chain; pod verify-audit detects any historical edit; sensitive content is stored as hashes only.
• Evidence bundles — pod export-evidence / pod verify-evidence produce and verify a portable evidence bundle plus a one-page report.
• Secret gates — sensitive input paths (.env, .ssh, .aws, …), known-format output regexes, and high-entropy fallback detection for unknown secret formats.
• Rollback points — pod serve --snapshot captures write operations; pod rollback restores files.
• Coverage + drift — pod coverage --strict exits non-zero when an MCP server is bypassing the gateway.
• Supply-chain gate (T4) — the gateway validates the declared server source (command / package / version) before startup.
• Control-plane posture (pod posture) — same rules, applied to the control plane: lifecycle hooks, frozen config, memory files, MCP package sources, agent identities, delegation chains. Drift is reported against a pod posture freeze baseline; --strict exits 1.
• User-owned rules — every verdict comes from ~/.pod/rules.json (or --rules <file>): risk patterns, severities, thresholds, trusted sources, egress lists. Code ships defaults; you own the decisions. Invalid rules fail closed.
• Hardening audit deliverable (pod harden) — one command runs multi-harness scan + exposure scan + control-plane posture + least-privilege compilation + evidence export and writes a client-ready report directory: executive summary, scope and method, prioritized to-dos with runnable commands, an honest coverage-boundary section, and a per-file sha256 manifest. --client / --auditor / --engagement stamp the cover; pod harden --verify <dir> lets the recipient re-check every artifact by hash without trusting the sender. Local only, never uploaded; secrets appear as masks, never prefixes.
• Continuous agent/harness guard (pod guard) — scans 16 harnesses (Claude Code, Codex, Cursor, DSH, OpenClaw, OpenCode, Gemini CLI, Windsurf, Zed, VS Code, Cline, Kilo, Amazon Q, Copilot CLI, Amp, Continue), 5 config formats (incl. Codex TOML) plus project-level .mcp.json / .cursor/mcp.json / .vscode/mcp.json, and reports against an 18-entry threat catalog (AG-01…AG-18, each with cited sources and an honest coverage verdict). Output opens with the three things to do first — each a copy-paste pod command bound to the harness it affects (pod agents enroll --harness claude-code) plus the command that confirms it worked — then the vulnerability list and a prioritized recommendation list, and finally a hand-off to the deliverable (pod harden). pod guard baseline + pod guard watch make it continuous: it only speaks on new/changed/gone findings and writes those to the hash chain. pod guard remediate --llm has a model draft proposals from an outbound allowlist that carries no paths, no hostnames and no config text; rule deltas must pass the same relaxation guard as pod rules apply, and any non-pod command is stripped.
• Enrollment from the console (pod agents / the "Enroll" button) — one click scans the host for installed harnesses and lists them as cards with their evidence, MCP-server count, how many of those bypass the gateway, and their pod guard finding counts. Enrolling an agent creates an ed25519 identity, a zero-permission policy (unregistered servers denied) and an audit directory, then appends kind=identity / config-change events to that agent's hash chain — so pod sync carries them to the cloud's control-plane view (machine-wide facts stay on the local _control chain). It never rewrites harness configuration — that stays with pod onboard --yes (which backs up and can revert). Enrolling is idempotent, removable (forget, identity kept by default), and pod ui --read-only turns the whole write path off. The console's POST endpoints require the token, Content-Type: application/json and a same-origin Origin.
• Takeover (pod agents onboard / the "Take over" button) — step two: rewrites each MCP server's command to pod serve --record-only … --command <original> so calls actually cross the gateway. Because it edits your files, the console shows the before/after command per server, the backup path and the "records but does not block" caveat before you confirm. It only touches user-level configs (never repo-level .mcp.json), refuses to run when pod is not on PATH (a broken wrapper would take every MCP server down), and reuses your existing zero-permission policy instead of writing an allow:['*'] template — so dropping --record-only later fails closed rather than open. pod agents revert --agent <name> restores from the most recent .pod-backup-*.
• Enforcement switch (pod agents enforce / the "Enforce" button) — step three: drops --record-only and points the wrapper at your compiled policy, so the gateway actually decides. The failure mode here is not "broke the config" but "looks enforced while protecting nothing", so it hard-refuses unless a policy exists that is bound to the agent, has server rules, and is not allow:["*"] — and the dialog shows which policy is in force, its allow/approve/deny counts and how much corpus it was compiled from. Switching back to record-only, or "restore config" (which undoes one step at a time), are both one click.
• Subscribed rules (pod rules) — rules ship as signed Ed25519 packs (pack / verify / apply / pull). Network sources must be verified. A pack that would loosen any of your existing rules is refused unless you pass --allow-relax, so an "update" can never silently weaken your posture.
• Policy red team (pod redteam) — attack scenarios are drilled against your policy through the same pure pipeline the gateway uses (decideCall), so "blocked" means blocked in production too, and the results are reproducible in CI. A model can propose scenarios (--llm), but only as data: it never gets a verdict, never gets execution, and never touches an MCP server. Only the capability surface (server/tool names + verdicts) leaves the machine, and every model call is written to the hash chain as kind=llm-call.
• Agent identities + delegation narrowing (pod identity / pod delegate) — ed25519 keypair per agent; delegations are signed hop-by-hop and must narrow capabilities; --ttl bounds every hop.
• JIT grants (pod grant) — signed, time-boxed, scope-limited tokens; a valid grant satisfies an approve decision without a human in the loop, and single-use grants are consumed atomically.
• Circuit breaker (pod quarantine) — quarantine an agent and the gateway denies its calls on the next invocation (no restart), with the decision written to the audit chain.
• Trust-propagation anomalies + pollution tracing (pod anomaly / pod trace) — thresholds from rules.anomaly; trace walks the delegation chain and the audit chain to find where a poisoned agent came from and who it could reach.

Policy example

{
  "version": "0.1.0",
  "agent": "openclaw",
  "defaultDecision": "deny",
  "servers": {
    "filesystem": {
      "allow":   ["read_file", "list_directory", "search_files"],
      "approve": ["write_file", "edit_file"],
      "deny":    ["delete_file"]
    }
  },
  "secrets": {
    "deny_input_paths": ["~/.ssh", ".env", "credentials", "id_rsa", ".aws", "known_hosts"],
    "deny_output_matching": ["ghp_[A-Za-z0-9]{36}", "sk-[A-Za-z0-9]{20,}", "AKIA[0-9A-Z]{16}"],
    "entropy": { "enabled": true, "min_length": 24, "threshold": 4.5, "block": true }
  }
}

CLI

pod init            scaffold policy templates (baseline / record)
pod onboard         discover local MCP servers and wrap them behind pod (dry-run by default)
pod serve           run the gateway (stdio / Streamable HTTP)
pod record          record-only mode: log every call without blocking (corpus collection)
pod policy draft    compile a least-privilege policy from real calls (+ --diff baseline)
pod approve|deny|pending   side-channel approvals
pod watch           resident approval queue
pod snapshots       list write-operation snapshots (rollback points)
pod rollback        restore files from a snapshot (serve --snapshot enables capture)
pod timeline        audit timeline filtered by agent / tool / time
pod verify-audit    verify the full hash chain, emit a report
pod digest          local weekly security digest (no network)
pod coverage        managed vs. unmanaged MCP servers; --strict exits 1 on drift
pod export-evidence / verify-evidence   export & verify evidence bundles
pod lint | doctor   policy lint / environment health
pod scan            free local security scan (config & bypass checks)
pod guard [scan]    continuous multi-agent / multi-harness vulnerability scan → vulnerability list + prioritized recommendations
pod guard watch     re-scan on an interval; speaks only on new/changed/gone findings, records them in the audit chain
pod guard remediate --llm   model drafts hardening proposals (never auto-applied; must pass the relaxation guard)
pod guard catalog   the threat catalog (AG-01…AG-18) with sources and pod's coverage for each
pod agents [scan]   list the harnesses installed on this machine (and whether each is already enrolled)
pod agents enroll --harness <id>   enroll one: identity + zero-permission policy + audit dir (never touches harness config)
pod agents onboard --harness <id> [--yes]   take over (rewrite that harness's MCP servers to go through the gateway; backup + revert)
pod agents enforce --harness <id> [--record-only] [--yes]   switch to enforcement (or back to record-only) — refuses unless a compiled policy exists
pod agents revert --agent <name>   restore the config from the most recent .pod-backup-*
pod agents forget --agent <name>   remove the enrollment (policy deleted; identity kept unless --purge-identity)
pod ui [--read-only]   local console; the "Scan this machine" + "Enroll" + "Take over" buttons call the same write paths as pod agents
pod harden          one-shot hardening audit: harness scan + exposure + posture + policy draft + evidence → client-ready report directory (--verify re-checks a delivered one)
pod posture [freeze]   control-plane posture: hooks / frozen config / memory / packages / identities / delegations
pod rules              rule packs for subscribed hardening: show | pack | verify | apply | pull
pod redteam            attack scenarios vs. your policy (offline built-in library, or --llm generated); exit 1 on a high-severity bypass
pod identity           per-agent ed25519 identity: init | list | verify
pod delegate           signed delegation: issue | verify | check (capability narrowing)
pod grant              JIT capability tokens: issue | list (signed, TTL, scope, single-use)
pod quarantine         circuit breaker: list | add | remove (enforced by the gateway)
pod anomaly            convention-burst / capability-spread signals over the rules window
pod trace <agent>      pollution tracing: delegation chain + related audit entries
pod graph build     static capability graph from agent configs + tool schemas
pod graph toxic     source→sink toxic paths + targeted policy diff
pod graph explain   trace a path back to evidence
pod sync / pull-policy   optional Pod Cloud sync & policy distribution

Supported agents

Documentation

• 能做什么、给你带来什么 ← 先看这个
• 部署 Pod Cloud（云端控制平面） ← 部署与"你需要提供什么"

云端控制平面原先分两个独立仓库（podcloud-server / podcloud-web）， 已并入本仓库 cloud/ 下并归档原仓库——历史链接会看到指向这里的告示。

• Positioning & wedge
• Threat model
• Multi-agent / multi-harness security ← 现状盘点 · 威胁目录 · 差距
• Egress defense
• Control-plane hardening (requirements + design)
• Agent onboarding
• Automation (launchd/systemd/cron)

Pod Cloud (optional, in this repo)

本地部分开箱可用，云端是可选的：没有它，pod 照样编译策略、执法、留证据。 需要跨机器/跨 agent 的统一视图、策略下发、告警与合规报告时，一条命令起一个：

bash deploy/install.sh            # 单机 Docker Compose（首次 2-5 分钟）
# 或带管理员：ADMIN_EMAIL=you@x.com ADMIN_PASSWORD='...' bash deploy/install.sh

数据方向是单向的：本地只推 SHA-256 哈希上云，审计原文不出你的机器；云端不参与本地执法（云端挂了 agent 不受影响）。 必填配置只有一项（JWT 密钥，脚本自动生成），其余见 docs/deploy-cloud.md。

Sponsor

pod is Apache-2.0 and stays that way: the CLI, the gateway, the audit chain and the evidence export are complete on your own machine, and nothing is locked behind a sponsorship. Sponsorship pays for the parts that do not demo well — CI minutes, a machine to run the multi-harness attack suites on, and the security maintenance that only shows up as absence of incidents.

The only official channel is GitHub Sponsors: github.com/sponsors/suhui-organization (or the Sponsor button at the top of this repository).

赞助不是解锁功能的前置条件——核心能力本地全都有。不给钱也一样欢迎：提一个真实的 误报、贴一份 pod scan 的输出、或者帮下一个人装起来，都是等价的帮忙。

License

Apache-2.0 — see LICENSE. Security notes: SECURITY.md.