SauceTaster/assemblyline-mcp

# AssemblyLine MCP 一个用于 [AssemblyLine 4](https://cybercentrecanada.github.io/assemblyline4_docs/) 的 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 服务器 — AssemblyLine 4 是 加拿大网络安全中心的**开源文件分类与恶意软件分析**平台。 它允许兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor、VS Code 等）提交文件、哈希和 URL 进行分析、 检索结果、跨 AssemblyLine 索引进行搜索，以及对警报进行分类。 [](https://pypi.org/project/assemblyline-mcp/) [](https://pypi.org/project/assemblyline-mcp/) [](https://github.com/SauceTaster/assemblyline-mcp/actions/workflows/ci.yml) [](https://github.com/SauceTaster/assemblyline-mcp/actions/workflows/test.yml) [](https://codecov.io/gh/SauceTaster/assemblyline-mcp) [](LICENSE) [](https://github.com/astral-sh/ruff) [](https://github.com/astral-sh/uv) [](https://modelcontextprotocol.io) ## 功能 - **专为 Agent 打造，而非仅仅是 API 对等** — `al_analyze` 提交并等待，然后 返回简洁的**判定摘要**（判定结果、标记的服务、启发式分析、AV 命中、网络 IOC、子项），而不是原始 blob 数据；`al_submission_iocs` 和 `al_find_related` 涵盖 IOC 提取和拓展调查。内置的 **MCP prompts** （`triage_file`、`investigate_hash`、`review_alert`）在**服务器内部直接提供了 AssemblyLine 的分类 工作流和评分语义 —— 无需安装任何 skill**。 - **全面的 AssemblyLine 4 覆盖** — 提交/摄取、检查提交和 单文件结果、跨每个索引的 Lucene 搜索、警报分类以及系统 元数据，构建于官方的 [`assemblyline-client`](https://github.com/CybercentreCanada/assemblyline_client)。 - **默认安全** — 破坏性/管理员操作（删除、工作流运行、 用户/服务/系统管理）**甚至不会被注册**，除非您通过 `AL_ALLOW_ADMIN=true` 主动开启， 并且每个工具都带有 MCP `readOnlyHint` / `destructiveHint` 注解，以便客户端可以在执行高风险操作前进行提示。 - **两种传输模式** — `stdio` 用于本地桌面客户端，而 **streamable HTTP** 用于网络/容器化部署（带有可选的 `admin` 范围身份验证）。 - **内置端到端自检** — `assemblyline-mcp selftest` 启动 进程内 mock AssemblyLine，测试每个工具，并打印通过/失败 报告。无需实时服务器，无需 pytest，任何架构均适用。 - **生产级就绪打包** — 支持 `uvx` 安装，包含类型提示 (`py.typed`)， 多架构 Docker 镜像，以及已发布的 [MCP registry](https://github.com/modelcontextprotocol/registry) 清单。 ## 可用工具 所有工具均带有 `al_` 前缀。只读工具始终可用；写入工具 会改变状态但无破坏性；**管理员**工具需要 `AL_ALLOW_ADMIN=true`。 | 分组 | 工具 | |-------|-------| | **分析 (Agentic)** | `al_analyze` (提交 + 等待 + 判定摘要)、`al_submission_digest`、`al_submission_iocs`、`al_find_related` | | **提交** | `al_submit`、`al_ingest`、`al_ingest_get_messages`、`al_submission`、`al_submission_full`、`al_submission_summary`、`al_submission_tree`、`al_submission_report`、`al_submission_file`、`al_submission_is_completed`、`al_submission_list`、`al_submission_set_verdict` | | **搜索** | `al_search`、`al_search_facet`、`al_search_stats`、`al_search_histogram`、`al_search_grouped`、`al_search_fields` | | **文件 / 结果** | `al_file_info`、`al_file_result`、`al_file_score`、`al_file_children`、`al_file_strings`、`al_file_hex`、`al_file_ascii`、`al_file_ai_summary`、`al_file_download`、`al_result`、`al_error`、`al_hash_search` | | **警报** | `al_alert`、`al_alert_list`、`al_alert_grouped`、`al_alert_statistics`、`al_alert_label`、`al_alert_set_priority`、`al_alert_set_status`、`al_alert_set_verdict`、`al_alert_take_ownership` | | **系统** | `al_whoami`、`al_user_quotas`、`al_help_configuration`、`al_help_constants`、`al_help_classification`、`al_heuristics` | | **管理员** *(受控)* | `al_submission_delete`、`al_file_delete_from_filestore`、`al_alert_remove_label`、`al_workflow_run`、`al_workflow_delete`、`al_signature_change_status`、`al_signature_delete`、`al_badlist_delete`、`al_safelist_delete`、`al_service_delete`、`al_system_set_message`、`al_system_clear_message` | ### 引导式工作流（MCP prompts — 无需 skill） 服务器注册了 MCP **prompts**，这些 prompts 编码了 AssemblyLine 的分类工作流 和评分语义，因此 Agent 开箱即用即可正确解读结果。 这些在原生的 MCP 客户端（Claude Desktop/Code、Cursor 等）中可以直接使用： - **`triage_file`** — 对文件/哈希进行分类并报告判定结果。 - **`investigate_hash`** — 获取某个哈希已知的结果、IOC 以及相关活动。 - **`review_alert`** — 将警报评估为真阳性/假阳性。 在 [`skills/assemblyline-triage/`](skills/assemblyline-triage/) 下还提供了一个更丰富的、特定于 Claude 的 **Agent Skill** — 但这是可选的； 无需安装任何内容即可完全使用该服务器。 ## 安装 您需要一个正在运行的 [AssemblyLine 4](https://cybercentrecanada.github.io/assemblyline4_docs/installation/overview/) 实例以及一个 API key（或用户名/密码）。 ``` # 免安装运行（推荐） uvx assemblyline-mcp # 或使用 pipx / pip pipx install assemblyline-mcp pip install assemblyline-mcp ``` ### Docker ``` docker run --rm -i \ -e AL_URL=https://al.example.org \ -e AL_APIKEY_USER=analyst \ -e AL_APIKEY=your-keyname:secret \ ghcr.io/SauceTaster/assemblyline-mcp:latest ``` ## 配置 通过带有 `AL_` 前缀的环境变量（或 `.env` 文件）进行配置。 | 变量 | 必需 | 默认值 | 描述 | |----------|:--------:|---------|-------------| | `AL_URL` | ✅ | – | AssemblyLine 实例的基础 URL（例如 `https://al.example.org`）。 | | `AL_APIKEY_USER` | ✅¹ | – | 与 `AL_APIKEY` 配对的用户名。 | | `AL_APIKEY` | ✅¹ | – | API key 密钥（`keyname:secret`）。 | | `AL_USERNAME` | ✅¹ | – | 用户名（用于密码身份验证）。 | | `AL_PASSWORD` | ✅¹ | – | 密码（用于密码身份验证）。 | | `AL_VERIFY_SSL` | | `true` | 验证 AssemblyLine TLS 证书。 | | `AL_TIMEOUT` | | `60` | 单次请求超时时间（秒）。 | | `AL_RETRIES` | | `3` | 有限的重试次数（永不无限重试）。 | | `AL_ALLOW_ADMIN` | | `false` | 注册管理员/破坏性工具。 | | `AL_MAX_DOWNLOAD_BYTES` | | `10485760` | `al_file_download` 输出的上限。 | | `AL_TRANSPORT` | | `stdio` | `stdio` 或 `http`。 | | `AL_HOST` / `AL_PORT` / `AL_PATH` | | `127.0.0.1` / `8000` / `/mcp/` | HTTP 传输绑定设置。 | | `AL_ALLOW_INSECURE_BIND` | | `false` | 允许将 http 绑定到非环回主机（无内置身份验证）。 | | `AL_MASK_ERROR_DETAILS` | | `true` | 对客户端隐藏内部异常详情。 | ¹ 提供 **要么** `AL_APIKEY_USER` + `AL_APIKEY` **要么** `AL_USERNAME` + `AL_PASSWORD`。 ### Claude Code ``` claude mcp add assemblyline \ --env AL_URL=https://al.example.org \ --env AL_APIKEY_USER=analyst \ --env AL_APIKEY=your-keyname:secret \ -- uvx assemblyline-mcp ``` ### Claude Desktop 添加到 `claude_desktop_config.json` （[查看示例](examples/claude_desktop_config.json)）： ``` { "mcpServers": { "assemblyline": { "command": "uvx", "args": ["assemblyline-mcp"], "env": { "AL_URL": "https://al.example.org", "AL_APIKEY_USER": "analyst", "AL_APIKEY": "your-keyname:secret" } } } } ``` ### VS Code 请参阅 [examples/vscode_mcp.json](examples/vscode_mcp.json)。 ## 使用方法 ``` assemblyline-mcp # serve over stdio (default) assemblyline-mcp serve -t http -p 8000 # serve over streamable HTTP assemblyline-mcp selftest # run the built-in end-to-end self-test assemblyline-mcp doctor # validate config + connectivity to a real AL assemblyline-mcp version ``` `doctor` 执行 AssemblyLine 连接握手并报告 已通过身份验证的用户 — 这对于容器的 `HEALTHCHECK` 和首次运行设置非常有用。 ## 开发 ``` git clone https://github.com/SauceTaster/assemblyline-mcp cd assemblyline-mcp uv sync # creates .venv with Python 3.12 and all dev deps uv run ruff check . # lint uv run ruff format --check . # formatting uv run mypy # type-check uv run pytest # full test suite (unit + integration + e2e, mock-backed) uv run assemblyline-mcp selftest # the shippable e2e diagnostic ``` 整个测试套件都在进程内的 **mock AssemblyLine** 服务器上运行，因此 无需实时实例，并且适用于任何架构（包括 Apple Silicon）。可选的测试套件用于测试真实实例 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ### 使用 MCP Inspector 进行调试 ``` uv run fastmcp dev src/assemblyline_mcp/server.py ``` ### 结合 Docker Compose 进行端到端测试 ``` docker compose -f docker-compose.e2e.yml up --build # 在 http://localhost:8000/mcp/ 上的 MCP server (http)，由 mock AssemblyLine 支持 ``` ## 安全性 - 凭据仅从环境中读取，且绝不会被记录。 - 破坏性工具受 `AL_ALLOW_ADMIN` 控制；在 HTTP 传输上，它们 还需要具有 `admin` 范围的 token。 - `al_file_download` 仅返回 base64 字节 — 样本**绝不执行**； 超大的文件（`AL_MAX_DOWNLOAD_BYTES`）在未被获取的情况下即会被拒绝。 - **HTTP 传输不提供针对读/写工具的内置身份验证。** 除非您设置了 `AL_ALLOW_INSECURE_BIND=true`，否则它拒绝绑定到非环回地址； 在将其公开之前，请使用强制身份验证的 反向代理或 FastMCP `AuthProvider` 为服务器提供前端保护。 有关披露政策，请参阅 [SECURITY.md](SECURITY.md)。 ## 致谢 - [AssemblyLine 4](https://github.com/CybercentreCanada/assemblyline) 和 由加拿大网络安全中心开发的 [`assemblyline-client`](https://github.com/CybercentreCanada/assemblyline_client)。 - 使用 [FastMCP](https://gofastmcp.com) 构建。 ## 许可证 [MIT](LICENSE)

标签：AI代理工具, AssemblyLine, DAST, MCP服务器, 安全分析自动化, 恶意软件分析, 文件鉴定, 请求拦截, 逆向工具