FlorianStuettgen/SOC_Replay

 SOC_Replay 将安全组合中通常分开呈现的两个系统结合在了一起： 1. 一个**真实的分段网络靶场**，包含企业级计算、存储、网络强制执行、遥测和带外恢复；以及 2. 一个**确定性的证据引擎**，用于编译可检查的检测规则、评估合成或经过脱敏处理的遥测数据、验证精确声明的结果，并发布可进行完整性检查的报告包。 该项目围绕一个原则构建： SOC_Replay 保留了这些证据类别，而不会假装它们是可以互换的。 ## 90 秒证明 ``` python -m venv .venv . .venv/bin/activate # Windows: .venv\Scripts\activate python -m pip install -e . soc-replay doctor soc-replay run scenarios/network-scan --output build/network-scan soc-replay verify-bundle build/network-scan ``` 预期结果： ``` replayed 7 events; detections=1 verification: PASS plan: <64-character semantic fingerprint> ledger: <64-character execution root> bundle: <64-character bundle identity> bundle verification: PASS ``` 生成的包包含： ``` build/network-scan/ ├── report.json # machine-readable evidence and per-rule traces ├── report.md # analyst-readable evidence └── manifest.json # artifact hashes, execution identity, and bundle ID ``` ## 执行结构  该引擎是一个明确的五阶段 pipeline： | 阶段 | 职责 | 确定性输出 | | --- | --- | --- | | **Load** | 验证并深度冻结 scenario 和 JSONL 事件输入 | Provenance hashes 和 run ID | | **Compile** | 绑定 accessors/operators 并编译候选 selectors | Plan 和逐规则指纹 | | **Index** | 构建不可变 indexes 并交集安全 selectors | 稳定的候选集和 index digest | | **Evaluate** | 执行每一条规则并保留正检测或零检测的 trace | 有序的 detection 和规则执行记录 | | **Verify** | 将结果与精确声明的 detection contract 进行比较 | 机器可读的 PASS/FAIL | 每个阶段都会向一个严格类型化且经过加密链接的执行账本中追加一条记录。验证器强制执行严格的阶段顺序、digest 格式、计数值类型、元数据结构、hash 连续性、完成状态以及根身份。 参见 [执行核心](docs/22-Execution-Core.md)、[执行账本](docs/23-Execution-Ledger.md) 和 [合约验证](docs/24-Contract-Validation.md)。 ## “完整合约”的含义 ### 深度不可变的 runtime 状态 仅仅冻结 dataclass 并不能使嵌套的映射和列表变得不可变。SOC_Replay 会递归冻结事件详情、条件值、期望映射、检测组、关联元数据、验证值以及账本元数据。序列化后的输出依然是常规的 JSON。 ### 完整的语义指纹 规则指纹涵盖了所有影响输出的字段： - identity、显示名称、severity 和描述； - 所有的 match 条件和值； - 聚合分组、threshold、duration、distinct-value 和 window 策略； - 模拟的 response action、描述和 mode。 改变行为或报告可见的含义都会改变指纹。 ### 复合候选计划 编译器会提取出每一个安全的 indexed selector，而不仅仅是第一个。索引会确定性地交集 equality 和 tag 池，随后应用完全编译好的 predicate 集合。候选选择改变的是成本，而绝不会改变真假条件。 ### 每一条规则都留下 trace 每一次规则执行都会记录： - 候选策略和候选计数； - matched-event 计数； - group 计数； - 考虑的 window 数；以及 - detection 计数。 因此，零检测规则是可见的证据，而不是证据缺失。 ### 精确的场景断言 维护的 scenario schema `1.1` 声明了精确的预期 detection：规则、severity、evidence-event ID、group 值以及模拟 action。Schema `1.0` 仍然为了兼容性而保留可读性，但 `doctor` 会拒绝来自受维护目录的旧版场景。 ### Runtime 与 schema 保持一致 CI 会针对 Draft 2020-12 JSON Schema 验证实际的 scenario、event、report、manifest 和 ledger 实例。Runtime 验证、schema 验证、bundle 验证和代码库审计均使用相同的合约词汇表。 ## 证据身份层级 ``` input bytes └── run ID └── semantic execution plan └── per-rule execution traces └── ordered detections └── expectation verdict └── stage ledger root └── artifact hashes └── bundle ID ``` 只有当这些身份相互匹配时，一个 bundle 才能在内部保持一致。验证器会拒绝普通的文件篡改，以及那些 report、trace、ledger、summary、action 或 manifest 之间相互矛盾的重新哈希 bundle。 ## 包含的实验 | 场景 | 角色 | 精确的预期结果 | | --- | --- | --- | | [网络扫描](scenarios/network-scan) | 正相关对照 | 一个由 `net-001` 到 `net-005` 支持的高危 detection | | [特权组更改](scenarios/privileged-group-change) | 正向嵌套字段对照 | 一个由 `iam-002` 支持的严重 detection | | [失败的认证突发](scenarios/failed-authentication-burst) | 重复 window 对照 | 两个具有非重叠 evidence window 的中危 detection | | [经批准的特权维护](scenarios/benign-privileged-change) | 负向对照 | 零检测，并保留零结果的规则 trace | 每一个受维护的场景都包含合成的遥测数据、精确的授权边界、可检查的规则、精确的 detection contract，以及可重复验证的 bundle 生成过程。 ## 离线遥测适配器 ``` soc-replay adapters soc-replay normalize \ --adapter suricata-eve \ examples/adapters/suricata-eve.jsonl \ build/suricata-normalized.jsonl ``` 全局 adapter 注册表在启动后即被冻结。Suricata adapter 会消费已存储的 `alert` 和 `flow` 记录，通过公共 model 验证每一个发出的事件，报告被跳过的记录，进行原子写入，并发出确定性的输出 hash。它不包含任何传感器连接或凭据。 ## 物理平台  | 层级 | 代表性组件 | 角色 | | --- | --- | --- | | 安全计算 | 配备 Qubes OS 的 Dell PowerEdge R710 | 隔离的管理和实验域 | | 存储与虚拟化 | 配备 Proxmox VE 的 EqualLogic/Avid 平台 | 基于存储的工作负载、快照和恢复 | | 网络强制执行 | Dell X1052P 和 Cisco ASA 设备 | VLAN 分段和受控的跨区域路径 | | 检测与分析 | 位于专用 SOC 节点上的 SELKS/Suricata | 网络证据和分析师工作流 | | 恢复 | OpenGear 控制台和 KVM 路径 | 在正常网络不可用时提供带外访问 | 照片证明了安装。配置证明了预期策略。重放 bundle 证明了确定性的规则行为。经过测量的实验记录证明了端到端的平台行为。 ## 命令接口 ``` soc-replay validate soc-replay explain [--json] soc-replay run --output soc-replay verify soc-replay verify-bundle soc-replay catalog [--json] soc-replay adapters [--json] soc-replay normalize --adapter soc-replay graph --format text|json|mermaid soc-replay doctor [--json] ``` `doctor` 审计 pipeline、contract 版本、注册表以及受维护 scenario 的成熟度。`explain` 展示已编译的 selector 计划和观察到的执行计数。`graph` 展示阶段连线，而不是将架构隐式化。 ## 代码库架构 ``` SOC_Replay/ ├── src/soc_replay/ │ ├── contracts.py # shared schema and pipeline vocabulary │ ├── immutability.py # recursive freeze boundary │ ├── model_common.py # shared validation vocabulary │ ├── event_models.py # events, conditions, aggregates, rules │ ├── scenario_models.py # exact expectations and scenarios │ ├── result_models.py # detections and verification records │ ├── compiler.py # executable plans and semantic fingerprints │ ├── indexing.py # immutable composite candidate routing │ ├── correlation.py # detections and per-rule execution traces │ ├── pipeline.py # five-stage orchestration │ ├── ledger.py # strict deterministic hash chain │ ├── report_render.py # JSON and analyst-readable rendering │ ├── bundle.py # manifests and internal-consistency verification │ ├── report.py # stable reporting façade │ ├── adapters/ # frozen offline normalization registry │ └── cli.py # operational command surface ├── scenarios/ # exact positive, repeated-window, and negative controls ├── schemas/ # event, scenario, report, manifest, and ledger contracts ├── tests/ # behavior, corruption, immutability, schema, and CLI tests ├── tools/ # contract, determinism, and repository auditors ├── assets/ # physical build evidence └── docs/ # architecture, operations, decisions, and threat model ``` ## 质量门禁 ``` python -m pip install -e ".[dev]" ruff check src tests tools mypy python -m compileall -q src tests tools coverage run -m unittest discover -s tests -v coverage report soc-replay doctor python tools/validate_contracts.py python tools/verify_deterministic_bundles.py python tools/verify_repository.py python -m pip wheel . --no-deps -w dist ``` 该门禁强制执行严格的类型检查、lint、编译、至少 90% 的分支覆盖率、精确的 scenario 验证、真实的 schema-instance 验证、可重复的确定性 bundle 生成、严格的 ledger 有效性、深度不可变性测试、代码库不变性、无实时 I/O 导入以及 wheel 构建。 ## 文档 从以下开始： - [文档地图](docs/README.md) - [系统架构](docs/01-Architecture.md) - [重放引擎](docs/11-Replay-Engine.md) - [实现状态](docs/14-Implementation-State.md) - [工程评审](docs/16-Engineering-Review.md) - [架构决策](docs/17-Architecture-Decisions.md) - [证据包](docs/18-Evidence-Bundles.md) - [执行核心](docs/22-Execution-Core.md) - [执行账本](docs/23-Execution-Ledger.md) - [合约验证](docs/24-Contract-Validation.md) 受版本控制的 `docs/` 目录是权威来源。位于 `docs/wiki/` 下的 Wiki 副本是次要的，绝不能取代 implementation-state 记录或经过测量的证据。 ## 范围与非声明 SOC_Replay 是一个个人运营的防御性研究和演示环境。它不会生成流量、部署 payload、绕过控制、修改账户、运营基础设施或执行 response 命令。 执行 ledger 和 bundle manifest 提供了相对于其 hash 的防篡改证据。它们**并不**能确立作者身份、可信时间、外部监管链，也不能证明遥测数据源自实时的生产系统。 ## 当前状态 **Version:** 3.1.0 **物理平台：** 已安装并记录 **执行引擎：** 深度不可变、已编译、复合索引、已记录 trace 并已打包 **执行身份：** 完整的语义计划指纹，加上严格的五阶段 hash 账本 **实验证据：** 四份精确的确定性 contract，包含一个零检测对照 **Schema 保证：** 作为真实的 Draft 2020-12 实例验证的受维护输入和生成的输出 **Adapter 接口：** 已冻结、离线、经过脱敏处理的 Suricata EVE 标准化 **质量门禁：** 42 项测试，93% 的分支覆盖率，严格的类型检查，contract 审计，确定性审计以及 wheel 构建 **实时响应：** 刻意排除在该包之外

标签：Python, SIEM/IDS, 安全遥测, 插件系统, 无后门, 网络靶场, 逆向工具