aplaceforallmystuff/mcp-cti-glossary

# mcp-cti-glossary [](https://github.com/aplaceforallmystuff/mcp-cti-glossary/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) [](#requirements) 一个 MCP server，将八个权威的网络威胁情报和安全词汇表聚合到一个经过 FTS5 索引的 SQLite 存储中，并通过 7 个工具暴露。使用它可以消除多义词的歧义（NICKEL, CHROMIUM），解决跨供应商的威胁行为者命名（Salt Typhoon ↔ GhostEmperor ↔ FamousSparrow），通过 ID 查找 ATT&CK 技术，或者使用全文搜索扫描约 3.4 万个术语。 **v0.1.0 语料库：来自 8 个数据源的约 34,000 个术语** — MITRE ATT&CK、NIST CSRC 词汇表、ENISA 词汇表、ENISA 威胁分类、MISP Galaxy（threat-actor + Microsoft activity groups）、OFAC SDN、Jargon File / New Hacker's Dictionary，以及一份手工整理的跨供应商别名 YAML。 ## 为什么会有这个项目 日常的 CTI 工作充满了重叠的词汇 — Salt Typhoon、GhostEmperor、FamousSparrow 和 UNC2286 是由四个不同供应商命名的同一个威胁集群。NICKEL 是一个 Microsoft 代号、一个 OFAC 实体、一种化学元素，也是一个 Mandiant 追踪器。每一个新术语都会消耗上下文和阅读时间。这个 server 将这种成本压缩到一次工具调用中，并带有来源元数据，以便答案是可审计的。 ## 使用方法 一旦 server 接入 Claude Code（参见下方的[配置 Claude Code](#configure-claude-code)），你不需要按名称调用工具 — 你只需与 Claude 对话，它会自动选择合适的工具。以下是与每个工具触发的现实提示词配对： ### 消除多义词的歧义 触发 `glossary_disambiguate`。返回排名后的候选结果 — 首先是 vendor-aliases 中关于 NICKEL 的消歧条目（解释了 Ke3chang/APT15 的含义以及 NICKEL ACADEMY 和 NICKEL GLADSTONE 这两个 Microsoft 追踪器），然后是任何名称中包含 NICKEL 的 OFAC SDN 条目作为模糊匹配。你可以根据文章上下文选择正确的含义。 ### 跨供应商行为者解析 触发 `glossary_lookup`。返回来自 `vendor-aliases` 和 `misp-galaxy` 的 **Salt Typhoon** 条目（其中 Microsoft 代号也指向它），并带有完整的别名列表 — GhostEmperor、FamousSparrow、UNC2286、Earth Estries、RedMike。确认它们是不同供应商名称下的同一个行为者。 ### 带有完整别名映射的 APT 查询 触发 `glossary_actor`。返回 MITRE ATT&CK G0007 条目（Fancy Bear、Sofacy、Sednit、STRONTIUM…）以及 MISP Galaxy 的 Microsoft 代号条目（Strontium 以及 Forest Blizzard / APT28 同义词）— 在一次响应中获得完整的跨供应商覆盖。 ### 通过 ID 查找 ATT&CK 技术 触发 `glossary_technique`。返回 Spearphishing Attachment 及其杀伤链阶段、平台和 ATT&CK URL。比切换窗口去看 attack.mitre.org 更快。 ### 跨语料库的模糊搜索 触发 `glossary_search`。FTS5 BM25 排名 — 首先命中的将是 Salt Typhoon、Volt Typhoon 以及涉及电信基础设施的 ATT&CK 技术（T1190、T1078）。 ### OFAC 制裁检查 触发 `glossary_lookup`。返回 vendor-aliases 条目以及任何具有其计划代码（CYBER2、NARCO 等）的匹配 SDN 条目。 ### 多行为者审计 Claude 顺序调用 `glossary_actor` 和 `glossary_lookup`。返回一个快速审计表 — 适用于在发送威胁报告或在任何交付物中引用集群名称之前使用。 ### 上游更新后刷新 触发 `glossary_refresh({ source: "ofac-sdn" })`。大约需要 25 秒。无需重建或重启 server。 ### 健康检查 触发 `glossary_stats`。返回总术语数、每个数据源的数量和上次刷新时间戳，以及针对任何超过 30 天的数据源的过期标志。 复合价值：每次在 CTI 资料中遇到新术语时，你都可以直接询问 Claude。结构化的响应带有来源归属 — 当你在报告、简报或任何交付物中引用它时，引用链会保持完整。 ## 工具 所有 7 个工具都返回带有来源归属的结构化 JSON。以下参考适用于直接调用工具的情况；有关自然语言用法，请参见上方的[使用方法](#usage)。 ### `glossary_disambiguate(term, context?)` 主要工具。返回歧义词的排名候选结果（先精确匹配，然后是 FTS5 模糊匹配）。 ``` // Call: glossary_disambiguate({ term: "NICKEL" }) { "term": "NICKEL", "exactMatchCount": 1, "totalCandidateCount": 4, "candidates": [ { "rank": 1, "term": "NICKEL", "source": "vendor-aliases", "category": "general", "externalId": "nickel-disambiguation", "aliases": ["NICKEL ACADEMY", "NICKEL GLADSTONE"], "matchKind": "exact", "definition": "NICKEL is overloaded across security vocabularies...", "attribution": "Hand-curated cross-vendor naming, mcp-cti-glossary (MIT)." }, // ... OFAC and other fuzzy matches follow ] } ``` ### `glossary_lookup(term, source?)` 按术语或别名进行不区分大小写的精确匹配，可跨所有数据源或限定于某一个数据源。通过别名命中会返回每个包含该别名的数据源中的规范条目 — 因此 `glossary_lookup({ term: "GhostEmperor" })` 会返回来自 `vendor-aliases` 和 `misp-galaxy` 两个数据源的 Salt Typhoon。 ### `glossary_search(query, source?, category?, limit?)` 跨术语名称和定义的 FTS5 模糊搜索，按 BM25 排名。可按数据源键（`mitre-attack`、`nist`、`enisa-glossary`、…）或类别（`cti_actor`、`cti_technique`、`cultural`、`regulatory`、`general`、…）进行过滤。 ### `glossary_actor(name_or_alias)` 专门用于威胁行为者。将任何别名解析为跟踪它的每个数据源中的规范条目。适用于跨供应商协调：查询 `APT28`，你将在一次响应中获得 MITRE 的入侵集条目以及 MISP Galaxy 的 Microsoft `Strontium` 代号条目。 ### `glossary_technique(technique_id)` 通过规范 ID 查找 ATT&CK 技术 — 支持顶级技术（`T1566`）和子技术（`T1566.001`）。经过 Schema 验证，格式错误的 ID 会在数据库查询之前被拒绝。 ### `glossary_refresh(source?)` 手动重新摄取一个或所有数据源。适用于 OFAC 发布新的 SDN 列表、MITRE 发布新的 ATT&CK 版本，或 NIST 更新每日词汇表导出时。数据源键：`mitre-attack`、`ofac-sdn`、`vendor-aliases`、`nist`、`misp-galaxy`、`enisa-glossary`、`enisa-taxonomy`、`jargon-file`。 ### `glossary_stats(staleThresholdDays?)` 语料库健康状况：每个数据源的计数、上次刷新时间戳、过期数据源标志。 ## 数据源 | 数据源 | 许可证 | 类型 | 大约术语数 | 刷新机制 | |---|---|---|---|---| | [MITRE ATT&CK Enterprise](https://attack.mitre.org/) | Apache-2.0 | 静态 STIX 2.1 包 | ~1,700 | 通过 `glossary_refresh` 按需刷新 | | [NIST CSRC 词汇表](https://csrc.nist.gov/glossary) | 公共领域 (US) | 每日 JSON 导出 | ~9,800 | 上游每日更新；此处按需刷新 | | [OFAC SDN 列表](https://ofac.treasury.gov/) | 公共领域 (US) | XML feed (订阅源) | ~19,000 | 财政部每周更新 | | [Jargon File](http://www.catb.org/jargon/) | OPL-1.0 / 公共领域 (PG ed.) | Project Gutenberg 纯文本 | ~2,300 | 按需刷新 | | [MISP Galaxy](https://github.com/MISP/misp-galaxy) | CC0-1.0 / BSD-2-Clause | threat-actor + microsoft-activity-group JSON | ~1,150 | 按需刷新 | | [ENISA 词汇表](https://www.enisa.europa.eu/media/media-press-kits/enisa-glossary) | CC-BY-4.0 | HTML 抓取 (快照测试) | ~120 | 按需刷新 | | [ENISA 威胁分类](https://github.com/MISP/misp-taxonomies/tree/main/enisa) | CC0-1.0 / BSD-2-Clause | MISP machinetag JSON | ~170 | 按需刷新 | | Vendor aliases (交叉对照表) | MIT (本仓库) | 手工整理的 YAML | ~10 | 编辑 `data/vendor_aliases.yaml` 并刷新 | 每个工具响应都带有许可归属元数据。有关每个数据源的完整归属要求，请参见 [LICENSES.md](./LICENSES.md)。 ## 环境要求 - Node ≥ 18 - macOS、Linux 或 Windows（缓存路径通过 `env-paths` 正确解析） - 约 30 MB 磁盘空间用于存放填充后的 SQLite 缓存（经过 VACUUM 后） ## 安装 此软件包尚未发布到 npm。请从 GitHub 安装： ``` git clone https://github.com/aplaceforallmystuff/mcp-cti-glossary.git cd mcp-cti-glossary npm install npm run build ``` 首次启动时，server 会从最新的 GitHub Release 下载一个约 8 MB 的预构建 gzip 压缩数据库（解压后磁盘占用约 28 MB）。如果由于任何原因无法获取该构件，server 将回退到实时运行每个适配器（约 30 秒）。你也可以手动预填充： ``` npm run ingest # ~30s — populates ~/Library/Application Support/mcp-cti-glossary/glossary.db on macOS ``` （计划在 v0.1.0 发布到 npm；在此之前，请通过克隆进行安装。） ## 配置 Claude Code 添加到你的 `~/.claude.json`（或你的 Claude Code MCP 配置所在的位置）： ``` { "mcpServers": { "cti-glossary": { "command": "node", "args": ["/absolute/path/to/mcp-cti-glossary/dist/index.js"] } } } ``` 重启 Claude Code。这七个 `glossary_*` 工具将在任何会话中可用。 ## 配置 Claude Desktop 形式相同，在 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 中： ``` { "mcpServers": { "cti-glossary": { "command": "node", "args": ["/absolute/path/to/mcp-cti-glossary/dist/index.js"] } } } ``` ## 架构 - TypeScript ES modules，`@modelcontextprotocol/sdk` v1.26+ - 通过 `better-sqlite3` 使用带有 FTS5 虚拟表（BM25 排名，`unicode61 remove_diacritics 2` 分词器）的 SQLite - 使用 `zod` + `zod-to-json-schema` 进行工具输入验证 - 缓存路径通过 `env-paths` 解析（macOS 上为 `~/Library/Application Support/mcp-cti-glossary/glossary.db`） - `src/tools/` 中每个工具一个文件，`src/sources/` 中每个数据源适配器一个文件 - `src/ingest/` 包含共享编排器、预构建数据库获取器和首次运行解析器（缓存 → 发布构件 → 实时摄取） `src/sources/_adapter.ts` 中的 `SourceAdapter` 接口是添加新数据源的契约。每个适配器实现 `fetch(): Promise` 和 `normalize(doc: RawDoc): Term[]`。添加新数据源大致为：编写适配器，添加 YAML/JSON 固定数据，编写仅规范化的测试，在 `src/ingest/orchestrator.ts` 和 `src/tools/refresh.ts` 中注册。请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 开发 ``` npm install npm run build # tsc → dist/ npm run watch # tsc --watch npm test # vitest run (120 tests across 21 files) npm run typecheck # tsc --noEmit npm run ingest # populate local SQLite cache (live ingest, ~30s) npm run build:db # CI artifact builder — produces build/glossary.db.gz + sha256 ``` 对填充后的数据库进行工具层的端到端冒烟测试： ``` npx tsx scripts/smoke-tools.ts ``` ## 发布 在 `main` 分支上打 `v*.*.*` 标签会触发 `.github/workflows/release-db.yml`，该工作流会： 1. 运行类型检查和完整的测试套件。 2. 针对实时上游数据源执行每个适配器。 3. 对生成的数据库执行 VACUUM，进行 gzip 压缩，并计算 `sha256`。 4. 将 `glossary.db.gz` + `glossary.db.gz.sha256` 上传到对应的 GitHub Release。 MCP server 的首次运行解析器从 `releases/latest/download/glossary.db.gz` 下载，因此除非 GitHub 本身不可访问，否则用户无需等待实时摄取。 ## 故障排除 **Server 启动了，但 Claude Code 报告 "no tools available."** 1. 确认 MCP 配置中的路径是绝对路径，并且指向 `dist/index.js`，而不是 `src/`。 2. 在终端中运行 `node /absolute/path/to/dist/index.js < /dev/null` — 在一两秒内，你应该会在标准错误输出中看到 `mcp-cti-glossary v0.1.0 running on stdio (db: cache|prebuilt|live-ingest)`如果没有，说明构建已过时：请运行 `npm run build`。 3. 检查 Claude Code 的 MCP 日志以查找握手错误。 **对于你确定存在的术语，工具返回 "no results"。** 如果预构建数据库获取失败且跳过了实时摄取，数据库可能为空。通过 `glossary_stats({})` 检查数据源计数。如果全部为零，请运行一次 `npm run ingest` 或在任何会话中调用 `glossary_refresh({})`。 **`npm run ingest` 因 "Failed to fetch MITRE ATT&CK bundle" 失败。** `github.com/mitre/cti` 上的静态 STIX 包大约有 50 MB。请检查你的网络并重试。 **OFAC SDN 摄取卡住。** 财政部的 XML feed 大约为 27 MB，并会解析为约 1.9 万条记录。预计需要 20-30 秒。如果停滞超过一分钟，feed 端点可能已关闭 — 请尝试使用 `curl -I https://www.treasury.gov/ofac/downloads/sdn.xml` 验证可达性。 **FTS5 搜索对部分术语不返回结果。** FTS5 查询是通过引用每个由空格分隔的 token 构建的。单字符 token 不会匹配。尝试每个 token 至少包含三个字符，或者使用 `glossary_lookup` 通过别名进行精确匹配。 ## 路线图 ### v1.1+ - **发布到 npm**，名称为 `mcp-cti-glossary-server` - **SANS / HackTheBox / Spyscape 词汇表** - **Microsoft Threat Actor Naming 分类法抓取器**（带有用于应对 DOM 变动的快照测试） - **Mandiant + CrowdStrike 供应商命名抓取器** - **实时 TAXII 轮询**，取代 ATT&CK 的静态 STIX 包 - **自动刷新 cron**（在此之前，用户需手动调用 `glossary_refresh`） - **可选的网页搜索回退**，用于处理未知术语（通过环境变量 opt-in） ### 不在范围内（已锁定） - 嵌入式向量搜索 — 精确匹配的 FTS5 满足了操作需求 - 多语言词汇表 — 仅限英文 - Vault 回写 — 纯 MCP server，除了缓存数据库外，对用户的文件系统没有副作用 - 实时抓取供应商页面 — 法律立场不明确；我们只使用已在 MITRE 中的公开别名映射以及可重新分发的 MISP Galaxy 数据 ## 许可证 MIT — 详见 [LICENSE](./LICENSE)。 源数据根据 [LICENSES.md](./LICENSES.md) 中列出的许可证进行聚合。每个工具响应都带有归属元数据，以便下游使用保持清晰（例如，在威胁报告或简报中引用结果时）。 ## 贡献 欢迎提交 Bug、PR 和新的数据源适配器。请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。`src/sources/_adapter.ts` 中的 `SourceAdapter` 接口记录了契约；现有的八个适配器是每种常见格式（STIX JSON、XML feed、gzip 压缩的 JSON 导出、HTML 抓取、MISP machinetag JSON、Project Gutenberg 纯文本版以及手工整理的 YAML）的参考实现。 ## 致谢 - **MITRE Corporation** — 提供了 ATT&CK，这是规范的操作性 CTI 分类法 - **NIST CSRC** — 提供了每日更新的公共领域词汇表导出 - **ENISA (European Union Agency for Cybersecurity)** — 提供了开放的词汇表和威胁分类法 - **MISP Project / CIRCL** — 提供了可重新分发的 galaxy + taxonomy 生态系统，使得跨供应商命名变得易于处理 - **US Department of the Treasury / OFAC** — 提供了作为公共领域 feed 的 SDN 列表 - **Eric S. Raymond** 以及更广泛的 Jargon File 贡献者传承 — 提供了文化俚语语料库 - 跨供应商命名社区（Microsoft Threat Intelligence、Mandiant、CrowdStrike、Recorded Future、ESET、Kaspersky、SentinelOne 等）提供了使威胁行为者消歧成为可能的集群别名

标签：Claude Code, Cloudflare, ENISA, FTS5, GNU通用公共许可证, LLM工具, MCP Server, MISP Galaxy, MITM代理, MITRE ATT&CK, NIST CSRC, Node.js, OFAC SDN, Ruby, SQLite, 全文检索, 别名映射, 威胁情报聚合, 威胁行为者, 安全术语, 实体解析, 幻觉缓解, 情报共享, 智能体安全, 模型上下文协议, 知识库, 网络威胁情报, 网络安全, 自动化攻击, 行话消歧, 跨供应商映射, 隐私保护, 黑客词典