Veridise/audithub-mcp

# AuditHub MCP Server 此代码库包含 `audithub-mcp` 的源代码，这是一个用于 [AuditHub](https://audithub.veridise.com) 的 MCP server。 `audithub-mcp` 允许基于 LLM 的 agent 访问以下功能： * 发现有关 AuditHub 组织和项目的信息 * 启动和监控 AuditHub tool 任务 * 访问 AuditHub 的 issues 和 findings 根据设计，该 MCP server 将功能限制为只读且非破坏性的。 可以通过配置文件启用其他功能。 ## 前置条件 - Python 3.12+ - [uv](https://docs.astral.sh/uv/) ## 安装 `audithub-mcp` 作为一个 Python package 实现，但目前尚未在 PyPI 上提供。 您必须直接从此代码库安装。 ### 全局安装 如果您使用的是 `uv` package manager，则可以使用 `uv` 安装 `audithub-mcp`： ``` uv tool install 'git+https://github.com/Veridise/audithub-mcp' audithub-mcp --help ``` ### 本地克隆 从代码库根目录开始： ``` uv venv uv sync --active ``` 如果您的虚拟环境已经激活，并且您只想运行 server entrypoint，请使用： ``` uv run audithub-mcp --help ``` ## 使用 `audithub-mcp` 要使用 `audithub-mcp`，您需要配置两部分：您的 agent 和 `audithub-mcp` 配置文件。 两者都配置好后，agent 将自动启动 MCP server 并使用其工具。 ### Agent 配置 要在您的 agent 中启用 `audithub-mcp`，您必须将其添加到您的 agent 的 MCP server 配置中。 以下示例假设 `audithub-mcp` 已在 `PATH` 中可用，并且 您的配置文件位于 `~/.config/audithub-mcp/config.yaml`。 * Codex CLI * 对于交互式设置，请使用 `codex mcp add audithub-mcp` * 如果您想使用配置文件进行设置，请将以下内容添加到您的 `.codex/config.toml` 中： [mcp_servers.audithub-mcp] command = "audithub-mcp" args = ["--config", "~/.config/audithub-mcp/config.yaml"] * Claude Code * 对于交互式设置，请使用 `claude mcp add audithub-mcp audithub-mcp` * 如果您想使用配置文件进行设置，请将以下内容添加到您的 `.claude/mcp.json` 中： { "mcpServers": { "audithub-mcp": { "command": "audithub-mcp", "args": [ "--config", "~/.config/audithub-mcp/config.yaml" ] } } } ### MCP Server 配置 您将需要创建一个包含 `audithub-mcp` server 创建信息的 YAML 文件，并确保 agent 配置调用 `audithub-mcp` 时使用了 `--config ` 参数。 如果您不确定将配置文件放在哪里，建议的默认位置是 `~/.config/audithub-mcp/config.yaml`。 文件权限应设置为 `400`（所有者只读），因为它包含 凭证。 有关如何创建 配置文件的详细信息，请参阅[配置文档](./docs/configuration.md)。 ## 可用的 MCP 工具 | 工具 | 描述 | |---|---| | `get_organizations` | 列出允许列表中的组织；传入 `details=true` 获取完整的组织记录，传入 `filter_id` 缩小结果范围 | | `get_defi_vanguard_detectors` | 使用 Vanguard 列表块格式列出组织的所有 DeFi Vanguard detector | | `get_projects` | 列出组织中允许列表里的项目；传入 `details=true` 获取完整的项目记录，传入 `filter_id` 缩小结果范围 | | `get_versions` | 列出项目的版本；传入 `details=true` 获取完整的版本记录，传入 `filter_id` 缩小结果范围，传入 `latest_only=true` 仅获取最新版本 | | `get_task_info` | 获取 AuditHub task 的状态和详细信息 | | `get_task_artifacts` | 列出 AuditHub task 的已清理 artifact 元数据 | | `get_task_artifact` | 通过 ID 获取 task artifact，内容为 base64 编码 | | `get_task_logs` | 获取 task 一个或多个步骤的日志，并将每个结果写入本地输出文件 | | `get_task_findings` | 获取 task 的 findings 并将其写入本地输出文件 | | `wait_for_task_completion` | 轮询 task 直到没有待处理步骤或达到超时，然后返回最新的 task 快照和完成状态；如果没有超时，支持 task 的客户端可以将其作为 task 调用 | | `parse_findings_from_task_log` | 将一个或多个 task 日志文件解析为包含 findings 及计数的 JSON，并写入本地绝对输出路径 | | `get_version_comments` | 获取特定项目版本的评论 | | `get_version_comment_threads` | 获取特定项目版本的评论线程 | | `get_thread_comments` | 获取项目版本中特定线程的评论 | | `get_project_issues` | 获取项目的所有 issue | | `get_project_issue` | 获取项目中的特定 issue | | `get_project_comments` | 获取项目跨所有版本的所有评论 | | `run_orca_task` | 为项目版本启动 OrCa task；仅在显式启用 task 运行时注册 | | `run_defi_vanguard_task` | 为项目版本启动 DeFi Vanguard task；仅在显式启用 task 运行时注册 | | `create_version_from_file` | 通过上传本地 `.zip` 压缩包创建项目版本；仅在显式启用版本创建时注册 | | `create_version_from_url` | 从 git 仓库或压缩包 URL 创建项目版本；仅在显式启用版本创建时注册 | 所有工具均返回由 `audithub-sdk` 模型支持的带类型的 Python 对象。 `get_organizations`、`get_projects` 和 `get_versions` 返回的对象 仅公开属于已配置允许列表中组织/项目的条目。 ## 安全模型 - **默认只读。** 默认工具命名为 `get_*`，并且仅调用生成的 `audithub-sdk` GET endpoint。 - **Task 完成轮询。** `wait_for_task_completion` 会重复获取 task 详细信息，直到没有待处理步骤或达到超时，然后返回带有布尔完成标志的最新已清理 `Task` 快照。当支持 task 的客户端在无超时的情况下调用时，它可以作为 task 运行，而不是阻塞请求。 - **可选的 OrCa task 执行。** 仅在提供 `AH_ENABLE_TASK_RUNS=1` 或 `--enable-task-runs` 时才会注册 `run_orca_task` mutation 工具。它通过 `audithub-sdk` 调用生成的 OrCa POST endpoint。 - **可选的 DeFi Vanguard task 执行。** `run_defi_vanguard_task` mutation 工具在同一 task 运行可选开关下注册。其输入在顶层被展平：`organization_id`、`project_id`、`version_id`、detector 选择以及 runtime 选项。将 detector 选择作为包含两个元素的 JSON 数组 `[type, id]` 传递，其中内置选择器使用来自 `get_defi_vanguard_detectors` 的内置 detector 代码，自定义选择器使用同一工具显示的目录 ID。server 在调用生成的 DeFi Vanguard v2 POST endpoint 之前，会通过后端 detector 目录解析这些选择。 - **链上 OrCa 模式。** 在针对已部署的合约启动 OrCa 时，请将 `deployment_info_file` 作为以 `.deployment.json` 结尾的路径传递。server 会将其标准化为 `on_chain=True` 并提前拒绝不匹配的路径，以便调用者不会意外启动本地 Foundry 风格的运行。 - **可选的版本创建。** 仅在提供 `AH_ENABLE_VERSION_CREATION=1` 或 `--enable-version-creation` 时才会注册 `create_version_from_url` mutation 工具。它通过 `audithub-sdk` 调用生成的项目版本 URL POST endpoint。 - **本地 findings 解析。** `parse_findings_from_task_log` 实用工具读取一个或多个本地 task 日志文件，使用共享的日志解析器提取 findings，并写入包含已解析 findings 以及 findings 总数和每个日志计数的 JSON 文件。它不会调用 AuditHub API。 - **Detector 目录缓存。** DeFi Vanguard v2 内置 detector 列表是从 AuditHub 配置 endpoint 惰性获取的，并在进程内缓存一天。自定义 detector 在每次请求时从组织库和标准库中实时获取。 - **Detector 列表格式。** `get_defi_vanguard_detectors` 为每个 detector 返回一个块。每个块以 `detector: ` 开始，其中 `` 是与 `DefiVanguardV2DetectorSelectionInput` 匹配的 JSON 值，后跟 `title:`。标准库的自定义 detector 还包含从 detector payload 加载的 `description:`。每个块以 `------` 结束。 - **凭证隔离。** OIDC 凭证在启动时从环境中读取一次，并传递给 `audithub_sdk_ext.AuthenticatedApiClient`。它们永远不会被接受作为工具参数，也不会出现在工具输出或已清理的错误消息中。 - **ID 允许列表。** Server 拒绝访问任何其数字 ID 未明确包含在 `AH_ALLOWED_ORG_IDS` / `AH_ALLOWED_PROJECT_IDS` 中的组织或项目。该检查在任何网络请求之前运行。 - **仅限 SDK 传输。** 所有 AuditHub 交互均通过 `audithub-sdk` 和 `audithub_sdk_ext` 进行；MCP server 中没有原始 HTTP 辅助程序。 ## 开发工作流 - 运行测试：`uv run pytest` - 类型检查：`uv run mypy` - Lint：`uv run ruff check` - 格式化代码：`uv run ruff format` ### 在本地覆盖 `audithub-sdk` 要针对 `audithub-sdk` 的本地检出测试 `audithub-mcp`，请在根目录的 [`pyproject.toml`](./pyproject.toml) 中添加路径源 覆盖，然后重新同步 环境。 根目录 `pyproject.toml` 覆盖示例： ``` [tool.uv.sources] audithub-sdk = { path = "/absolute/path/to/audithub-sdk", editable = true } ``` 然后运行： ``` uv sync --active ``` 要返回固定版本，请从 `[tool.uv.sources]` 中移除 `audithub-sdk` 条目，然后再次运行 `uv sync --active`。 ## 许可证 [Apache 2.0](./LICENSE)

标签：AI代理集成, LLM工具, MCP服务器, Python, 区块链安全, 无后门, 智能合约审计, 逆向工具