guatxlabs/forge

Plume **观察**（负责记录的羽笔，蓝队）。Forge **打击** — 并 **淬炼** Plume 的 防御（紫队循环）。Forge 编排攻击模块（侦擦 → 枚举 → exploit），其中 **每个动作都会经过故障关闭式 ROE 门控**，并被记录在 **追加式、防篡改的交战 账本** 中。默认情况下，Forge 是 **惰性的**：在操作员有意识地 解锁每一层之前，无法触发任何动作。 ## 安全至上 — 4 层门控（`forge/roe.py`） 必须全部通过才能执行 LIVE（实战）动作。否则：`DRY_RUN`（模拟）或 `VETO`（硬拒绝）。 | 层 | 问题 | 失败 → | |---|---|---| | 1 — 解锁？ | 是否已显式解锁交战 (`--arm`)？ | `DRY_RUN` | | 2 — 范围？ | 目标 ∈ `in_scope` 且 ∉ `out_scope`？（**故障关闭**：`in_scope` 为空 = 什么也不做） | `VETO` | | 3 — 能力？ | exploit/破坏性 ⇒ 是否有显式的 `allow_exploit`/`allow_destructive`？ | `VETO` | | 4 — 批准？ | 动作是否已批准 (`--approve`)，或处于 `auto` 模式？ | `DRY_RUN` | `VETO`（层 2/3）**绝不**会被模拟或触发。任何评估错误 ⇒ `VETO`（故障关闭）。 ## 安装 ``` pip install -e . # met l'exécutable `forge` sur le PATH (forge = forge.cli:main) forge doctor # diagnostic : modules opérationnels + outil/service attendu par module ``` 无需安装，一切也可以通过 `python3 -m forge.cli ` 访问。 ## 快速开始 ``` # 端到端演示 — 无真实目标，无网络 I/O forge demo # ou: python3 -m forge.cli demo # 完整套件 (stdlib，零网络)：Python unittest + 控制台的 cargo test make test # = python3 -m unittest discover -s tests -t . + (cd console && cargo test) python3 -m unittest discover -s tests -t . # Python seul (260 tests) # 检查目标隶属关系 forge scope-check app.exemple.test --scope scope.json # 计划 (展示每个动作的 ROE 判定，不发射) forge plan --scope scope.json --actions actions.json # 执行 — 默认 INERTE；必须武装并获得批准才能发射 forge run --scope scope.json --actions actions.json \ --ledger engagements/e1.jsonl --report rapport.md # tout en DRY_RUN forge run --scope scope.json --actions actions.json \ --arm --approve demo.fingerprint:app.test --ledger engagements/e1.jsonl # 交战完整性 forge ledger verify --ledger engagements/e1.jsonl ``` 复制 `scope.example.json` → `scope.json` 并**在获得书面授权的情况下**填写 `in_scope`。 `scope.json`、`*.key`、`*.jsonl` 均被 gitignore（包含密钥 / 交战状态）。 ### 即时演示 — 1 条命令填充控制台（离线） [`examples/reference-engagement/`](examples/reference-engagement/) 中提供了一个**合成参考交战** （保留 `.example` 主机，文档 IP — **无真实目标，无真实 SOC**）。它会立即 填充 Findings / Coverage / Purple / Runs 标签页： ``` make demo # amorce la base démo + lance la console peuplée -> http://127.0.0.1:7100 make demo-purple # idem + stub mock-Plume (DEMO FIXTURE) -> matrice détecté/raté/MTTD (7 tirés, 4 détectés, 3 ratés) ``` `make demo` 会运行 `forge seed-demo --dir examples/reference-engagement`，它会**将 夹具直接摄入 SQLite**（幂等，无网络，仅触及演示 活动 `acme-lab`）。相关的商业详细报告： [`examples/reference-engagement/REFERENCE_ENGAGEMENT.md`](examples/reference-engagement/REFERENCE_ENGAGEMENT.md). ## Rust 控制台（`console/` — 存储 + 紫队循环） Plume 列的最小化分支（axum + rusqlite，单一二进制文件）：RED 模型存储 （`finding`/`runrecord`）、API，以及 **紫队交汇点**（`POST /api/ingest` 接收 来自 Python 引擎的 findings + ATT&CK 运行记录；Plume 随后通过 `mitre` 字段进行关联）。 ``` cd console && cargo build --release # compile offline depuis le cache cargo # (可选) 启用操作员 auth：密码的 argon2id hash，绝不明文 HASH=$(./target/release/forge hashpw 'mon-mot-de-passe') FORGE_CONSOLE_TOKEN=$(openssl rand -hex 16) \ FORGE_CONSOLE_USER=forge FORGE_CONSOLE_PASS_HASH="$HASH" \ ./target/release/forge # http://127.0.0.1:7100 (sans PASS_HASH = dev localhost ouvert) # 引擎端：向控制台发送 campaign python3 -m forge.cli campaign --scope scope.json --targets t.json --campaign op1 \ --console http://127.0.0.1:7100 --console-token "$FORGE_CONSOLE_TOKEN" ``` **Auth/RBAC**（Plume 的 `auth_guard`/`host_guard` 模型）：`/health` 开放；所有其他 路由受限于 反 DNS 重绑定 **host-guard**（`Host` 在白名单中 → 否则返回 `421`），以及 (b) 如果设置了 `FORGE_CONSOLE_PASS_HASH`，则受限于 **auth-guard** — **Basic**（操作员=查看者，读取）或 **Bearer token**（代理/管理员=写入）。无哈希 → 开放式 localhost 开发模式（写入 仍受 token 门控）。通过 `forge hashpw '...'` 设置 **argon2id** 密码。 端点：`GET /health` · `POST /api/ingest` (token) · `GET /api/findings` · `GET /api/runrecords` · `GET /api/coverage` (ATT&CK 汇总) · **`GET /api/query?q=...`** (soql) · **`/api/panels`** (GET 列表 · POST 创建 [token] · DELETE [token] · `GET /api/panels/:id/data`) · `GET /`（操作员深色控制台， 原生 JS：soql 搜索栏 + 表格/条形/统计形式的 **面板仪表板**）。 存储层去重（`UNIQUE(campaign,target,title)`）。绑定 127.0.0.1 ；完整的 auth/RBAC = 加固。 **soql（类 SPL 查询语言，从 Plume 移植）** — 查询 `finding`/`runrecord`， 编译为 **只读 SQL**（字段列入白名单，值绑定参数，单个 SELECT，设限 LIMIT，`SQLITE_OPEN_READ_ONLY` 连接）。示例： ``` search severity=HIGH | fields target,title,mitre search | stats count by severity | sort -count search title~Origine runs | stats count by mitre ``` 字段不在白名单中 → `400`（防注入）。返回编译后的 SQL（透明度）。 ### 控制台快速开始（≈5 分钟） ``` # 1) 构建 binary (离线，从 cargo 缓存) cd console && cargo build --release && cd .. # 2) 启动控制台 (开发：localhost 开放，写入受 token 保护) FORGE_CONSOLE_TOKEN=$(openssl rand -hex 16) ./console/target/release/forge & # -> http://127.0.0.1:7100 (暗色操作员 UI + API) # 3) 在 UI 端填充模块目录 forge modules --json # liste les 14 modules (kind, mitre, dispo) # 4) 摄取演示 campaign (零网络，合成 finding) FORGE_CONSOLE_URL=http://127.0.0.1:7100 FORGE_CONSOLE_TOKEN=$FORGE_CONSOLE_TOKEN \ python3 demo_ingest.py # FIRE demo.fingerprint -> POST /api/ingest ``` ## 连接器（由 Forge 驱动的标准渗透测试工具） Forge 本身不增加进攻能力：两个连接器**驱动**操作员 已经在使用的标准渗透测试工具，并在相同的 ROE 门控后将其结果 **映射**为 Findings。两者都在**触发时**探测各自的服务（绝不在 目录中），如果服务无法访问则自动关闭。 | 模块 | 驱动工具 | 环境变量（默认值） | |---|---|---| | `msf.module` | **msfrpcd** (RPC msgpack) — 启动操作员选择的 MSF 模块；Forge 不生成任何 payload | `MSF_RPC_HOST` (127.0.0.1) · `MSF_RPC_PORT` (55553) · `MSF_RPC_USER` (msf) · `MSF_RPC_PASS` · `MSF_RPC_SSL` (true) · `MSF_RPC_TOKEN` (永久 token，可选) | | `burp.scan` | **REST API Burp Suite** Pro/Enterprise — 启动范围内扫描，拉取 issues | `BURP_API_URL` (http://127.0.0.1:1337) · `BURP_API_KEY` | 治理：`msf.module` 声明 `exploit=True`（故障安全 → 引擎要求 `allow_exploit`）； `burp.scan` 保持 `exploit=False` 但发出 `reported_by_tool`（绝不返回 `vulnerable` — 如同 nuclei， 在没有可利用性证据的情况下绝不超配）。`forge doctor` 会指示哪些是可访问的。 ## 架构（简述） ``` cerveau (Claude / secpipe planner) │ propose des Actions (kind, target, exploit?, destructive?) ▼ Engine ──► gate ROE ──► VETO | DRY_RUN | FIRE ──► Ledger (append-time, hash-chain + HMAC) │ │ │ ▼ (FIRE seulement) └──► module.fire() ──► Findings ──► report.py (+ section anti-masquage) ▲ modules = OUTILS AUTONOMES orchestrés (toolkit/*.py, secpipe, évasion browser-automation) ``` - **核心** = `roe.py`（门控） + `ledger.py`（证明） + `engine.py` + `schema.py`。纯标准库。 - **模块** 保持独立（`Module` 仅执行 `dry()`→PoC 和 `fire()`→findings）。 - **紫队循环**：每个 finding 都包含 `mitre` (ATT&CK) 字段 = 关联键，用于验证 防御方（BAS）的检测情况。**检测源是一个可配置的插件** （Plume 只是一个预设 — CrowdSec、FortiGate、pfSense/OPNsense、Elastic/OpenSearch、文件、exec 均可在 无需代码的情况下接入）：参见 [`docs/DETECTION.md`](docs/DETECTION.md) 和 [`ARCHITECTURE.md`](ARCHITECTURE.md)。 ## 状态（v0.0.1 — 260 个测试通过，零网络） — **P1 + P2 已完成** | 层 | 状态 | |---|---| | 故障关闭 ROE 门控（4 层） | ✅ 已构建 + 已测试（10 个测试） | | 追加式防篡改账本（非对称 **Ed25519** + 外部验证，HMAC 备选） | ✅ 已构建 + 已测试（8 个测试） | | 引擎 + 防掩饰报告 + CLI | ✅ 已构建，端到端演示 OK | | 覆盖率安全规划器（基于付费类的 FLOOR） | ✅ 从 secpipe 移植 + 自测 | | 大脑（`Brain` 接口 + `HeuristicBrain`） | ✅ — Claude 编排器的切入点 | | 运行器（本地二进制文件或 docker，无需安装） | ✅ 从 secpipe 移植 | | 交战图（世界模型 主机→服务→findings） | ✅ 从 secpipe 移植 | | 处理程序：`recon.httpx`/`recon.nmap`/`web.nuclei`/`access_control.idor`/`origin.find` | ✅ — 已门控，若缺少工具则自动中立化 | | 规避：`evasion.xhr`/`evasion.turnstile`/`evasion.idor_intercept`（浏览器自动化） | ✅ — 触及 CF/WAF 目标，若服务不可达则自动关闭 | | 连接器：`msf.module` (msfrpcd) / `burp.scan` (REST API Burp) | ✅ — 驱动标准工具，在触发时探测，若服务不可达则自动关闭 | | 记忆：JSONL 存储 + 去重 (`forge/memory.py`) | ✅ — FAISS 后端 (YWH 工具包) 待接入 | | 紫队循环：ATT&CK 运行记录 + `forge campaign` | ✅ 已构建 + 已测试 | | **Rust 控制台** (`console/`，Plume 列的分支) | ✅ — 离线编译，ingest+coverage+PWA，Python↔Rust 集成已验证 | | **soql `finding`/`runrecord`** (`GET /api/query`，只读，防注入) + UI 搜索栏 | ✅ 从 Plume 移植，经过在线测试 | | **查询驱动的仪表板**（已保存的 soql 面板，表格/条形/统计可视化，写入受 token 门控） | ✅ 经过在线测试 | | **控制台 Auth/RBAC**（argon2id Basic=查看者 · Bearer=管理员 · 防重绑定 host-guard） | ✅ 从 Plume 移植，10/10 在线测试通过 | | **Ed25519 账本**（追加时非对称签名 + 通过公钥 `verify_external`） | ✅ 已测试 | | **主机外锚定**（`anchor.py`：`Anchor` 接口 + 共同签署见证人 + `reconcile`） | ✅ 已测试（检测到本地重签名的重写） | | **语义记忆**（标准库模糊匹配 `JaccardMemory` + 可选的 FAISS embeddings 桥接） | ✅ Jaccard 已测试，FAISS 优雅降级 | | **共享核心 `guatx-core`**（位于 `GUATX/core/` 的**公共中立** Rust crate；控制台依赖它） | ✅ 6 个 Rust 测试，移出私有库，控制台已重构 | | **首次部署向导**（自部署：**从浏览器**配置管理员/加密/检测源/操作员策略，自动禁用，零硬编码默认值） | ✅ — `GET /api/setup/state` · `POST /api/setup` | | **RBAC 管理员与连接器治理**（账户 `/api/users`，查看者/操作员/管理员；msf/burp 在触发时探测，`exploit` 故障安全，绝不超配） | ✅ — 经过在线测试 | | **基础设施无关检测源**（UI 中的可配置插件：Plume/CrowdSec/FortiGate/pfSense/OPNsense/Elastic/文件/exec，写密钥） | ✅ — 参见 `docs/DETECTION.md` | | **加密备份/恢复 + 迁移**（**始终加密**的归档 argon2id+XChaCha20，调度程序 + 异地，`migrate` DB+ledger+`.ed25519` 密钥） | ✅ — `/api/backup(/policy)` · `/api/restore` · `forge migrate` | | **静态加密 SQLCipher**（选配镜像 `--features encryption`，启动时 `PRAGMA key`） | ✅ 选配 — `capabilities.sqlcipher` 暴露给向导 | | Plume 迁移至 `guatx-core` + 远程见证签署人 (HTTP) | ⏳ 按需提供 | **模块**（节选；表格由 `forge modules --json` 生成） — 包含依赖项和状态的**最新完整目录 （31 个模块）**在 **[`docs/MODULES.md`](docs/MODULES.md)** 中： | kind | exploit | ATT&CK | description | |---|:---:|---|---| | `access_control.idor` | ✅ | T1190 | 针对双账户的有证据差分 IDOR/BOLA 预言机 (CWE-639)。 | | `auth.takeover` | ✅ | T1212 | 有证据的 ATO/身份验证绕过预言机 (whoami = 受害者身份，CWE-287/640)。 | | `burp.scan` | — | T1595.002 | 驱动 Burp Suite 的 REST API：范围内扫描 → issues → Findings。 | | `cors.credentials` | ✅ | T1539 | 有证据的 CORS 凭证预言机 (ACAO 反射源 + ACAC=true，CWE-942)。 | | `demo.fingerprint` | — | — | 演示流水线 (plan→ROE→dry/fire→finding→ledger)，零 I/O。 | | `evasion.idor_intercept` | ✅ | T1190 | 在传输中武装 IDOR 拦截（浏览器拦截-修改，CWE-639）。 | | `evasion.turnstile` | — | T1556 | 通过交互式 Turnstile（视觉点击操作系统）— 访问使能器。 | | `evasion.xhr` | — | T1190 | 通过浏览器会话观察 XHR 请求（WAF 绕过）。 | | `msf.module` | ✅ | T1210 | 驱动 msfrpcd：启动操作员选择的 MSF 模块。 | | `origin.find` | — | T1590.005 | CDN/WAF 背后的原始 IP (subfinder→DNS→drop-CF→验证 Host)。 | | `recon.httpx` | — | T1595 | HTTP 指纹识别（状态、标题、技术）。 | | `recon.nmap` | — | T1046 | 发现暴露的服务（nmap -sV，top 1000）。 | | `ssrf.callback` | ✅ | T1190 | 有证据的 SSRF 预言机（收集方接收到唯一 callback，CWE-918）。 | | `web.nuclei` | — | T1595.002 | 通过 nuclei 模板进行漏洞扫描（中危/高危/严重）。 | ## 生产环境部署（自部署） 完整手册：**[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)**。简而言之 — 构建上下文是 父目录 `GUATX/`（控制台在 `path` 中依赖同级的 `guatx-core`；已提交 `console/Cargo.lock` 以确保可重现的构建）： ``` cd GUATX/forge && cp scope.example.json scope.json # INERTE tant que in_scope vide ; éditer AVEC AUTORISATION cd .. && docker compose -f forge/docker-compose.yml up -d --build # console SEULE (loopback :7100, healthcheck GET /health) ``` 打开 `http://127.0.0.1:7100` → **首次启动向导**将配置管理员（RBAC argon2id）、加密、 **你的基础设施的检测源**（FortiGate/pfSense/CrowdSec/Elastic/… — 参见 [`docs/DETECTION.md`](docs/DETECTION.md)， 无需代码的插件）以及操作员策略 — **没有任何硬编码内容**。可选服务 （浏览器/msf/burp）位于**配置文件**（`--profile browser`）之后，没有硬编码的 `depends_on` → 纯粹的 `up` = 仅控制台。**静态加密**（选配的 SQLCipher 镜像）和**预定的加密备份** （异地）：[`docs/MIGRATION.md`](docs/MIGRATION.md) · [`docs/BACKUP.md`](docs/BACKUP.md)。 ## 文档 **➡️ 完整且可导航的目录：[`docs/README.md`](docs/README.md)** — 所有 产品文档的集合（概述、架构、安装、配置、管理、 概念、CLI、HTTP API、安全性、故障排除）。关键页面： - [`docs/OVERVIEW.md`](docs/OVERVIEW.md) — **Forge 是什么**、价值、独立运行原理。 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — **它是如何构建的**（Python 引擎 + Rust 控制台 + SPA + 治理）。 - [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) — 环境变量和 `settings` 键的**完整参考**。 - [`docs/CLI.md`](docs/CLI.md) · [`docs/HTTP_API.md`](docs/HTTP_API.md) — CLI 和 HTTP API 参考。 - [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) — **离线端到端入门**（seed + mock-Plume）：安装 → 范围 → 控制台 → 紫队 → 报告 → 完整性。 - [`docs/PLAN.md`](docs/PLAN.md) — 定位、红/蓝/紫队、路线图排序及阻塞状态。 - [`docs/DETECTION.md`](docs/DETECTION.md) — **检测源 = 可配置插件**（无需代码即可接入任何蓝队基础设施：Plume/CrowdSec/FortiGate/pfSense/OPNsense/Elastic/文件/exec）+ `DetectionSource` 模型和 MITRE 映射。 - [`docs/PURPLE_PREREQS.md`](docs/PURPLE_PREREQS.md) — 用于连接紫队循环（核心壁垒）的 **Plume** 预设的先决条件 — `DETECTION.md` 的一个特例。 - [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — **端到端自部署手册**：构建/运行（最小·完整 · Docker · compose · 原生/systemd · `encryption` SQLCipher 镜像），**首次启动向导**（管理员 · 加密 · 检测源 · 操作员策略 — 无硬编码）、迁移与**加密备份**（调度/异地）、`guatx-core` 构建上下文、`/health` 存活检测。包括测量的足迹 + 矩阵（Docker / k8s / host / venv）。 - [`docs/PLATFORMS.md`](docs/PLATFORMS.md) — **操作系统支持矩阵**（Linux 为主 · macOS 完全支持 · Windows 尽力支持）：跨平台适用的部分 vs 仅限 Unix 的能力（通过 `setsid`/`killpg` 杀死 C2 运行的子树），以及各操作系统的配置/数据/临时目录的解析。 - [`docs/MIGRATION.md`](docs/MIGRATION.md) — 将现有安装（DB + ledger + `.ed25519` 密钥）迁移至 Docker/其他目标；可选的 SQLCipher 静态加密。 - [`docs/BACKUP.md`](docs/BACKUP.md) — **始终加密**（argon2id + XChaCha20-Poly1305）的备份/恢复，调度 + **异地**发送。 ## 许可证与模型 Forge 遵循**开源核心**模型。 - **社区版 — [AGPL-3.0-or-later](LICENSE)**：**完整的治理核心**是开源、免费 且可自托管的。故障关闭式 ROE 范围守卫、防篡改的 Ed25519 授权账本、 面向证据的预言机、可扩展的技术注册表 + 所有技术类别、受控的轻量级 C2 运行、 控制台（UI + 向导 + RBAC 管理员/操作员/查看者）、连接器/编排（nuclei/msf/ burp/…）、基础设施无关检测、加密备份/恢复以及紫队循环 — **独立运行或在小团队中 运行 Forge 所需的一切**。由于这是 AGPL，任何 网络部署都必须向其用户提供相应的源代码。 - **企业版 — 独立的商业许可证**：**规模化 / 团队 / 合规**层 — 多租户/MSSP（按租户进行加密隔离）、SSO/SCIM、高级可组合 RBAC 与按交战授权、 HA/集群/分布式存储（Postgres）、合规（SOC2/ISO 证据、legal-hold/WORM 保留， KMS/HSM 密钥）、高级连接器以及支持/SLA。 **原则**：**治理核心 + 加密审计保持开放且可验证** — 这是 产品的全部信誉。只有**规模化/团队/合规**层是商业化的，并构建为 **可分离模块**。边界详情：**[`COMMUNITY_VS_ENTERPRISE.md`](COMMUNITY_VS_ENTERPRISE.md)**。

标签：Python, 可视化界面, 密码管理, 攻击模拟, 数据展示, 无后门, 红队, 逆向工具, 驱动签名利用