dansaurabh/Chara

# CHARA — AI Runtime Intelligence Platform **针对本地 AI 运行时的主动主机级发现与可解释威胁建模** CHARA 可以映射开发者或企业计算机上完整的 AI 攻击面。它能发现本地已配置或正在运行的每个 Model Context Protocol (MCP) server，对每个 server 的功能进行分类（如 shell 执行、文件访问、网络出口），使用安全且非破坏性的 payload 主动验证其可利用性，并生成专为安全分析师或企业管理员定制的可解释 runtime intelligence 报告。 ## 发现的内容 | 发现类型 | 来源 | 风险示例 | |---|---|---| | IDE 配置中的凭证 | `hunter` | Claude Desktop `env` 块中的 AWS key | | 不安全目录中的 MCP server | `hunter` | 从 `/tmp` 提供服务的二进制文件 | | 正在运行的 MCP 进程 | `recon` | cmdline 中包含 MCP 关键字的 Python 进程 | | 未经身份验证的 TCP MCP endpoint | `probe` | 在 loopback 上暴露了 `execute_bash` 工具，已验证执行 | | Stdio MCP server（所有已注册的 IDE） | `ghost` | 在 Cursor + Gemini 中注册了具备 Shell 能力的 server | | 注册为 MCP server 的未知二进制文件 | `ghost` | 没有解释器的独立绝对路径二进制文件 | | 已安装的 AI 工具 | `inventory` | VS Code、Copilot、Ollama、Claude Code、Gemini CLI | ## 架构 ``` main.py └── engine.py Facade — coordinates all scanners ├── inventory.py Phase 0 — AI-BOM: IDEs, extensions, CLI agents, runtimes ├── hunter.py Phase 1 — Static config scan (Claude/Cursor/Windsurf/Gemini/JetBrains) ├── recon.py Phase 2 — Live process table scan ├── ghost.py Phase 3 — Stdio subprocess probe (deep mode only) ├── probe.py Phase 4 — TCP JSON-RPC interrogation + echo verification └── export.py Phase 5 — ARS scoring, JSON export, narrative summary src/explain.py Explainability Engine — converts Finding → Explanation src/classify.py Tool manifest classifier — edge detection from tool names/descriptions src/models.py DTOs: Finding, Explanation, ScanContext, CharaGraph, ARSResult ``` 所有扫描器共享一个 DTO (`Finding`)。所有配置均通过 `ScanContext` 流转。各扫描器模块之间没有交叉导入。Explainability Engine (`explain.py`) 是纯逻辑——没有 I/O 操作，也没有发现调用。 ## ARS 评分 CHARA 使用 **Agentic Risk Score (ARS)** 矩阵对每个发现进行评分： | 评分 | 条件 | |---|---| | `CRITICAL` | 未经身份验证的 RPC + shell 执行能力，或进程以 root/SYSTEM 身份运行 | | `HIGH` | 未经身份验证的 RPC + 文件访问或网络出口 | | `MEDIUM` | 静态配置中发现明文凭证 | | `LOW` | 未经身份验证的 RPC，且仅包含良性实用工具 | ## 可信度阶梯 CHARA 区分了观察到的情况和已确认的情况： | 标签 | 含义 | 适用情形 | |---|---|---| | `EXECUTION VERIFIED` | Echo 探测返回了确切的字符串 | Shell 工具接受了 `echo 'CHARA-VALIDATION'` | | `HANDSHAKE VERIFIED` | 完成了完整的 MCP 协议 | Ghost 探测完成了 stdio 握手 | | `CAPABILITY OBSERVED` | Server 响应，声明了能力 | 返回了 `tools/list` 但无需 echo 探测 | | `CONFIGURATION ONLY` | 仅在配置文件中看到，未实际运行 | 端口关闭或 server 未运行 | | `PROCESS OBSERVED` | 进程匹配 MCP 模式 | 进程扫描匹配，无主动探测 | ## 安全 Payload 契约 当检测到 shell 执行时，CHARA 会准确地发送一个主动 payload： ``` echo 'CHARA-VALIDATION' ``` 仅当响应中出现确切的字符串 `CHARA-VALIDATION` 时，才会设置 `EXECUTION VERIFIED`。绝不发送任何破坏性、改变状态或通过网络传播的 payload。Ghost 探测会在最小化的环境中生成 subprocess（macOS/Linux 上仅包含 `PATH`，Windows 上包含七个安全键）——凭证永远不会被转发到生成的进程中。 ## GhostRisk 检测 CHARA 使用操作系统原生信号来标记未知的 stdio 二进制文件——没有硬编码列表： - **独立二进制文件信号** — 命令是一个绝对路径，且参数中没有解释器运行目标。合法的 MCP server 几乎总是 `interpreter + target`（例如 `npx -y @org/server`、`python3 -m module`）。独立的绝对路径二进制文件是不寻常的。 - **隔离属性（仅限 macOS）** — 检查 `com.apple.quarantine` xattr。存在该属性意味着二进制文件来自不受信任的下载渠道。Homebrew 和系统包管理器在安装时会清除此属性。 ## 环境要求 - Python 3.11+ - `psutil >= 5.9.0, < 7` ``` pip install -r requirements.txt ``` ## 用法 ``` python3 main.py [OPTIONS] ``` ### 选项 | 标志 | 默认值 | 描述 | |---|---|---| | `--scan-mode fast\|balanced\|deep` | `balanced` | 扫描深度。`fast` 约 2 秒，`balanced` 约 10 秒，`deep` 约 30 秒以上 | | `--ghost-probe` | 关闭 | 生成 stdio MCP server 以验证能力（仅限 deep 模式） | | `--no-probe` | 关闭 | 跳过 TCP 探测——仅限 hunter + recon | | `--audience analyst\|admin` | `analyst` | 输出视图：安全评估或管理员治理 | | `--ports N [N ...]` | 内置列表 | 覆盖要探测的 loopback 端口 | | `--output FILE` / `-o` | `chara_graph_export.json` | JSON 导出路径 | | `--verbose` / `-v` | 关闭 | 扫描期间的逐模块详情 | ### 示例 ``` # 快速 passive scan python3 main.py --scan-mode fast # 带有 stdio 验证的全面深度扫描 — 分析师视图 python3 main.py --scan-mode deep --ghost-probe --verbose # 管理员治理报告 python3 main.py --scan-mode deep --ghost-probe --audience admin # CI/CD gate — 探测特定端口，遇到 CRITICAL 时失败 python3 main.py --scan-mode balanced --ports 3000 8080 8989 echo "Exit: $?" # 4=CRITICAL 3=HIGH 2=MEDIUM 1=LOW 0=clean ``` ### 退出代码 | 代码 | 含义 | |---|---| | `0` | 无发现 | | `1` | 最高级别的发现为 LOW | | `2` | 最高级别的发现为 MEDIUM | | `3` | 最高级别的发现为 HIGH | | `4` | 最高级别的发现为 CRITICAL | 使用退出代码来控制 CI/CD pipeline——当检测到 MCP 风险时，非零退出将阻止构建。 ## 输出 CHARA 生成两个部分：首先是 AI-BOM 清单，随后是威胁面报告。 ### 分析师视图（默认） ``` ======================================================================= CHARA AI Runtime Intelligence Report — Security Assessment 2026-06-27 14:22 | Mode: deep | 3 finding(s) ======================================================================= [CRITICAL] Cursor Desktop -- filesystem-mcp Confidence: EXECUTION VERIFIED Transport: TCP 127.0.0.1:1235 Cursor Desktop has a server on port 1235 exposing a shell execution tool (execute_bash). The tool was actively verified — it accepted and executed a test command with no authentication required. Chain: Cursor Desktop -> filesystem-mcp -> execute_bash -> Developer Authority (developer) -> No Authentication -> Arbitrary Execution Risk Evidence: * tools/list returned: [execute_bash, read_file, write_file] * Echo probe confirmed: "CHARA-VALIDATION" (exact match) * Config: ~/.cursor/mcp.json -> "filesystem-mcp" Analyst: Verified RCE surface. No credential required to invoke execute_bash. Enumerate available paths, environment variables, and network access from this execution context. ----------------------------------------------------------------------- [MEDIUM] Cursor Desktop -- data-server (config) Confidence: CONFIGURATION ONLY Cursor Desktop configuration at ~/.cursor/mcp.json contains a plaintext AWS key for 'data-server'. Evidence: * Credential found: aws_access_key -> AKIA...EXAMPLE Analyst: Determine whether this credential is valid and what cloud resources it grants access to. Check for credential reuse. ======================================================================= CRITICAL: 1 HIGH: 0 MEDIUM: 1 LOW: 0 | Total: 2 Confidence: EXECUTION VERIFIED: 1 | CONFIGURATION ONLY: 1 ======================================================================= ``` ### 管理员视图（`--audience admin`） 相同的扫描，但使用侧重于治理的语言： ``` ======================================================================= CHARA AI Runtime Intelligence Report — Administrator View 2026-06-27 14:22 | Mode: deep | 3 finding(s) ======================================================================= [CRITICAL] Cursor Desktop -- filesystem-mcp Confidence: Actively Verified Cursor Desktop has a server on port 1235 exposing a shell execution tool (execute_bash). The tool was actively verified — it accepted and executed a test command with no authentication required. Evidence: * tools/list returned: [execute_bash, read_file, write_file] * Config: ~/.cursor/mcp.json -> "filesystem-mcp" Admin: Immediate review required. Disable or restrict this server if not actively needed for approved workflows. Verify this capability is covered by your AI governance policy. ======================================================================= CRITICAL: 1 HIGH: 0 MEDIUM: 1 LOW: 0 | Total: 2 Review any CRITICAL or HIGH findings with your AI governance team. ======================================================================= ``` ### JSON 导出（`chara_graph_export.json`） ``` { "metadata": { "generated_at": "...", "scan_mode": "deep", "total_findings": 3 }, "nodes": [ { "id": "endpoint_127.0.0.1_1235", "type": "MCPEndpoint", "edges": ["UnauthenticatedRPC", "ExposesShellExecution"], "verified": true, "metadata": { "host": "127.0.0.1", "port": 1235, "tool_names": ["execute_bash", "read_file"], "shell_tool": "execute_bash", "verified_meaning": "rce_confirmed", "ide": "cursor" } } ], "edges": [ { "from": "endpoint_127.0.0.1_1235", "label": "ExposesShellExecution" } ], "ars_findings": [ { "node_id": "...", "score": "CRITICAL", "reasons": [...] } ], "explanations": [ { "finding_id": "endpoint_127.0.0.1_1235", "runtime_id": "Cursor Desktop", "narrative": "Cursor Desktop has a server on port 1235...", "confidence_label": "EXECUTION VERIFIED", "evidence_items": ["tools/list returned: [execute_bash, ...]", "Echo probe confirmed..."], "relationship_chain": ["Cursor Desktop", "filesystem-mcp", "execute_bash", "No Authentication"], "next_action_admin": "Immediate review required...", "next_action_analyst": "Verified RCE surface...", "ars_score": "CRITICAL" } ] } ``` `explanations` 数组是附加的——所有现有的键（`nodes`、`edges`、`ars_findings`）均保持不变。 ## 能力边 | 边 | 含义 | |---|---| | `UnauthenticatedRPC` | Server 响应了未经身份验证的 `tools/list` | | `ExposesShellExecution` | 工具名称或描述匹配 shell 关键字（如 `execute_bash`、`run_cmd` 等） | | `FileAccess` | 工具暴露了文件读/写操作 | | `NetworkEgress` | 工具暴露了 HTTP/fetch/download 操作 | | `VerifiedStdioMCP` | 通过 stdio 传输完成了完整的 MCP 握手 | | `PlaintextCredential` | 静态配置（`env` 块或参数）中匹配到凭证模式 | | `AgenticTier0` | 进程以 root/SYSTEM 身份运行 | | `ActiveStdioBind` | 进程持有一个打开的 loopback socket 或命名管道 | | `InheritsContext` | 进程在开发者（非提权）上下文下运行 | ## `verified_meaning` 字段 每个 probe 和 ghost 发现在其 metadata 中都包含一个 `verified_meaning` 键： | 值 | 含义 | |---|---| | `rce_confirmed` | Echo 探测返回了确切的 `CHARA-VALIDATION` 字符串 | | `handshake_confirmed` | Ghost 探测完成了完整的 MCP stdio 握手 | | `declared_only` | Shell 工具在清单中已声明，但 echo 探测失败 | | `not_applicable` | 发现不包含 shell 执行能力 | ## 测试平台 一个自包含的测试平台可在无外部依赖的情况下验证所有模块： ``` python3 testbed/run_testbed.py ``` 包含 22 个场景，涵盖 hunter、recon、probe、ghost、导出以及端到端的完整 pipeline。S06 在 Windows 上自动跳过（chmod 是空操作）。S10 在没有 root 权限时自动跳过。 ## 模块自检 每个模块都有一个独立的自检： ``` python3 src/models.py python3 src/explain.py python3 src/hunter.py python3 src/recon.py python3 src/probe.py python3 src/ghost.py python3 src/inventory.py python3 src/export.py ``` ## CI GitHub Actions 会在每次推送时运行完整的自检 + 测试平台矩阵： | 平台 | Python | |---|---| | macOS (latest) | 3.11, 3.12 | | Ubuntu (latest) | 3.11, 3.12 | | Windows (latest) | 3.11, 3.12 | ## 刻意未实现的功能 - **敏感文件交叉比对** — CHARA 会检测 `FileAccess` 能力，但不会枚举磁盘上的哪些具体文件（例如 `~/.aws/credentials`、`~/.ssh/id_rsa`）处于该 server 的可触及范围内。已暂缓，待确认范围后再实现（参见 `Docs/FUTURE_IMPLEMENTATION.md` S23）。 - **超出 loopback 范围的网络扫描** — CHARA 仅探测 `127.0.0.1`。不进行 LAN 或远程扫描。 - **CVE 查找** — 扫描期间无任何外部 API 调用。 - **超出 echo 的 payload** — 安全探测契约是固定的。不会向核心引擎添加任何额外的 payload。 ## 安全声明 CHARA 是一款**本地、经授权使用的安全工具**。请仅在你拥有或获得明确书面扫描许可的系统上运行它。`--ghost-probe` 会根据你的 IDE 配置生成真实的 subprocess——请仅在批准的测试范围内、经授权的系统上使用。

标签：AI安全, Chat Copilot, Docker容器, LNA, MCP, StruQ, Web报告查看器, 占用监测, 威胁建模, 插件系统, 攻击面发现, 数据泄露, 资产管理, 逆向工具