Truss Threat Intelligence

truss-agent-mcp

通过 Model Context Protocol 和终端助手使用 Truss 威胁情报——一个二进制文件：truss-mcp。

Smithery 上的 Truss MCP

两种使用方式

使用方式	用途	身份验证
远程（推荐）	Cursor、Claude Desktop、MCP 注册表	OAuth → https://api.truss-security.com/mcp
本地 stdio（旧版）	气隙隔离 / 自带密钥 / FilterQL REPL 工具	TRUSS_API_KEY → REST

托管 MCP（OAuth、Growth+ 门槛、五个工具）由 Truss API 提供。本软件包提供配置、validate-remote / doctor --remote、CLI 搜索，以及可选的本地 stdio。Community 账户无法同意使用托管 MCP。

尚未发布到 npm。 请从此代码库安装（npm install -g .）。发布后：npm install -g @truss-security/truss-agent-mcp。

快速开始

cd truss-agent-mcp
npm install && npm run build
npm install -g .
truss-mcp doctor --remote --strict-oauth   # OAuth path hosts use
truss-mcp init                            # for CLI search / legacy stdio
truss-mcp search

Node.js 18+。二进制文件名 truss-mcp 可避免与 @truss-security/truss-sdk 的 truss 命令冲突。

可运行的命令

命令	功能
truss-mcp search	使用实时 MCP 工具的交互式 REPL（本地 stdio 或远程 OAuth 令牌）
truss-mcp mcp	本地 stdio MCP 服务（旧版 / 气隙隔离）
truss-mcp init	交互式 .env 设置
truss-mcp doctor	验证密钥和 API 访问；--remote 运行托管 OAuth 诊断
truss-mcp validate-remote <url>	OAuth + MCP 诊断（发现、DCR、PKCE、工具）
truss-mcp help	使用情况摘要

引导式搜索工作流

一个始终连接 MCP 工具的 REPL。助手会判断你的意图，并在查询 Truss API 前征求确认：

1. 知识 — Truss 平台、网络安全背景、威胁背景
2. 构建筛选条件 — 起草 FilterQL、验证并确认
3. 查询 — run 执行已确认的筛选条件（默认 7 天）
4. 格式化 — 使用 stix 导出 STIX；在对话线程中提供 JSON 摘要
5. 检测规则 — 根据搜索结果生成 detect splunk、detect falcon、detect cortex

助手会明确提供后续步骤：构建筛选条件、完善筛选条件、查询 Truss API、导出 JSON/STIX，或生成 SIEM/EDR 威胁狩猎查询。

• 更长的时间窗口（run 30、days 30）可能会消耗更多 API 配额
• 仅涉及上下文的后续操作（IOC 去重、重新格式化）会使用对话线程历史记录，不会重新查询

完整 REPL 参考：guides/truss-cli.md

终端显示（REPL）

truss-mcp search 使用颜色编码和 ASCII 边框输出：

• 你 — 你的消息
• MCP — 实时工具调用轨迹（远程模式下为 → search_threats，stdio 模式下为 → search_products）
• 结果 — 助手摘要前的结构化产品表格
• Truss — 助手回复（青色）、引导提示（黄色）、FilterQL 代码块（洋红色）

控制项：color / color on / color off / color auto · 环境变量 TRUSS_MCP_COLOR · 标准变量 NO_COLOR=1

MCP 主机（Cursor / Claude）——远程 OAuth（推荐）

主机配置中无需 API 密钥。需要 Growth+ Truss 账户；通过浏览器 OAuth 授权。

{
  "mcpServers": {
    "truss-mcp": {
      "url": "https://api.truss-security.com/mcp"
    }
  }
}

示例：config/cursor.mcp.json · config/claude_desktop_config.json · guides/client-setup-cursor.md。

旧版 stdio（气隙隔离）

{
  "mcpServers": {
    "truss-mcp": {
      "command": "truss-mcp",
      "args": ["mcp"],
      "env": { "TRUSS_API_KEY": "YOUR_KEY" }
    }
  }
}

请参阅 config/cursor.mcp.stdio.json 和 guides/getting-started.md。

远程 MCP OAuth 验证（注册表门禁）

在发布到注册表或正式发布前，将其用作 OAuth + MCP 检查工具。完成 OAuth 后，search_threats 必须至少返回一个 Truss 产品（包含 id + title）。除非传入 --save-token，否则访问令牌仅在该进程运行期间保存在内存中。

truss-mcp doctor --remote --strict-oauth
# or:
truss-mcp validate-remote https://api.truss-security.com/mcp --strict-oauth

令牌交换完成后，它会打印一份 OAuth 兼容性检查清单（资源 URI、重定向、PKCE S256、发行者匹配、受众与 MCP 资源的匹配情况、truss_role），然后使用真实 Truss 数据验证 MCP 访问。

选项：

truss-mcp validate-remote https://api.truss-security.com/mcp --verbose
truss-mcp validate-remote https://api.truss-security.com/mcp --strict-oauth
truss-mcp validate-remote https://api.truss-security.com/mcp --save-token /tmp/truss-mcp-token
truss-mcp validate-remote https://api.truss-security.com/mcp --token-file /tmp/truss-mcp-token
truss-mcp validate-remote https://api.truss-security.com/mcp --port 9877
truss-mcp validate-remote https://api.truss-security.com/mcp --no-open

• --verbose — 显示 HTTP 状态、关键标头和截断后的响应正文（令牌会脱敏）
• --strict-oauth — 如果 OAuth 检查清单中有 WARN/FAIL，则以状态码 2 退出（即使 Truss MCP 调用成功）
• --save-token PATH — 将访问令牌写入文件，供本地重放（模式为 0600；调试后请删除）
• --token-file PATH — 跳过浏览器 OAuth；使用已保存的令牌重新检查 MCP 访问权限和 Truss 数据

可选的自动化 OAuth 数据测试（已保存令牌 + TRUSS_RUN_MCP_OAUTH=1）记录在 guides/publishing.md 中。

官方列表：server.json（com.truss-security/truss-mcp）· 跟踪：guides/registry-submission.md · 内部元数据：config/mcp-registry.json · 架构：docs/05-hosted-mcp-oauth-architecture.md

配置

环境变量加载顺序（Shell 变量优先）：~/.config/truss/env → ~/.truss/.env → ./.env

变量	适用场景	说明
TRUSS_API_KEY	本地 mcp / stdio search	从 Truss 控制面板获取（仅适用于旧版隔离环境）
TRUSS_MCP_URL	远程 search / doctor	默认值为 https://api.truss-security.com/mcp
TRUSS_MCP_OAUTH_TOKEN_FILE	远程 search	来自 validate-remote --save-token 的 Bearer 令牌
LLM_PROVIDER	search	anthropic 或 openai — 通过 init 设置
LLM_MODEL	search	通过 init 设置
ANTHROPIC_API_KEY / OPENAI_API_KEY	search	按提供方设置

完整列表：env.example

文档

指南 — 安装、REPL、MCP 客户端、FilterQL 示例

• 入门指南
• 终端 REPL
• FilterQL 指南
• Cursor 设置 · Claude Desktop

参考文档 — API 约定、工具、架构（docs/README.md — 文档 01–06）

开发

npm install && npm run build
npm test
npm run truss:search    # from source without global install

**贡献者 / AI Agent：**请参阅 AGENTS.md，了解仓库操作和约定。

发布：guides/publishing.md · 变更：CHANGELOG.md

相关项目

• @truss-security/truss-sdk — API 客户端
• truss-agent — 定时 Webhook 投递
• Truss 文档 — 公共 API / SDK 文档

MIT