> **从 `mode` 之前的版本升级？** 向后兼容性得到保留：早于按规则模式的策略（它设置了 `settings.block_categories`，但没有 `default_mode`，也没有规则级别的 `mode`）会保持原有行为 — 使用 `--mode enforce` 安装时，这些类别仍然会被阻止。一旦你的策略采用按规则模型（任何 `mode`/`default_mode`），它就会完全由策略决定，如上所述。

---

## 架构<a name="how-it-works" />

每次工具调用都走同一条路径：它通过**集成面**（第 1 阶段）进入，在**执行前被评估**（第 2 阶段），产生允许/警告/阻止判定，并落入**防篡改证据**（第 3 阶段）。第 4 阶段是可选的 — 一个自托管控制平面，一旦设备注册，其签名策略便成为第 2 阶段的权威依据。```mermaid
flowchart TD

%% ── sources ────────────────────────────────────────────────
subgraph SRC["Agents Prismor protects"]
    direction LR
    AC["<b>Coding agents</b><br/>Claude Code · Codex · Cursor · Windsurf · Copilot<br/>OpenClaw · Hermes · Grok · Kiro · Crush<br/>OpenHands · Qwen · Continue · Goose"]
    AF["<b>Production frameworks</b><br/>OpenAI Agents · LangChain / LangGraph · CrewAI · browser-use<br/>Pydantic AI · AutoGen Core · Agno · Semantic Kernel · Google ADK<br/>BeeAI · Claude Agent SDK · Vercel AI SDK · Mastra"]
end

%% ── stage 1 ────────────────────────────────────────────────
subgraph ENTRY["Stage 1  ·  Integration surface"]
    direction LR
    H(["<b>Runtime hooks</b><br/>pre / post tool-call<br/>per-agent config"])
    G(["<b>MCP gateway</b><br/>fronts every MCP server<br/>injection-scans responses"])
    F(["<b>Framework adapters</b><br/>in-process + HTTP eval server<br/>per-user via use_subject"])
end

%% ── stage 2 ────────────────────────────────────────────────
subgraph EVAL["Stage 2  ·  Evaluated before the call executes"]
    direction TB
    D(["<b>Tool-call dispatcher</b>"])
    P["<b>Policy engine</b><br/>YAML rules · per-rule observe / enforce<br/>layered org → project → repo · non-overridable floor"]
    CHK["<b>Pre-execution checks</b><br/>Semantic guard · Egress control · MCP guardrails · Tool tags<br/>IAM and agent controls · Scoped session rules<br/>Script-content inspection · Docker sandbox"]
    SEC["<b>Secret and supply-chain protection</b><br/>Cloak placeholders + output scrub · Env guard · Sweep<br/>Canary tripwires · Skill scanner<br/>Supply-chain scoring → npm · pip · cargo · go"]
end

FEED[/"Signed advisory feed  ·  Prismor intel + NVD"/]
V{"<b>Allow  ·  Warn  ·  Block</b><br/>every block prints narrowest-first unblock steps"}

%% ── stage 3 ────────────────────────────────────────────────
subgraph EV["Stage 3  ·  Evidence and feedback"]
    direction LR
    ST[("<b>Session store</b><br/>SQLite + JSONL<br/>session forensics")]
    VIEW["<b>Views</b><br/>Web + terminal dashboard<br/>Status · Tokens · Audit · Doctor"]
    PROOF["<b>Tamper-evident</b><br/>Signed trail — hash chain + Ed25519<br/>Attestation bundle · Host discovery"]
    LEARN["<b>Learning</b><br/>propose rules · flag false<br/>positives · detect evasion"]
end

PAST[/"Transcript ingest  ·  replays pre-install history through the live policy"/]

%% ── stage 4 ────────────────────────────────────────────────
subgraph ORG["Stage 4  ·  Optional self-hosted control plane"]
    direction LR
    RP["<b>Signed remote policy</b><br/>layered rules · time-boxed<br/>exemptions · pause / resume"]
    TEL["<b>Live telemetry</b><br/>redacted events<br/>offline spool"]
    OD["<b>Org dashboard</b><br/>policy · devices<br/>sessions · approvals"]
end

%% ── flow ───────────────────────────────────────────────────
AC --> ENTRY
AF --> ENTRY
ENTRY --> D
D --> P
P --> CHK
P --> SEC
FEED -.-> SEC
CHK --> V
SEC --> V
V --> ST
PAST -.-> ST
ST --> VIEW
ST --> PROOF
ST --> LEARN
LEARN -.->|"proposed rules"| P
RP ==>|"authoritative once enrolled"| P
ST -->|"redacted"| TEL
TEL --> OD

会话、发现、威胁类别、代理明细以及实时事件流——全部来自本地工作区数据库，无需云端。

<h3>自托管仪表盘 </h3>

<img width="1500" height="771" alt="image" src="https://assets.kitploit.com/production/public/readmes/13903/4803ea2755c08fa3f6d987eea1a23e0db9aa8d18d748f0160fee2e19cce765f2.png" />


### 供应链执行<a name="supply-chain-enforcement" />

`prismor` 包装你的软件包管理器，并在每次安装运行前根据实时威胁情报进行评分——存在时间、维护者数量、安装脚本以及已知 IOC。内置对 **mini-shai-hulud**（2026 年 5 月）和 **AntV 维护者劫持** 攻击（2026 年 5 月）的覆盖。```bash
prismor supplychain npm install express                    # passes, runs npm
prismor supplychain npm install @tanstack/react-router     # BLOCK: IOC match (score 100)
prismor supplychain pip install requests numpy
prismor supplychain pnpm add lodash

有关完整评分表、生态系统支持和 IOC 格式，请参阅 [docs/supply-chain.md](https://github.com/prismorsec/prismor/blob/HEAD/docs/supply-chain.md)。

---

## 禁用 Prismor<a name="disabling-prismor" />

有三个独立的层级，每一层都可以限制代理会话。禁用其中一个并不会禁用其他层——请选择与你真正想要关闭的层级相匹配的那个。

### 1. 完全卸载 hooks

从代理的 hooks 配置中移除 `hook-dispatch` 条目，从而使 Prismor 完全不再接收 `PreToolUse`/`PostToolUse`/`UserPromptSubmit` 事件。```bash
prismor uninstall-hooks --agent claude --scope project   # this workspace only
prismor uninstall-hooks --agent claude --scope user      # global (all workspaces)
prismor uninstall-hooks --agent all --scope project      # every supported agent, this workspace

`--mode observe` 记录发现结果而不进行阻断。`PRISMOR_LOCAL_DRY_RUN=1` 会额外抑制任何在 observe 模式安装的钩子下本应被阻断的发现结果的阻断行为（`prismor/runtime/cli.py`，在 `args.mode == "observe"` 时检查）。如果你希望 Prismor 的遥测/日志在暂时停止强制执行时继续工作，这就是正确的开关。

这**不会**影响在 `.prismor/policy.yaml` 中设置为 `mode: enforce` 的策略规则——无论钩子如何安装，这些规则仍以策略为准（参见上文 [观察 / 强制](#observe--enforce-per-rule-policy-authoritative)）。

### 3. 清除会话的 scoped-agent 规则

[Scoped Agent](https://github.com/prismorsec/prismor/blob/HEAD/docs/scoped-agent.md) 会在 `.prismor/scoped/{session_id}.json` 中生成每个会话的 `allowed_tools`/`deny_tools` 列表。**此检查与钩子的 `--mode` 无关**——`deny_tools` 中的工具在 `prismor/runtime/scoped_agent.py` 中被硬编码为 `action: block` / `mode: enforce`，因此即使钩子以 `--mode observe` 安装，它也会阻断。卸载钩子或切换到 observe 模式不会解除 scoped 拒绝。```bash
prismor scope list                    # find the session ID
prismor scope show --session-id ID    # inspect its allowed_tools / deny_tools
prismor scope clear ID                # remove the scoped rules for that session
prismor scope edit ID                 # or hand-edit deny_tools in $EDITOR