itsoc-mcp

itsoc-icp — 基于本地分析后端的 MCP 服务

mcp-name: io.github.Ankit512/itsoc-icp

itsoc-icp（Python 包 itsoc_mcp）将本项目现有的日志分析能力作为 Model Context Protocol 工具开放，使支持 MCP 的 Agent（Claude Code / Claude Desktop）能够调用这些能力。它是一个 隔离的同级包：不从 anomaly_detector.py 导入任何内容，不修改任何 /api/* 路由，也不会为核心后端添加依赖。

它是什么（以及不是什么）

• 它是客户端，不是大脑。 每个工具都会代理已运行的本地后端 （默认为 http://127.0.0.1:8765）。此服务不会计算任何判定： 严重程度、关联分析和规则判定均由后端中冻结的确定性检测器负责。工具只负责传递，绝不会重新判定。
• 不执行操作，也没有审批权限。 没有任何工具可以批准、拒绝、 执行或撤销操作。propose_block_ip 只能创建状态为 pending 的提案；所有执行和审批权限 均严格归后端控制台所有，并要求人在环路中的逐步验证。analyze_log 会启动日志分析，explain_finding 则通过现有端点请求建议性解释——解释绝不会改变、压制或升级 判定。
• 从设计上保证诚实。 后端的 null、“0 lines parsed”及空闲状态会原样传递——绝不会伪造“一切正常”或空文件。
• 默认脱敏。 所有包含原始日志文本的字段，都会在离开服务前通过 项目现有的出口关卡（console/redact.py）进行掩码处理，除非你选择启用可信本地会话（见下文）。

每个工具响应都包含一个 provenance 区块，说明判定是确定性的、由规则负责的，解释仅供参考，MITRE 标签是派生信息（不是判定），并附上正在运行的检测器的 detector_sha256。

工具

工具	返回内容	诚实性说明
analyze_log(source, compare=False)	对本地路径 或 http(s) URL 运行现有的分析流程；返回 run_id + 摘要（严重程度计数、已解析/未解析行数、无法识别标志、检测器 sha）。	无法识别的格式 → “已解析 0 行”，明确表示并非一切正常。
list_runs()	运行历史中保存的运行记录，以及当前运行。	历史记录为空时会如实返回空结果。
get_findings(run_id='', severity='', rule='', host='', limit=50)	当前运行中经过筛选的发现项：由规则判定的严重程度、rule_id、推导出的 MITRE 标签。	默认会对主机名/标题进行脱敏。非当前的 run_id 会如实报错（此服务绝不会切换当前运行）。
get_evidence(finding_id, run_id='')	某条发现项的真实证据行 + 规则谓词 + 时间线。	默认会对原始行和时间线标签进行脱敏。
explain_finding(finding_id, run_id='')	通过 /api/explain 获取 LLM 的建议性说明。	仅供参考；默认脱敏；无法访问模型时会如实报错。
export_run(format, run_id='')	代理 /api/export（csv|html|xml|json|md）。	空闲状态 → 如实返回 409（“尚无内容可导出”），绝不会返回空文件。内容包含原始日志文本，因此默认会予以保留，不返回（但会返回实际大小 + sha256）；设置受信任本地标志后即可内联接收内容。
threat_intel_lookup(ip, bundle_path=None)	对单个 IPv4 地址执行 离线 STIX→MITRE 查询，复用 threat_intel/（匹配结果 + 严重程度来自 threat_detector.py，MITRE 数据来自缓存的 ATT&CK 数据库）。不会向外部网络发送数据。	未配置 bundle → 如实返回 n/a；未匹配 → 如实返回“无匹配”，并非一切正常。
propose_block_ip(incident_id, runbook_id='rb-block-ip')	在后端控制台创建一条待处理审批记录，以提议阻止边界 IP。	仅创建提议：没有执行权限，也没有审批权限。必须在控制台通过加强身份验证才能批准/执行。

每个工具都将全部四个 MCP 提示显式声明为布尔值（readOnlyHint、 destructiveHint、idempotentHint、openWorldHint），以便宿主在调用前发出警告，同时让 OpenAI 的目录接受此契约。读取工具 （list_runs、get_findings、get_evidence、export_run、threat_intel_lookup） 的 readOnlyHint: true。analyze_log、explain_finding 和 propose_block_ip 会写入数据（仅追加，不具破坏性）。所有面向后端的工具都设为 openWorldHint: true。

安装

核心后端仅使用 stdlib——运行它无需安装任何内容。只有在要运行此服务时，才需要安装 MCP SDK：

pip install -r itsoc_mcp/requirements-mcp.txt   # the `mcp` SDK, and nothing else

运行

1. 启动后端（在仓库根目录中），仅使用 stdlib，无需额外安装：

   python3 console/serve.py           # serves http://127.0.0.1:8765
   

2. 通过 stdio 启动 MCP 服务（在仓库根目录中）：

   python -m itsoc_mcp
   

配置（环境变量）

变量	默认值	用途
ITSOC_BASE_URL	http://127.0.0.1:8765	本地后端的监听地址。
ITSOC_MCP_TRUSTED_LOCAL	(未设置)	设为 1 可返回原始（未脱敏）日志文本和内联导出内容。对于 MCP 客户端可能将数据转发到本机之外的任何会话，请保持未设置——默认会屏蔽 IP、用户名和已知主机。
ITSOC_STIX_BUNDLE	(未设置)	threat_intel_lookup 使用的本地 STIX bundle 路径。未设置 → 工具会如实报告“n/a — 没有可供匹配的数据”。

注册到 MCP 客户端（stdio）

将以下内容粘贴到 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json，或 Claude Code 的 .mcp.json）。将 /ABSOLUTE/PATH/TO/itsoc 替换为仓库根目录：

{
  "mcpServers": {
    "itsoc-icp": {
      "command": "python",
      "args": ["-m", "itsoc_mcp"],
      "cwd": "/ABSOLUTE/PATH/TO/itsoc",
      "env": {
        "ITSOC_BASE_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

若要在受信任的本地计算机上允许获取原始证据/导出内容，请在该 env 块中添加 "ITSOC_MCP_TRUSTED_LOCAL": "1"（以及可选的 "ITSOC_STIX_BUNDLE": "..."）。后端（python3 console/serve.py）必须正在运行。

测试

无需网络、无需 SDK、无需 ATT&CK 缓存——客户端使用了伪实现，离线映射器也使用了桩：

python3 itsoc_mcp/test_mcp.py

测试会检查每个工具的结构，验证 get_evidence/get_findings/explain_finding 默认会脱敏，且只有设置 ITSOC_MCP_TRUSTED_LOCAL=1 时才会返回原始内容；同时还会验证空闲、无法识别和错误状态会返回如实的错误，而不是空载荷。

独立安装（uvx / pipx）

pyproject.toml 会构建一个 itsoc-icp 发行包，其中包含一个 itsoc-icp 控制台 脚本（itsoc_mcp.server:main），并固定使用 mcp>=1.9,<2——MCP 客户端使用稳定的 1.x API；mcp 2.0 更改了服务端 API。此软件包独立完整： 设计上无需检出仓库即可运行。

uvx itsoc-icp        # or: pipx run itsoc-icp   (the backend must still be running)

明确说明两点：

• 独立运行时绝不会削弱出口防护。 脱敏逻辑只有一个事实来源——console/redact.py，只要仓库可导入，就会使用它。在纯净安装中，则会回退到逐字 vendored 镜像（_redact_vendored.py），其屏蔽行为完全一致（默认脱敏；只有设置 ITSOC_MCP_TRUSTED_LOCAL=1 时才返回原始内容）。漂移防护测试会确保两者始终一致， 因此 vendored 副本绝不会在无提示的情况下减少屏蔽内容。redaction.redact_source() 会报告当前使用的是哪一份。如果两者都无法加载，模块会拒绝导入，而不会直接放行文本——它会默认拒绝，绝不默认放行。
• threat_intel_lookup 需要仓库。 其离线 STIX→MITRE 路径会复用仓库中同级的 threat_intel/ 软件包，纯净安装不会附带该软件包。在独立安装中，该工具会默认拒绝， 并返回如实的“离线威胁情报不可用……不是干净判定／不代表一切正常”消息——绝不会捏造匹配结果或假装一切正常。请从仓库运行 （python -m itsoc_mcp）以使用离线威胁情报。其他所有工具都是后端 API 的客户端， 在独立安装和仓库内运行时表现相同。

独立安装表示无需检出仓库即可使用 MCP 软件包——后端（python3 console/serve.py）仍需单独运行，并且必须能通过 ITSOC_BASE_URL 访问。

许可证

MIT——请参阅仓库顶层的 LICENSE。