puck-security/puck-scout

# Puck [](LICENSE) [](https://github.com/puck-security/puck-scout/releases/latest) [](https://github.com/puck-security/puck-scout/actions/workflows/go.yml) **通过 MCP 进行自主、只读的 endpoint 调查。** 用简单的自然语言询问关于您的资产库的问题；获取包含处置建议的叙述性回答。 [快速开始](docs/getting-started.md) · [参考手册](docs/reference.md) · [架构](docs/architecture.md) · [安全](docs/security.md) · [**企业版 / 托管版 ↗**](https://puck.security/enterprise)

## 工作原理 ``` You type a question | v ┌──────────────────────────────────────────────────────┐ │ MCP Client (Claude Code / Cursor / any MCP client) │ │ Calls puck_investigate, reasons about results, │ │ decides what to check next │ └──────────────────┬───────────────────────────────────┘ │ stdio (JSON-RPC) v ┌──────────────────────────────────────────────────────┐ │ MCP Server (Go) │ │ Loads skills, validates commands against policy │ │ engine, fans out to agents, writes audit log before │ │ every command, enforces cost caps │ └─────────┬──────────────┬──────────────┬──────────────┘ │ mTLS poll │ │ v v v ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Agent │ │ Agent │ │ Agent │ Rust binaries. │ host-01 │ │ host-02 │ │ host-03 │ Read-only. Does not └─────────┘ └─────────┘ └─────────┘ write to disk. ``` **调查流程**: pathfinder → checkpoint → fleet → iterate → analyze → save（持久化到 `investigations/`）。有关每个阶段的具体作用，请参阅[架构](docs/architecture.md)。 ## MCP 工具 | 工具 | 功能描述 | |------|--------------| | `puck_investigate` | 启动调查；返回已连接的 agent 和初始 skill 上下文。 | | `puck_list_skills` | 列出已加载的 skill —— 在调用 `puck_investigate` 之前调用，以发现可用功能。 | | `puck_get_skill_section` | 按需获取绑定的 skill 的附加部分（`fleet_strategy`、`remediation_guidance`、`readme`、`full`）。 | | `puck_run_check` | 在单个 endpoint 上运行单个只读命令。 | | `puck_query_fleet` | 在多个 endpoint 上并行扩展执行命令。 | | `puck_save_analysis` | 将最终报告保存为 markdown。 | | `puck_continue` | 当调查需要更多轮次时，扩展命令预算。 | 完整 schema 请见 [reference.md](docs/reference.md)。 ## 组件 - **Endpoint Agent** (Rust, `agent/`) —— endpoint 上的只读命令执行器。支持 Linux、macOS 和 Windows（amd64 + arm64）的原生二进制文件。 - **MCP Server** (Go, `mcp/`) —— 编排调查流程：加载 skill、验证命令、分发任务给 agent、写入审计日志。 - **Skills Library** (YAML, `skills/`) —— 调查 playbook。无需编写 Rust 或 Go 代码即可贡献新的 skill。 ## 快速开始 安装服务器，注册一个 endpoint，开始调查。从 [GitHub Releases](https://github.com/puck-security/puck-scout/releases/latest) 下载二进制文件。 **1. 设置 MCP server**（您的工作站或运维机） ``` # 将 puck-mcp 安装到 PATH，然后： bash <(curl -fsSL https://raw.githubusercontent.com/puck-security/puck-scout/main/scripts/setup-mcp.sh) \ --hostname $(hostname) ``` 这将生成 CA、服务器证书和配置。如果已安装 `claude` CLI，它会自动将 Puck 注册为 MCP server —— 无需手动配置。否则，它将打印出手动注册的命令。 **2. 注册一个 endpoint** ``` # 在服务器上：生成一次性 bootstrap token puck-mcp generate-bootstrap-token --hostname eng-laptop-47 # 在 endpoint 上：安装 + 注册（token-safe 模式；完整详情见 docs/getting-started.md）： TF=$(mktemp /tmp/puck-bt.XXXXXX) && chmod 600 "$TF" printf 'Paste puck-bt-… (hidden): '; read -rs T; echo; printf '%s' "$T" > "$TF"; unset T bash <(curl -fsSL https://raw.githubusercontent.com/puck-security/puck-scout/main/scripts/install-agent.sh) \ --server https://your-server:50281 \ --hostname eng-laptop-47 \ --token-file "$TF" \ --download-binary shred -u "$TF" 2>/dev/null || rm -f "$TF" ``` **3. 调查** 打开 Claude Code 并询问： ``` Use puck to check eng-laptop-47 for credential exposure ``` 对每个要调查的 endpoint 重复步骤 2。对于批量注册（10 台以上主机），请参阅[快速开始](docs/getting-started.md#multiple-hosts-fleet-enrollment)。 有关工具 schema、配置字段和 CLI 文档，请参阅[参考手册](docs/reference.md)。 ## 隐私 Puck 会将 endpoint 的发现结果（进程列表、文件路径、网络连接、凭据暴露情况）发送给 Claude 进行分析。**在未首先禁用模型训练的情况下，请勿在 Free、Pro 或 Max Claude.ai 账户下运行 Puck** —— 这些计划默认使用对话数据来训练模型，并保留 5 年。 | 认证方式 | 默认进行训练 | 适合敏感数据 | |---|---|---| | Anthropic API key (`ANTHROPIC_API_KEY`) | 否 —— 始终适用商业条款 | 是 | | Claude Code OAuth —— Teams 或 Enterprise 计划 | 否 —— 适用商业条款 | 是 | | Claude Code OAuth —— Free、Pro 或 Max 计划 | **是，除非手动选择退出** | 仅在选择退出后适合 | 如果您正在使用 Free、Pro 或 Max 计划且无法更改，请在运行任何调查之前前往 [claude.ai/settings/data-privacy-controls](https://claude.ai/settings/data-privacy-controls) 选择退出。强烈建议在生产环境中使用 API 或 Teams/Enterprise 计划。 权威政策请参阅 [Anthropic 的数据使用文档](https://code.claude.com/docs/en/data-usage)。 ## 安全模型 一种共享的类型化白名单（`policy/policy.toml`，内嵌于两个二进制文件中）由服务器（分发前）和 agent（执行前）独立执行。任何不在编译内语法中的内容都将被拒绝 —— 被攻破的服务器也无法指示 agent 运行任何新内容。操作员可以通过 `/etc/puck/policy-overrides.toml` 启用/禁用现有条目；添加新的二进制文件需要提交 PR。**Puck 被攻破的最坏情况是未经授权的读取访问，而不是未经授权的修改。** **EDR 和 endpoint 安全工具可能会标记 puck-agent。** 该 agent 会读取敏感文件（进程内存映射、钥匙串、凭据文件、网络连接），因此使其对 IR 有用的相同信号也可能会触发安全产品中的启发式规则。如果您要在 EDR 旁边部署，请在注册 endpoint 之前将 `puck-agent` 二进制文件加入白名单 —— 在调查中途遇到来自您自己的 IR 工具的误报是非常糟糕的。 完整的威胁模型请参阅 [docs/security.md](docs/security.md)。 ## 项目布局 ``` puck-scout/ agent/ Rust endpoint agent mcp/ Go MCP server skills/ Investigation playbooks (YAML) demo/ Demo scripts for local testing docs/ Architecture, security model, ADRs, getting started integrations/ Third-party integrations (TheHive, Tines) ``` ## 企业版 / 托管版 Puck Scout 是 MIT 许可下的开源调查核心 —— 免费使用、修改和自托管。对于想要比自托管更多的功能的团队： | | OSS（此仓库） | Puck Security（托管版） | |---|---|---| | MCP server | 自托管 | 托管的多租户智能核心 | | SSO + RBAC | 自己动手 | 内置（Okta, Azure AD, Google） | | 多租户 fleet-of-fleets | 每个服务器一个 fleet | 是，支持每个租户的审计隔离 | | 合规性认证 | 无 | SOC 2 Type II + 符合 HIPAA 标准 | | 团队构建的 skill | YAML，通过 PR 贡献 | 由 Puck 团队构建和维护的定制 skill | | 调查 runbook | 自己编写 | 经过桌面推演测试，由 IR 工程师审查 | | 支持 | GitHub issues | 24×7 并带有 SLA | 前往 **[puck.security/enterprise](https://puck.security/enterprise)** ## 文档 - [快速开始](docs/getting-started.md) —— 安装 + 首次调查 - [教程](docs/tutorial.md) —— 完整的 Trivy 泄露事件演练 - [参考手册](docs/reference.md) —— 工具 schema、配置字段、skill YAML、CLI - [架构](docs/architecture.md) —— 系统设计和数据流 - [安全模型](docs/security.md) —— 威胁模型 + 部署建议 - [运维指南](docs/operations.md) —— PKI 恢复、CA 轮换、策略迁移 - [贡献](docs/contributing.md) —— skill、bug 修复、新功能 ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。 贡献者在首次提交 PR 时需签署 CLA —— 请参阅 [CLA.md](CLA.md)。 版权所有 (c) 2026 Puck Security, Inc.

标签：DLL 劫持, EVTX分析, Go语言, MCP, PB级数据处理, 可视化界面, 大语言模型, 安全运维, 无线安全, 日志审计, 程序破解, 端点检测与响应(EDR), 自动化调查