ThreatLocker

ThreatLocker MCP Server

一个模型上下文协议（MCP）服务，可让 AI 助手访问 ThreatLocker Portal API。通过自然语言交互管理计算机、审批请求、审计日志和组织。

功能

• 无状态架构：无需会话状态，每次请求都会建立新连接
• 决策树导航：使用 threatlocker_navigate 浏览各个域
• 网关模式：通过 HTTP 标头支持多租户
• 引导支持：针对缺失参数提供交互式提示
• 全面的错误处理：提供详细的错误消息和日志
• Docker 支持：可用于生产环境的容器化方案

工具

导航

• threatlocker_navigate - 导航至某个域，查看可用工具
• threatlocker_status - 检查 API 连接状态和可用域

计算机

• threatlocker_computers_list - 使用筛选条件列出计算机（搜索、组、分页）
• threatlocker_computers_get - 获取详细的计算机信息
• threatlocker_computers_get_checkins - 获取计算机签到历史记录

计算机组

• threatlocker_computer_groups_list - 使用筛选条件列出计算机组
• threatlocker_computer_groups_dropdown - 获取用于下拉选项的计算机组

审批请求

• threatlocker_approvals_list - 使用状态筛选条件列出审批请求
• threatlocker_approvals_get - 获取详细的审批请求信息
• threatlocker_approvals_pending_count - 获取待处理审批数量
• threatlocker_approvals_get_permit_application - 获取许可申请详情

审计日志

• threatlocker_audit_search - 使用筛选条件搜索审计日志条目
• threatlocker_audit_get - 根据搜索行中的 eActionLogId 获取一条审计日志条目（已弃用的别名：actionLogId）
• threatlocker_audit_file_history - 获取文件的审计历史记录。需要提供 fullPath，以及 hostname 或 computerId

组织

• threatlocker_organizations_list_children - 列出子组织
• threatlocker_organizations_get_auth_key - 获取组织身份验证密钥
• threatlocker_organizations_for_move_computers - 获取用于移动计算机的组织

配置

环境变量

Stdio 模式（直接 API 访问）

THREATLOCKER_API_KEY=your_api_key_here
THREATLOCKER_ORGANIZATION_ID=your_org_id_here
MCP_TRANSPORT=stdio

网关模式（多租户）

AUTH_MODE=gateway
MCP_TRANSPORT=http
MCP_HTTP_PORT=8080
# Required. The HTTP server exits non-zero if this is empty.
CONDUIT_S2S_SECRET=gateway-provisioned-secret
# Optional. Unset binds 127.0.0.1. The container image sets 0.0.0.0.
# MCP_HTTP_HOST=127.0.0.1

HTTP 传输需要设置 CONDUIT_S2S_SECRET。如果未设置，进程会记录错误并以非零状态码退出。仅用于本地开发时，可设置 MCP_ALLOW_INSECURE_DEV=1，让服务仍然启动并记录醒目警告；生产环境中请勿设置此标志。密钥绝不会写入日志。

如果未设置 MCP_HTTP_HOST，服务会绑定到 127.0.0.1。Dockerfile 会设置 MCP_HTTP_HOST=0.0.0.0，使进程在容器内监听；请在 localhost 上发布该端口。

网关模式标头

以网关模式运行时，每个请求都必须包含以下标头：

• X-Gateway-S2S：来自网关的服务间验证信息（t=<unix>,v1=<hmac>）。设置了 CONDUIT_S2S_SECRET 时，不包含有效标头的请求会被拒绝，并返回 401。
• X-Threatlocker-Api-Key：你的 ThreatLocker API 密钥（必需）。不包含此密钥的请求会被拒绝，并返回 401，且不会回退到 THREATLOCKER_API_KEY。
• X-Threatlocker-Organization-Id：你的组织 ID（可选；API 默认使用该密钥对应的主组织）

/health 和 /healthz 无需身份验证，也不会读取凭据。Stdio 传输不会使用 CONDUIT_S2S_SECRET。

日志记录

LOG_LEVEL=debug|info|warn|error  # Default: info

本地开发

1. 克隆代码库：

git clone https://github.com/WYRE-AI/threatlocker-mcp.git
cd threatlocker-mcp

2. 安装依赖项：

npm install

3. 设置环境变量：

cp .env.example .env
# Edit .env with your ThreatLocker credentials

4. 构建并运行：

npm run build
npm start

# Or for development with hot reload:
npm run dev

5. 测试服务：

# Stdio mode
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start

# HTTP mode. CONDUIT_S2S_SECRET is required unless you set
# MCP_ALLOW_INSECURE_DEV=1 (local development only; logs a loud warning).
# The server binds 127.0.0.1 unless MCP_HTTP_HOST is set.
MCP_TRANSPORT=http AUTH_MODE=gateway CONDUIT_S2S_SECRET=dev-secret npm run start:http
curl http://127.0.0.1:8080/health

Docker

使用 Docker Compose

# Required. Compose will not start if this is unset or empty.
export CONDUIT_S2S_SECRET=gateway-provisioned-secret

# Pull and run latest image. The published port is 127.0.0.1:8080.
docker compose up -d

# Or build locally
docker compose -f docker-compose.dev.yml up --build

直接使用 Docker

# Gateway mode (recommended). The container listens on 0.0.0.0 inside
# the network namespace; publish it on localhost only. The process
# exits if CONDUIT_S2S_SECRET is empty.
docker run -d \
  --name threatlocker-mcp \
  -p 127.0.0.1:8080:8080 \
  -e AUTH_MODE=gateway \
  -e CONDUIT_S2S_SECRET=gateway-provisioned-secret \
  ghcr.io/wyre-ai/threatlocker-mcp:latest

# Stdio mode
docker run -d \
  --name threatlocker-mcp \
  -e THREATLOCKER_API_KEY=your_key \
  -e THREATLOCKER_ORGANIZATION_ID=your_org_id \
  -e MCP_TRANSPORT=stdio \
  ghcr.io/wyre-ai/threatlocker-mcp:latest

架构

目录结构

src/
├── domains/           # Domain-specific handlers
│   ├── computers.ts
│   ├── computer_groups.ts
│   ├── approval_requests.ts
│   ├── audit_log.ts
│   ├── organizations.ts
│   ├── navigation.ts
│   └── index.ts
├── utils/             # Utilities
│   ├── client.ts      # ThreatLocker API client
│   ├── logger.ts      # Structured logging
│   ├── types.ts       # TypeScript types
│   ├── server-ref.ts  # Server reference for elicitation
│   └── elicitation.ts # Interactive prompts
├── server.ts          # MCP server creation
├── index.ts           # Stdio transport entry
└── http.ts            # HTTP transport entry

设计模式

• 领域处理器：每个 API 区域都有自己的处理器，包含 getTools() 和 handleCall()
• 延迟加载：按需导入领域处理器
• 新建连接：每个 HTTP 请求都会创建新的服务端实例，以实现无状态操作
• 凭据失效处理：凭据更改时重置客户端
• 交互式补全框架：通过交互式提示词补充缺失参数

许可证

Apache-2.0——详情请参阅 LICENSE。