sunilgentyala/bait-edr

一个审计优先的终端检测与响应参考框架，用于可解释的入侵检测、证据保留和策略控制的响应。

## BAIT 的功能 BAIT 收集终端观测数据，将其标准化为可移植的事件契约，评估易读的 YAML 检测规则，关联重复活动，存储证据，并通过 CLI 和 API 暴露策略控制的响应操作。 该框架具有刻意的透明性。每个告警都会保留产生该告警的事件、规则、严重性、风险评分、ATT&CK 映射、匹配解释和建议操作。 ### 工程原则 1. **行动前保留证据：** 检测会保留源事件和匹配的确切字段。 2. **审计优先的响应：** 在管理员启用主动模式和特定操作之前，破坏性操作将被禁用。 3. **目标验证：** 进程终止在执行前会检查 PID、进程名和创建时间。 4. **可移植的遥测数据：** 事件使用通用的进程、文件、网络、用户和身份验证对象。 5. **可衡量的行为：** 合成测试可在不执行恶意软件的情况下验证规则和响应策略。 ## 已验证的架构

该图直接映射到已实现的类和接口。有关组件到代码的验证表和未解决的生产环境差距，请参阅 [FRAMEWORK_REVIEW.md](FRAMEWORK_REVIEW.md)。 ### 当前功能 - 通过 `psutil` 进行跨平台进程快照，并丰富父进程信息 - 已建立的 TCP 连接快照，不臆造入站或出站方向 - 标准化的终端事件和告警模型 - 受 Sigma 启发的 YAML 规则，带有 schema、运算符、条件、ATT&CK 标签和响应操作验证 - 五个映射到相关 ATT&CK 技术的入门级检测 - 用于事件、告警和响应结果的有状态 SQLite 存储 - 基于复发情况的风险关联 - 安全的分流收集 - 受策略控制的进程终止和文件隔离 - FastAPI 数据接入、告警审查和响应 endpoint - 用于本地收集、规则验证、演示和 API 启动的 Typer CLI - 可选的 YARA 文件检查 - GitHub Actions CI、CodeQL、Dependabot 和 GitHub Pages 部署 - 静态文档站点和经过净化的网站状态小部件 ## 快速开始 ### Linux 或 macOS ``` python -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -e ".[dev]" cp config.example.yml config.yml bait validate-rules bait demo bait run --once ``` ### Windows PowerShell ``` py -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip pip install -e ".[dev]" Copy-Item config.example.yml config.yml bait validate-rules bait demo bait run --once ``` 启动本地 API： ``` bait serve --host 127.0.0.1 --port 8765 ``` 打开 `http://127.0.0.1:8765/docs` 查看生成的 OpenAPI 接口。 安全演示会提交合成的 PowerShell 和 TCP 连接事件。它不会执行 payload 或修改终端。 ## 检测流程 1. `ProcessCollector`、`NetworkCollector` 或 `POST /events` 创建一个 `EndpointEvent`。 2. `DetectionEngine` 评估已验证的规则选择。 3. `Correlator` 添加有界的复发上下文。 4. `SQLiteStorage` 持久化源事件和生成的告警。 5. API 或 CLI 暴露告警以供审查。 6. `ResponseManager` 通过 `ResponsePolicy` 发送明确的响应请求。 7. 每次响应都会生成一个包含状态和证据的已存储 `ResponseResult`。 ### 网络方向准确性 可移植的 `psutil` API 提供已建立的连接快照，但无法可靠地识别哪一方发起了每个连接。因此，BAIT 针对可移植的收集器报告 `network.direction: unknown`。在 BAIT 能够声明已验证的方向之前，需要原生的 Windows、Linux 和 macOS 收集器。 ## 入门级检测 | 规则 | 检测 | 严重性 | ATT&CK | |---|---|---:|---| | `BAIT-1001` | 编码的 PowerShell 执行 | 高 | T1059.001 | | `BAIT-1002` | 面向用户的应用程序启动脚本解释器 | 高 | T1204.002, T1059 | | `BAIT-1003` | 从临时目录启动的可执行文件 | 中 | T1204.002 | | `BAIT-1004` | 连接到不常见远程访问端口的 TCP 连接 | 中 | T1095 | | `BAIT-1005` | 聚合事件中的多次身份验证失败 | 中 | T1110 | 这些规则是入门级的启发式规则。在生产使用之前，每一项都需要针对特定环境进行调优、良性的负向测试以及误报测量。 ### 规则示例 ``` - id: BAIT-1001 title: Suspicious Encoded PowerShell Execution description: Detects PowerShell command lines that use encoded command switches. severity: high tags: - attack.execution - attack.t1059.001 logsource: category: process_creation product: windows detection: selection: event.category: process process.name|endswith: - powershell.exe - pwsh.exe process.command_line|regex: - "(?:^|\\s)-(?:enc|encodedcommand)(?:\\s|:)" condition: selection response: - collect_triage - terminate_process false_positives: - Approved administrative automation that intentionally uses encoded PowerShell ``` BAIT 受到了 Sigma 概念的启发，但并不是完整的 Sigma 实现。请参阅 [STANDARDS.md](STANDARDS.md)。 ## 响应安全性

默认模式是 `audit`。在审计模式下，BAIT 会记录计划的响应，但不会终止进程或移动文件。 激活本地操作需要满足以下所有条件： - `response.mode: active` - 启用了特定的操作标志 - 有效的目标 - 目标在受保护的进程和路径边界之外 - 在执行前立即进行目标身份验证 主机隔离和指标阻断将作为外部执行的记录计划保留。核心框架不会更改主机防火墙规则。 ## 配置 将 [config.example.yml](config.example.yml) 复制到 `config.yml`。安全的默认设置会将 API 绑定到 localhost，并保持禁用主动响应。 在允许从其他主机进行访问之前设置 API token： ``` export BAIT_API_TOKEN="replace-with-a-long-random-secret" bait serve ``` 请勿将 token 放置在源代码管理或浏览器 JavaScript 中。 ## API 接口 | 方法 | 路径 | 用途 | |---|---|---| | `GET` | `/health` | 基本的本地健康状态和记录计数 | | `GET` | `/alerts` | 列出已存储的告警，在配置时强制执行 bearer token 验证 | | `POST` | `/events` | 接入标准化的终端事件 | | `POST` | `/alerts/{alert_id}/respond?action=...` | 请求经过策略评估的响应 | 在添加 TLS、身份感知访问、RBAC、审计身份和速率控制之前，请将管理 API 保持私有。 ## 仓库结构 ``` bait_edr/ Python package collectors/ Process and network collectors detection/ Rule loading, validation, and matching response/ Policy and response actions rules/ Built-in detection rules tests/ Unit and integration tests scripts/ Safe demonstrations and site validation docs/ GitHub Pages site, diagrams, and assets website-integration/ External website widget and proxy examples .github/ CI, CodeQL, Pages, issue forms, and Dependabot ``` ## 验证 版本 0.2.1 已在 Python 3.13.5 和 3.14.4 上进行了验证，验证内容包括： - 39 个通过的测试 - 80% 的测量行覆盖率 - 成功的 Python 字节码编译 - 成功验证所有五个内置规则 - 一次安全的合成演示产生了两个预期的告警 - FastAPI 健康、身份验证、数据接入、告警检索和响应检查 - 在没有主动响应的情况下的实时进程和 TCP 快照收集 - 成功的 wheel 构建和包含所有五个打包规则的独立安装 - 成功渲染所有架构和响应图的 Graphviz - 静态网站资产和内部链接验证 请参阅 [VERIFICATION.md](VERIFICATION.md) 和 [test-results](test-results/)。 ## GitHub Pages 和您的网站 `docs` 目录已为 GitHub Pages 准备就绪。在仓库中，打开 **Settings > Pages**，选择 **GitHub Actions**，然后运行包含的部署工作流。 当托管在 GitHub Pages 上时，网站会自动确定仓库 URL。如果所有者或仓库名称不同，请更新 `docs/app.js` 中的后备值。 对于您现有的网站，请查看 [website-integration/README.md](website-integration/README.md)。仅通过服务器端 endpoint 发布经过净化的聚合状态。切勿将管理 bearer token 暴露给浏览器。 ## 安全与治理 在发布或部署之前： - 启用私有的漏洞报告 - 启用 Dependabot 告警、机密扫描、推送保护和代码扫描 - 使用必需的 CI 检查和 Pull Request 审查来保护 `main` - 对标记的发布进行签名并发布校验和 - 运行受控的审计模式试点 - 完成针对终端遥测的隐私、法律和运营审批 请参阅 [SECURITY.md](SECURITY.md)、[THREAT_MODEL.md](THREAT_MODEL.md)、[CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。 ## 生产环境差距 BAIT 尚未提供内核遥测、防篡改保护、集群管理、TLS 终止、多租户授权、签名规则包、强制保留或经过生产认证的遏制。这些局限性已被记录在案，而不是被隐藏。 ## 路线图 1. 原生的 Windows Event Log、ETW、AMSI 和服务收集器 2. Linux audit 和 eBPF 收集器 3. macOS Endpoint Security 收集器 4. 签名的规则、配置、发布和软件物料清单 (SBOM) 5. OCSF 导出和 OpenTelemetry 传输 6. 带有一致性测试的 Sigma 转换 7. 规则抑制、允许列表、基线和 ATT&CK 覆盖率报告 8. 具有租户隔离和委派管理的中心化集群管理 ## 许可证 基于 [Apache License 2.0](LICENSE) 授权。

标签：Python, 安全合规, 无后门, 端点检测与响应, 网络代理, 脱壳工具, 逆向工具