cxm947 / FakeLiang

攻击图自动验证 Agent 
 沿图推进，逐步验证，让每个结论都有据可查。 
 MulVAL / JSON 攻击图 · 技能卡驱动 · 多 Agent 协作 · 调用证据落盘
 🧭 项目简介  · 
 🚀 快速开始  · 
 🧾 运行产物  · 
 🧪 离线检查  · 
 📚 文档导航 
---
## 🧭 FakeLiang 是什么？
FakeLiang 读入一张**已有攻击图**（MulVAL TXT 或已编译 JSON）、资产信息与主机-IP 映射表，按技能卡驱动大模型，在靶场上逐节点验证图中的路径：**先做前期验证，再执行利用，最后核对产出事实**，全程保存可复核的调用记录。
当前聚焦于确定性攻击图的路径验证。结论以本轮证据为准：命令是否执行完毕、模型报告了什么、节点事实是否成立、整图是否通过，分别按各自的判据解释。
| 核心能力 | 具体做什么 |
| :--- | :--- |
| 🗺️ **图驱动推进** | 从图中的节点、依赖与目标事实出发，结合已有结果安排下一步 |
| 🧩 **技能卡驱动** | 每张卡提供适用条件、输入、操作知识与判据，供执行过程使用 |
| 🤝 **多 Agent 协作** | 规划、执行、核验各有职责，运行时负责依赖、会话和调用记录 |
| 🧾 **证据可追溯** | 保存调用参数、标准输出、错误输出与模型转录，支持逐步复核 |
## 🔄 三个 Agent，怎样协作？
**攻击图与映射 → 规划节点 → 前期验证 → 执行 → 事实核验 → 登记收获 → 下一节点**
| 角色 | 职责 |
| :--- | :--- |
| 🗺️ **Planner · 规划** | 读取图、已有结果与上一节点状态，选择下一节点；运行时核对依赖条件 |
| ⚙️ **Executor · 执行** | 按技能卡完成节点任务，逐步提交动作，并记录每次调用的回执 |
| 🔍 **Verifier · 核验** | 核对本轮调用证据、前置事实与待产出事实，分别保留模型判断和机器判据 |
遇到阻断、未满足或不确定的结果时，按实际状态记录。调用完成本身不等于节点已被证明，历史运行通过也不自动成为当前修订的验收结论。
## 🧰 运行前需要准备什么？
| 项目 | 要求 |
| :--- | :--- |
| **控制端** | Windows + CPython 3.12；发布验收环境为 Windows x64 / Python 3.12 |
| **执行端** | 一台可 SSH 的 Kali，且 Metasploit RPC 可达 |
| **靶场与输入** | 主机、路由、资产信息与主机-IP 映射需和攻击图一致 |
| **模型服务** | OpenAI 兼容端点与自己的 API key |
| **图形输出** | 默认输出 JSON、DOT 与 PDF；PDF 需要 Graphviz。使用 `--json-only` 可跳过 PDF，仍保留 JSON / DOT |
| **离线检查** | Git 用于核对文件地图，测试依赖随 `requirements.txt` 安装 |
`pyproject.toml` 中的 `>=3.10` 是包元数据下限；本项目的发布验收口径仍是 **Python 3.12 / Windows**。
## 🚀 快速开始
### 1 · 获取项目并安装
在 PowerShell 中执行：
 [code] 
`requirements.txt` 包含运行、靶场和离线验收的全部直接依赖。`-e .` 安装本项目自身，`agv-project`、`agv-visualize` 与 `python -m agents.*` 等入口由它提供。
### 2 · 准备模型与图输入
模型 key 默认从 `AGV_MODEL_API_KEY` 读取，也可用 `--model-api-key-env` 指定其他变量名：
 [code] 
示例使用仓库自带的 Hongri7 输入：
| 输入 | 文件 |
| :--- | :--- |
| 攻击图 | `Hongri7_v2.txt` |
| 资产信息 | `assets.json` |
| 主机-IP 映射 | `host_ip_map.csv` |
实际运行前，按自己的部署核对这三份输入。凭据文件与私有材料目录放在仓库外；供给方式见凭据说明。
### 3 · 编译预览与运行
图编译可单独用于预览；整图入口也支持直接读取 TXT 并现场编译，无需先手动编译。
 [code] 
将示例中的 Kali 地址、密码、RPC 信息和模型端点替换为本轮配置。完整参数与其他入口见 scripts/README.md。
## 🧾 跑完以后，看哪些结果？
运行结果保存在 `--run-root` 指定的目录。通常先看整轮摘要，再沿节点和调用记录核对证据。
| 产物 | 用途 |
| :--- | :--- |
| `plan_result.json` | 查看节点状态、阻断与未尝试项、终点事实和整轮判定 |
| `walk.txt` | 阅读按步骤整理的运行过程 |
| `planner.jsonl` | 追溯规划选择与规划调用记录 |
| `model_outputs.md` | 查看脱敏后的逐节点模型转录 |
| 节点目录中的 `calls/ /` | 核对该次调用的 `call.json`、`stdout.txt` 与 `stderr.txt` |
| 节点目录中的 `events.jsonl` | 追溯节点事件 |
| `harvest.jsonl` | 查看会话、凭据引用与产物的统一收获记录 |
判读结果时，将**执行回执、模型结论、事实证据与整图判定**分别核对。
## 🧪 离线检查
在仓库根目录执行：
 [code] 
`scripts/ci.py` 包含三项检查：**测试、技能卡检查、文件地图检查**，均不连接靶场、不调用模型。
离线预览装配好的提示词：
 [code] 
## 📚 按任务找到入口
| 你想做什么 | 阅读入口 |
| :--- | :--- |
| 了解参数、整图运行与各类命令 | 脚本说明 |
| 运行单个节点或单张技能卡 | `run_node.py` · `run_lean_task.py` |
| 管理会话与回收资源 | `session_manager.py` · `reclaim.py` |
| 阅读日志与模型转录 | `journal.py` · `node_transcript.py` |
| 了解现行说明、设计和历史记录 | 产品文档导航 |
| 查阅技能卡约定 | 技能卡说明 · 技能卡目录 |
| 查文件职责或参与修改 | 文件地图 · 贡献约定 |
### 🗂️ 目录速览
| 目录 | 内容 |
| :--- | :--- |
| `src/` | 图编译、运行层、Planner / Executor / Verifier、会话与证据 |
| `skills/` | 技能卡正文、机器描述与随卡资源 |
| `scripts/` | 命令行入口与离线检查 |
|