president-xd/raptor

# 🦅 RAPTOR **Retrieval-Augmented Persistent Threat Orchestration and Reasoning** 一个供安全分析师自托管的APT调查平台。摄取原始 遥测数据，与MITRE ATT&CK进行关联，评分APT归属，预测 可能的下一步对手行动，并生成分析师准备好的取证报告——在一个 单一的工作流程中，完全运行在自己的基础设施上。 ### 管理员 | 方法 | 路径 | 角色 | 描述 | |---|---|---|---| | `GET` | `/audit` | admin | 审计日志条目 | | `GET` | `/metrics` | admin | Prometheus度量 | | `GET` | `/admin/schema/status` | admin | 架构状态 | | `POST` `GET` `PATCH` `DELETE` | `/users` | admin | 用户管理 | ## 角色和访问控制 | 角色 | 权限 | |---|---| | `viewer` | 读取调查、报告、图形、审计日志、威胁源 | | `analyst` | viewer + 创建调查、运行模拟、查询图形 | | `admin` | analyst + 用户管理、系统配置 | | `service` | 完全访问（API-key主体） | RBAC在每个端点强制执行。调查由`tenant_id`范围；分析师只能看到他们自己的租户的案例。用户管理针对普通`admin`账户是租户范围的——只有`service`主体管理所有租户的用户。 ## 证据处理 证据写入`data/evidence/{investigation_id}/`下，并使用AES-256-GCM信封加密。 ``` # 过期证据清理 python3 scripts/ops/cleanup_expired_evidence.py --db data/raptor.db # dry run python3 scripts/ops/cleanup_expired_evidence.py --db data/raptor.db --execute # after approval # 密钥轮换（重新包装DEKs；不重新加密内容） python3 scripts/ops/rotate_evidence_key.py --db data/raptor.db --execute ``` ## 审计跟踪 ``` python3 scripts/ops/verify_audit_chain.py --db data/raptor.db python3 scripts/ops/export_audit_log.py --db data/raptor.db --out exports/audit-log.jsonl # 可选S3上传的定时导出 AUDIT_S3_BUCKET=my-audit-bucket scripts/ops/export_audit_cron.sh ``` cron脚本写入带时间戳的JSONL导出，运行链验证，可选地上传到S3，并修剪90天以上的本地副本。 ## 可观察性 ``` curl http://localhost:8000/api/v1/health/detailed curl -H "X-RAPTOR-API-Key: $KEY" http://localhost:8000/api/v1/metrics ``` 关键指标：`raptor_requests_total`、`raptor_auth_failures_total`、 `raptor_investigations_created_total`、`raptor_investigations_completed_total`、 `raptor_investigations_failed_total`、`raptor_parser_errors_total`、 `raptor_request_latency_seconds_avg`。 参考警报规则位于`observability/prometheus-rules.yml`中，以及`observability/grafana-dashboard.json`中的起始Grafana仪表板。 | 警报 | 条件 | |---|---| | `RaptorHighErrorRate` | 5xx速率>5%持续10分钟 | | `RaptorAuthFailureSpike` | 10分钟内>25次认证失败 | | `RaptorInvestigationFailure` | 15分钟内任何失败 | | `RaptorParserErrorSpike` | 15分钟内>50次解析错误 | | `RaptorHighLatency` | 平均延迟>2秒 | ## 运营手册 ``` # 备份/恢复 scripts/ops/backup.sh backups/$(date -u +%Y%m%dT%H%M%SZ) scripts/ops/restore.sh backups/ # 创建真实管理员后的引导锁定 # 设置 RAPTOR_BOOTSTRAP_ADMIN_DISABLED=true，然后： docker compose restart backend ``` 完整程序——部署姿态、身份、工作操作、备份顺序、审计完整性、事件响应——在 [`docs/production-runbook.md`](docs/production-runbook.md)中。 ## 开发 ### 后端 ``` cd backend python -m venv .venv && source .venv/bin/activate pip install -r requirements.lock pytest RAPTOR_ENV=development uvicorn main:app --reload --port 8000 ``` ### 前端 ``` cd frontend npm ci npm run dev # HMR dev server npm run build # Production build npm run e2e # Playwright tests ``` ### 全栈（代码重新加载） ``` docker compose up -d neo4j weaviate elasticsearch redis cd backend && uvicorn main:app --reload --port 8000 & cd frontend && npm run dev ``` 在容器化设置中，任何对前端CSS/JSX的更改都需要重新构建： ``` docker compose up -d --build frontend ``` ## 测试 后端测试位于存储库根目录的`tests/`中。`conftest.py`将`tests/`和`backend/`添加到`sys.path`，因此不需要安装步骤。 ``` pytest -q tests/ # 或 python -m unittest discover -s tests ``` | 测试文件 | 覆盖率 | |---|---| | `tests/test_ingestion_pipeline.py` | 日志解析、Sigma匹配、规范化 | | `tests/test_parser_graph_nlq.py` | 解析器、图形构建器、NLQ查询引擎 | | `tests/test_graph_query.py` | 图查询构建和守卫 | | `tests/test_analysis_attribution.py` | 归属评分和置信度 | | `tests/test_attack_catalog_matrix.py` | ATT&CK目录/矩阵 | | `tests/test_rag_fallbacks.py` | 当LLM关闭时的确定性回退 | | `tests/test_persistence_connectors.py` | 证据存储、审计防篡改、ES轮询状态、API-key认证 | | `tests/test_api_persistence_connectors.py` | 认证会话、CSRF守卫、ES拉取端点 | | `tests/test_postgres_adapter.py` | SQLite -> PostgreSQL SQL转换 | | `tests/test_postgres_runtime_integration.py` | 完整的PostgreSQL集成（需要`RAPTOR_DB_ENGINE=postgresql`） | | `tests/test_repo_contracts.py` | 存储库合同检查 | 前端端到端测试位于`frontend/e2e/`（`dashboard.spec.js`、`security.spec.js`）中，并通过Playwright通过`npm run e2e`运行。 ## 质量门 ### 本地 在推送之前通过`Makefile`在本地运行门： ``` make validate # pytest + frontend build + prod compose config validation make security-scan # pip-audit (backend) + npm audit --audit-level=high (frontend) make compose-config # validate the production compose overlay renders ``` ### 持续集成（`.github/workflows/ci.yml`） 在每次拉取请求和推送`main`时运行： | 任务 | 验证内容 | |---|---| | `backend-tests` | Python 3.11上的离线回归套件（`pytest tests/`） | | `postgres-integration` | `test_postgres_runtime_integration.py` 对一个实时`postgres:16`服务进行测试 | | `frontend-build` | 生产Vite构建 | | `frontend-e2e` | Playwright功能 + 安全端到端（API模拟，Vite开发服务器） | | `compose-validate` | 生产compose覆盖渲染，使用所有必需的变量 | | `dependency-audit` | `pip-audit`（后端）和`npm audit --audit-level=high`（前端） | | `secret-scan` | Gitleaks对完整历史记录进行秘密扫描 | | `filesystem-scan` | Trivy文件系统扫描（在可修复的CRITICAL上失败） | | `container-scan` | 构建后端和前端镜像，并使用Trivy扫描它们 | ### 发布和签名（`.github/workflows/release.yml`） 在推送`main`和`v*.*.*`标签时运行： - 构建后端和前端镜像，并将它们推送到GitHub 容器注册表（`ghcr.io`）。 - 使用Trivy扫描发布的镜像摘要。 - 使用**Cosign无密钥**（Sigstore / OIDC）对每个推送的摘要进行签名——没有 长期签名的密钥。使用以下方法验证发布的镜像： ``` cosign verify \ --certificate-identity-regexp "https://github.com///.github/workflows/release.yml@.*" \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ ghcr.io///backend: ``` ## 文档 | 文档 | 目的 | |---|---| | [`docs/production-runbook.md`](docs/production-runbook.md) | 部署姿态、身份、工作操作、备份/恢复、事件响应 | | [`docs/threat-model.md`](docs/threat-model.md) | 资产、信任边界、威胁和控制、残余风险 | | [`docs/data-governance.md`](docs/data-governance.md) | 数据类、LLM策略、保留、证据加密、审计 | | [`docs/observability.md`](docs/observability.md) | 度量、日志、操作检查 | | [`docs/scaling-limits.md`](docs/scaling-limits.md) | 运营包络、瓶颈、扩展路径 | | [`CHANGELOG.md`](CHANGELOG.md) | 发布历史 | ## 项目布局 ``` backend/ FastAPI app, pipeline, attribution, graph, rag, ingestion, report frontend/ React 18 + Vite analyst console (Nginx-served container) data/ Mock telemetry, bundled STIX/ATT&CK, runtime evidence (gitignored) docs/ Operational and governance documentation observability/ Prometheus alert rules and Grafana dashboard scripts/ Docker installers, hybrid installers, ops tooling tests/ Backend test suite (run from repo root) docker-compose.yml Local stack (SQLite) docker-compose.prod.yml Hardened production overlay (PostgreSQL + worker) Makefile Local quality gates and ops shortcuts ``` ## 许可证 此存储库受Apache许可证约束。

标签：搜索引擎查询, 测试用例, 请求拦截, 逆向工具