GnomeMan4201/shenron

# SHENRON **可观测的对抗行为，而非可移植的对抗程序。** 一个基于Python的防御性对抗遥测仿真平台。SHENRON能在50个技术类别中生成结构化合成遥测数据，通过名为bananaTREE的四阶段活动模型组织：观察（OBSERVE）、模拟（SIMULATE）、执行（EXECUTE）、适应（ADAPT）。 每个制品都带有明确的安全契约。无实际网络调用，无子进程生成，无可执行负载，无向日志目录外写入文件。 ## 安全边界 SHENRON不包含： - 可执行负载或shellcode - 真实网络连接或socket绑定 - 子进程生成或shell命令执行 - 向其自身日志目录外进行真实文件写入 - 任何形式的漏洞利用代码 这是架构约束，而非免责声明。安全验证器会扫描每个制品并标记违规。单次违规将产生 `VERDICT: UNSAFE`，无论覆盖率评分如何。 ## 快速开始 ``` git clone https://github.com/GnomeMan4201/shenron cd shenron python3 -m pytest tests/ -q python3 shenron.py --run all --dry-run python3 shenron.py --validate latest ``` ## 可复现演示 一条命令生成完整的制品包： ``` python3 shenron.py --release-demo ``` 输出 — `release/shenron-v0.3.3-demo/`： ``` shenron_demo_run.jsonl 40 synthetic telemetry events shenron_demo_report.md human-readable run report safety_verification.md safety contract field-by-field verification navigator_layer.json ATT&CK Navigator import layer (synthetic) shenron_demo_run_ecs.json ECS-formatted events shenron_demo_run_ecs_bulk.ndjson Elastic bulk API format shenron_demo_run_splunk_hec.json Splunk HEC format narrative.md tactic profile narrative charts/ 5 dark-mode PNGs MANIFEST.md bundle index with import commands ``` 每条记录都包含： ``` "safety": { "simulation_only": true, "executable": false, "payload_present": false, "portable_adversarial_procedure": false, "network_connection": false, "subprocess_spawned": false, "real_file_written": false, "shell_invoked": false } ``` ## 安全验证 检查任何JSONL制品的安全契约： ``` python3 shenron.py --verify-safety artifacts/demo/shenron_demo_run.jsonl ``` ``` [RECORDS] 40 executable PASS network_connection PASS payload_present PASS portable_adversarial_procedure PASS real_file_written PASS shell_invoked PASS simulation_only PASS subprocess_spawned PASS [VERDICT] PASS ``` ## bananaTREE活动模型 | 阶段 | 意图 | |------|------| | **观察** | 映射对抗信号表面 — C2、熵、身份模式 | | **模拟** | 为检测器训练生成合成遥测数据 | | **执行** | 运行仿真层，生成JSONL制品时间线 | | **适应** | 评估检测覆盖率，识别差距 | 运行内置场景： ``` python3 shenron.py --scenarios python3 shenron.py --scenario apt_kill_chain --dry-run python3 shenron.py --scenario persistence_runbook --dry-run ``` 内置场景：`basic_c2_persistence`、`recon_to_exfil`、`persistence_runbook`、`evasion_stress_test`、`apt_kill_chain`。 ## 检测器验证 ``` python3 shenron.py --validate latest ``` ``` [VALIDATION] c2_shape_detection_test [EXPECTED] 31 [OBSERVED] 31 [COVERAGE] 100.0% [SAFETY FAIL] 0 [VERDICT] PASS ``` 通过需要 ≥80% 覆盖率且零安全违规。 ## 运行比较 比较两次运行以跟踪检测覆盖率随时间的变化： ``` python3 shenron.py --compare python3 shenron.py --compare --narrate python3 shenron.py --compare --navigator-out reports/gap_layer.json ``` `--narrate` 标志生成分析师语言的防御叙述，指出两次运行间缺失的具体战术族，为每个差距提供分析师关注的语言，并建议接下来应运行哪些场景。 示例输出 — `apt_kill_chain` 对比 `persistence_runbook`： ``` [NARRATIVE] apt_kill_chain → persistence_runbook Coverage gap families (4): ✗ Command-and-Control ✗ Defense Evasion ✗ Lateral Movement ✗ Discovery Primary concern: If C2-shaped telemetry is not in your validation set, your detectors have not been tested against the phase where most APT campaigns are first visible — initial callback after compromise. ``` ## 覆盖率假设审计 定义您认为您的检测栈覆盖了什么，然后根据合成遥测数据对其进行审计： ``` # 创建假设文件 cat > assumptions/my_assumption.yaml << 'EOF' name: persistence_coverage_assumption description: We can detect persistence-shaped adversarial telemetry claims: - "We can observe persistence-shaped telemetry" - "We can detect suspicious scheduled task behavior" expected_techniques: - T1053.005 - T1543.003 - T1547.001 expected_signals: - scheduled_task_creation - service_install_signal expected_phases: - EXECUTE EOF # 审计它 python3 shenron.py --assumption assumptions/my_assumption.yaml \ --events artifacts/demo/shenron_demo_run.jsonl ``` SHENRON根据制品证据对每个声明进行评分，识别缺失的技术描述符，并生成一份带有“这证明了什么/这没有证明什么”章节的markdown报告。 示例输出： ``` [ASSUMPTION] persistence_coverage_assumption [RECORDS] 40 Claims 0 supported 0 partial 2 unsupported Techniques 3 observed 3 missing Signals 2 observed 3 missing [COVERAGE] 38.9% [VERDICT] FAIL ``` 完整示例文件见 `assumptions/examples/`。 ## 覆盖率历史 跟踪您所有运行中的技术覆盖率漂移： ``` python3 shenron.py --coverage-history --out-dir reports/history python3 shenron.py --coverage-history --history-campaign c2_shape_detection_test ``` 输出： - `coverage_history.md` — 每个活动的趋势表、漂移事件、技术集 - `coverage_history.json` — 机器可读的快照索引 - `coverage_history_trend.png` — 技术数量随时间变化的图表 通过8个活动中的256次运行，SHENRON可以显示您的检测信号词汇量在反复的验证运行中是扩展、收缩还是保持一致。 ## 格式导出 将合成事件导出为您的SIEM可以摄入的格式： ``` # Elastic Common Schema python3 shenron.py --export-format ecs \ --events artifacts/demo/shenron_demo_run.jsonl \ --out-dir artifacts/demo # Splunk HEC python3 shenron.py --export-format splunk \ --events artifacts/demo/shenron_demo_run.jsonl \ --out-dir artifacts/demo ``` Elastic导入： ``` curl -X POST 'http://localhost:9200/_bulk' \ -H 'Content-Type: application/x-ndjson' \ --data-binary @artifacts/demo/shenron_demo_run_ecs_bulk.ndjson ``` 所有ECS事件都携带 `event.dataset: shenron.synthetic`、`labels.simulation_only: true`，以及完整安全契约在 `labels.*` 字段中。每个事件的 `message` 字段都包含 `[SHENRON SYNTHETIC]`。这些不是真实事件。 ## 变体变异 测试您的分析流程对不完整、有噪声或错误标记的遥测数据是否脆弱： ``` python3 shenron.py --mutate \ --events artifacts/demo/shenron_demo_run.jsonl \ --out-dir artifacts/mutations # 运行特定变异类型 python3 shenron.py --mutate \ --mutation-types field_drop,timing_jitter,label_ambiguity \ --events artifacts/demo/shenron_demo_run.jsonl ``` 可用的变异类型： | 类型 | 功能 | 测试目标 | |------|------|----------| | `field_drop` | 移除非关键字段 | 可选字段依赖 | | `timing_jitter` | 添加随机时间戳偏移 | 对时序敏感的关联规则 | | `label_ambiguity` | 用通用名称替换特定信号 | 信号特异性要求 | | `signal_density_high` | 3倍记录复制 | 高容量突发处理 | | `signal_density_low` | 丢弃50%的记录 | 稀疏遥测检测 | | `phase_imbalance` | 将所有记录重新标记为单一阶段 | 阶段感知分析的脆弱性 | | `technique_noise` | 添加不相关的技术ID | 基于MITRE关联的鲁棒性 | 所有安全变异类型都保留 `simulation_only: true`。`missing_safety_fields` 类型（仅限选择加入）会故意违反安全契约 — 仅与 `--verify-safety` 一起使用以测试契约验证。 变异后： ``` python3 shenron.py --verify-safety artifacts/mutations/mutation_field_drop.jsonl ``` ## ATT&CK Navigator 导出 ``` python3 shenron.py --navigator latest python3 shenron.py --navigator --navigator-out reports/my_layer.json # 比较差异层 python3 shenron.py --compare --navigator-out reports/gap_layer.json ``` 在 https://mitre-attack.github.io/attack-navigator/ 导入 → 打开现有图层 → 上传文件。 Navigator 图层携带合成覆盖率元数据。它们代表来自合成遥测数据的MITRE风格描述符覆盖率 — 而非真实的ATT&CK验证。 ## 完整工作流 ``` # 1. 运行安全演示管道 python3 shenron.py --demo --charts --out-dir artifacts/demo # 2. 验证安全契约 python3 shenron.py --verify-safety artifacts/demo/shenron_demo_run.jsonl # 3. 导出为 SIEM 格式 python3 shenron.py --export-format ecs --events artifacts/demo/shenron_demo_run.jsonl # 4. 运行场景 python3 shenron.py --scenario apt_kill_chain --dry-run python3 shenron.py --scenario persistence_runbook --dry-run # 5. 比较并叙述 python3 shenron.py --compare --narrate \ --navigator-out reports/gap_layer.json # 6. 审计覆盖假设 python3 shenron.py --assumption assumptions/examples/persistence_coverage.yaml \ --events artifacts/demo/shenron_demo_run.jsonl # 7. 跟踪覆盖历史 python3 shenron.py --coverage-history --out-dir reports/history # 8. 生成变异变体 python3 shenron.py --mutate --events artifacts/demo/shenron_demo_run.jsonl # 9. 构建完整发布包 python3 shenron.py --release-demo ``` ## CLI参考 **演示和安全** ``` --demo Run safe 40-event demo pipeline --charts Generate charts from demo JSONL (use with --demo) --verify-safety [PATH] Verify safety contract on JSONL or 'latest' --out-dir DIR Output directory (default: artifacts/demo) --release-demo Build complete 9-file release artifact bundle ``` **场景和验证** ``` --scenario NAME Run a built-in or custom scenario --scenarios List available scenarios --run TARGET Run a layer, category, or 'all' --dry-run Validate without executing --validate [RUN_ID] Run detector validation --report-v2 [RUN_ID] Generate markdown report --include-validation Include validation results in report ``` **比较和分析** ``` --compare RUN_A RUN_B Diff two validation runs by run ID prefix --narrate Generate analyst narrative from --compare --navigator [RUN_ID] Export ATT&CK Navigator layer --navigator-out PATH Output path for Navigator JSON --assumption YAML_PATH Audit a coverage assumption file --events JSONL_PATH JSONL events file for --assumption or --export-format ``` **历史和变异** ``` --coverage-history Build coverage trend report from all timeline runs --history-campaign NAME Filter --coverage-history to a specific campaign --mutate Generate safe telemetry mutation variants --mutation-types TYPES Comma-separated mutation types (default: all safe) ``` **格式导出** ``` --export-format FORMAT Export events as ECS or Splunk HEC (ecs|splunk) ``` ## SHENRON不做什么 - 测试网络层控制 — 不进行真实的网络调用 - 验证EDR行为检测 — 不发生真实的进程执行 - 替代需要真实执行的对抗性仿真 - 证明检测规则在生产遥测数据上触发 - 测量内核级制品的检测 - 替代红队 SHENRON测试遥测管道层：日志记录、SIEM摄入、关联规则、分析师工作流和检测假设。它是对抗性仿真的补充，而非替代。 ## 测试 ``` python3 -m pytest tests/ -q ``` 283项测试。涵盖安全契约、格式适配器、假设审计、叙述引擎、覆盖率历史、变异引擎和验证评分。 ## 项目结构 ``` shenron.py CLI entrypoint core/ engine/ scenario_engine.py bananaTREE campaign runner layer_loader.py canonical layer discovery payload_registry.py layer execution registry reports/ evidence.py artifact loader, run parser model.py report dataclasses markdown.py markdown renderer validation/ coverage.py detection coverage dataclasses scorer.py validation scorer expectations.py expected detection loader safety/ contract.py shared safety contract — single source of truth compare.py run comparison engine navigator.py ATT&CK Navigator exporter narration/ engine.py deterministic analyst-language narrative generator assumption/ parser.py YAML assumption loader and validator evaluator.py claim scorer against JSONL artifact records reporter.py markdown + JSON report writer formats/ adapter.py ECS and Splunk HEC format adapters history/ tracker.py coverage trend tracking and drift detection mutation/ engine.py 7 safe telemetry mutation variant generators scripts/ generate_demo_artifacts.py safe 40-event JSONL generator generate_charts.py publication chart generator release_demo.py complete release bundle generator assumptions/examples/ example assumption YAML files scenarios/ custom scenario JSON files tests/ 283 tests ``` ## 版本 `v0.3.3` — 50个技术层 · 283项测试 · 零硬编码路径 · 通过判定 *gnomeman4201 / badBANANA研究集体*

标签：ATT&CK框架, Python框架, 事件生成, 合成数据生成, 多格式输出, 安全测试, 实验室模拟, 对抗模拟, 战役模型, 攻击性安全, 时序数据库, 红队研究, 网络安全, 逆向工具, 遥测模拟, 防御性安全, 隐私保护