使用说明

Velociraptor MCP服务器

快速入门

安装已发布的软件包： python3 -m venv .venv && . .venv/bin/activate && pip install velociraptor-mcp-server
运行（需要mTLS配置）： velociraptor-mcp --config /absolute/path/to/velociraptor_lab/volumes/api/api.config.yaml

Codex一衬（安装包装）：

codex mcp add velociraptor \
  --env VELOCIRAPTOR_API_CONFIG=/absolute/path/to/velociraptor_lab/volumes/api/api.config.yaml \
  -- velociraptor-mcp --config /absolute/path/to/velociraptor_lab/volumes/api/api.config.yaml \
  --log-level INFO --server-name velociraptor-mcp

基于FastMCP的服务器，通过MCP协议公开Velociraptor功能（VQL查询、狩猎、工件、VFS/文件操作、监控、警报），供Codex/ChatGPT风格的代理使用。

先决条件

Python 3.10+
如果你想使用附带的Podman（或Docker） velociraptor_lab 用于本地测试。
生成的Velociraptor mTLS API配置(api.config.yaml)实验室可以为你生成这个。

安装/开发

来自PyPI： pip install velociraptor-mcp-server
运行时（源）： pip install .
开发/可编辑： pip install -e .[dev]
遗产： pip install -r requirements.txt
预承诺： pre-commit install 然后 pre-commit run --all-files

设定目标（参见 Makefile): make dev, make test, make build, make health, make release VERSION=0.1.6.

运行MCP服务器

安装后，您可以直接调用模块或使用已安装的控制台脚本：

# installed entry point
velociraptor-mcp --config velociraptor_lab/volumes/api/api.config.yaml \
  --log-level INFO --server-name velociraptor-mcp

# or, from source
python3 main.py --config velociraptor_lab/volumes/api/api.config.yaml \
  --log-level INFO --server-name velociraptor-mcp

选项：

--config 或env VELOCIRAPTOR_API_CONFIG：路径 api.config.yaml （默认值 volumes/api/api.config.yaml)
--log-level 或env MCP_LOG_LEVEL （默认值 INFO)
--server-name 或env MCP_SERVER_NAME

可用工具（摘要）

VQL ： query_vql
客户： list_clients, get_client_info, search_clients
狩猎： list_hunts, get_hunt_details, create_hunt, stop_hunt, get_hunt_results
人工产品： list_artifacts, collect_artifact, upload_artifact, get_artifact_definition
文件/VFS： list_directory, get_file_info, download_file
监控/警报： get_server_stats, get_client_activity, list_alerts, create_alert
资源/提示：工件目录、VQL模板、事件响应提示

使用实验室（建议用于开发）

velociraptor_lab/ 包含一个启动的Podman/Docker堆栈：

Velociraptor服务器（GUI+gRPC）
应自动注册的测试客户端
在以下条件下生成的mTLS配置 velociraptor_lab/volumes/{server,client,api,datastore}

快速入门（Podman）：

cd velociraptor_lab
podman machine start                     # macOS/AppleHV
podman compose -f podman-compose.yml up --build -d
# or use the manual podman run commands in velociraptor_lab/README.md

验证API：

. ../.venv/bin/activate
python test_api.py --config volumes/api/api.config.yaml

然后运行MCP服务器（见上文），指向生成的 api.config.yaml.

实验室注册故障排除：

客户必须到达 https://VelociraptorServer:8000/ 在podman网络内。保持主机名/别名与证书CN一致。
如果 clients() 为空，删除 velociraptor_lab/volumes/* 并重新部署实验室。
对于手动探测， python test_api.py --query "SELECT * FROM clients()".

发展

创建一个新的venv并安装dev-extras： python3 -m venv .venv && . .venv/bin/activate && pip install -e .[dev].
在本地运行单元测试： . .venv/bin/activate && pytest.
对照实验室验证API接线： python test_api.py --config velociraptor_lab/volumes/api/api.config.yaml --query "SELECT * FROM clients()" （提到实验室后）。
如今，棉绒很少；专注于测试，并保持工具名称/配置键与VQL和env-var保持一致。

测试

. .venv/bin/activate
pytest

注：如果出现以下情况，则自动跳过API实验室测试 pyvelociraptor 或者缺少配置。

Codex MCP设置

您可以使用Codex CLI（stdio传输）注册此服务器。选择一条路径：

本地源代码/dev运行： （来自回购）

python3 main.py --config velociraptor_lab/volumes/api/api.config.yaml \
  --log-level INFO --server-name velociraptor-mcp

要让Codex从源头运行，请点 codex mcp add ... -- python3 main.py ... 绝对路径。

手动配置文件（Codex）： 添加到 ~/.codex/config.toml 如果您更喜欢直接编辑：

[mcp_servers.velociraptor]
command = "python3"
args = ["main.py", "--config", "/absolute/path/to/velociraptor_lab/volumes/api/api.config.yaml", "--log-level", "INFO", "--server-name", "velociraptor-mcp"]
env = { VELOCIRAPTOR_API_CONFIG = "/absolute/path/to/velociraptor_lab/volumes/api/api.config.yaml" }
cwd = "/absolute/path/to/velociraptor-mcp-server"  # optional but recommended
startup_timeout_sec = 15   # optional; defaults to 10
tool_timeout_sec = 120     # optional; defaults to 60

食品法典委员会的常见问题：

确保 VELOCIRAPTOR_API_CONFIG 指向mTLS api.config.yaml 由实验室生成。
如果握手失败，请检查 ~/.codex/log/codex-tui.log 对于MCP过程stderr；大多数故障都是缺少配置路径或证书。
在带有Gatekeeper的macOS上，确保允许venv-python运行二进制文件（罕见）。

故障排除

ModuleNotFoundError 或 grpc 缺失→ 确保你在真空中奔跑 pip install ..
Velociraptor API config not found → point --config / VELOCIRAPTOR_API_CONFIG 对于生成 api.config.yaml.
Codex握手失败→ check ~/.codex/log/codex-tui.log；最常见的是缺少配置路径。
PEP 668“外部管理”错误→ 始终使用venv（如上所述）。

结构

mcp_server/       # server, tools, resources, prompts
main.py           # entrypoint
tests/            # unit tests + fixtures
requirements.txt  # shared deps (MCP + lab)
velociraptor_lab/ # podman/docker lab for local Velociraptor API

Docker（可选）

构建并运行已挂载的 api.config.yaml:

docker build -t velociraptor-mcp .
docker run --rm -v $PWD/velociraptor_lab/volumes/api/api.config.yaml:/app/velociraptor_lab/volumes/api/api.config.yaml:ro \
  -e VELOCIRAPTOR_API_CONFIG=/app/velociraptor_lab/volumes/api/api.config.yaml \
  velociraptor-mcp

Env模板

看 example.env 对于常见变量(VELOCIRAPTOR_API_CONFIG, MCP_LOG_LEVEL, MCP_SERVER_NAME).

出版/发布

自动化（GitHub操作，标签推送上的可信发布）：

git add pyproject.toml mcp_server/__init__.py README.md
git commit -m "Release X.Y.Z"
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin main && git push origin vX.Y.Z

手册（如果必须）：

python -m venv .venv && . .venv/bin/activate
pip install -U pip build twine
python -m build --no-isolation
python -m twine check dist/*
twine upload dist/*

通过GitHub操作发布

如果您的CI在标记推送上发布，请使用以下步骤：

git add pyproject.toml mcp_server/__init__.py README.md
git commit -m "Release 0.1.6"        # or skip if already committed
git tag -a v0.1.6 -m "v0.1.6"        # bump tag version as needed
git push origin main                  # adjust branch name if different
git push origin v0.1.6                # triggers the release workflow

可信发布：工作流使用PyPI OIDC；注册 .github/workflows/ci.yml 作为PyPI项目设置中的受信任发布者。不 PYPI_API_TOKEN 一旦链接，就需要。

许可证

该项目根据MIT许可证获得许可。看 LICENSE 全文。