SamTruss/Pathfinder-AI

# Pathfinder ## ⚠️ 仅限授权使用 — 请首先阅读本声明 Pathfinder 是一款攻击性安全研究软件。其设计旨在**规划和执行相关操作，如果在未获得明确书面许可测试的情况下对非您所有的系统执行这些操作，将属于违法行为。** **您只能在以下情况下使用 Pathfinder：** - 完全归您所有的系统，或 - 由您全权控制的隔离实验室环境，或 - 您已获得**明确的书面授权**（签署的交战规则、工作声明或同等文件）的第三方系统，且该授权涵盖特定的测试活动、范围和时间窗口。 **您不得使用 Pathfinder 进行以下操作：** - 在未事先获得系统所有者书面授权的情况下，测试、扫描、探测或尝试利用任何系统。 - 进行超出授权中定义的范围、方法或时间框架的测试。 - 处理、窃取或保留超出授权允许范围的第三方数据。 - 规避您所在管辖区或目标所在管辖区的任何法律、法规或合同义务。 作者及贡献者对滥用行为不承担任何责任。在未获得测试许可的系统上未经授权使用本软件，在大多数司法管辖区均属于刑事犯罪，包括违反英国的 **Computer Misuse Act 1990**、美国的 **Computer Fraud and Abuse Act** 以及其他地区的同等法规。**您需自行确保对 Pathfinder 的使用是合法且经过授权的。** 如果您不确定您的预期用途是否已获授权，**请勿运行本软件**，直到您收到系统所有者的书面确认，并在适当情况下咨询法律顾问。 有关漏洞披露政策，请参见 [`SECURITY.md`](SECURITY.md)；有关完整的研究伦理声明，请参见 [`docs/ethics.md`](docs/ethics.md)。 ## 当前状态 Pathfinder 目前处于活跃的 pre-alpha 开发阶段。截至 2026 年 5 月 9 日，该 框架已实现端到端运行：本地 LLM (Ollama) 负责对授权的 评估任务进行推理，ScopedPolicy 治理层通过 YAML 配置强制执行 交战范围，自定义 MCP 服务器在严格的参数允许列表下调用真实的 安全工具 (Nmap)。该框架 已在 localhost 上的端到端测试（耗时 115ms）中得到验证。 [路线图](docs/roadmap.md) 的 0-2 阶段已完成。实验室集成 （第 3 阶段）、完整的 PEER 编排（第 4 阶段）和定量评估 （第 5 阶段）将是接下来的工作。 ## 简介 Pathfinder 是基尔大学 一项正在进行的博士研究项目的工程产物，旨在研究代理式和生成式 AI 在自主 VAPT 中的应用。它既是一个**研究平台** —— 一个用于对攻击性安全任务中的代理行为进行实证研究的底层支撑 —— 也是 accompanying 系统综述和即将发表的出版物中描述的架构模式的**参考实现**。 该框架具有刻意的模块化特征，使得各个组件（规划器、推理器、工具包装器、内存后端、目标环境、评估工具）可以独立地进行替换、消融或插桩，以便于实验研究。 ### Pathfinder 是什么 - 一个用于在授权安全测试背景下研究代理式 AI 的研究框架。 - 一个实现了显式“观察–推理–决策–行动”循环的模块化代理架构。 - 一个用于在受控实验室环境中进行可重复、可插桩实验的平台。 ### Pathfinder 不是什么 - 一个交钥匙的“自主黑客”工具 —— 它需要专家监督、范围明确的实验室目标以及谨慎的配置。 - 人类渗透测试员的替代品 —— 其研究问题恰恰在于代理能走*多远*，而不是它们是否应该取代从业者。 - 生产就绪的攻击性工具 —— 这是研究级软件，带有研究级的注意事项。 ## 架构 Pathfinder 在两个层面上运行： **PEER 生命周期** — 评估工作流遵循 Plan–Enumerate–Exploit–Report（计划–枚举–利用–报告）结构，反映了实际 VAPT 任务的顺序阶段。 | 阶段 | 职责 | |-----------|-----------------------------------------------------------------------------------------------| | Plan | 定义范围、目标、约束、允许的操作以及交战规则。 | | Enumerate | 在授权范围内进行侦察和服务发现。 | | Exploit | 在策略强制执行和人工批准关卡下，安全地验证选定的弱点。 | | Report | 将证据转化为结构化的调查结果、修复建议和审计工件。 | **ORDA 控制循环** — 在每个 PEER 阶段中，代理运行一个“观察–推理–决策–行动”循环以驱动迭代级别的行为。循环的每个阶段都是一个可插拔的 Protocol；替换实现只需更改构造函数参数，而不是子类化。 围绕这些核心的是**治理层**（在每次工具调用前进行策略强制执行）、**telemetry**（结构化记录每次迭代）、**memory**（观察和决策历史）以及**工具集成**（通过 MCP 服务器集成外部安全工具）。 有关完整的架构 —— 包括 Protocol 定义、数据类型、循环执行模型和实现状态 —— 请参见 [`docs/architecture.md`](docs/architecture.md)。 ## 仓库状态 | 项目 | 状态 | |-------------------|------------------------------------------------------------------------| | 可见性 | **公开** — 在积极研究期间发布，以确保透明度和可重复性。 | | 稳定性 | Pre-alpha。接口不稳定，且会未经通知即更改。 | | 贡献 | 仅限邀请。参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 | | 路线图 | 分阶段构建计划。参见 [`docs/roadmap.md`](docs/roadmap.md)。 | | 架构 | PEER 生命周期 + ORDA 控制循环。参见 [`docs/architecture.md`](docs/architecture.md)。 | | 引用 | 参见 [`CITATION.cff`](CITATION.cff)。 | ## 快速入门 ### 前置条件 - **Python 3.11+**（在 3.14 上开发） - **uv** — 包管理器（[安装指南](https://docs.astral.sh/uv/getting-started/installation/)） - **Ollama** — 用于本地 LLM 推理（[ollama.com](https://ollama.com/)） — 从第 1 阶段起需要 - **Docker + Docker Compose** — 用于测试床环境 — 从第 3 阶段起需要 - 一个受控、隔离的实验室环境，用于单元测试之外的任何执行 - 适用情况下的 LLM 提供商凭据（通过环境变量配置；参见 `.env.example`） ### 安装说明 (预期) ``` git clone cd pathfinder-ai python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" cp .env.example .env # then edit with your provider keys and lab config ``` ### 运行测试套件 ``` pytest ``` 单元测试和集成测试默认设计为在不连接外部系统或 LLM API 的情况下运行。 ### 在实验室目标上运行代理 在 `labs/` 和 `configs/` 目录下将提供脚本化的实验室设置（隔离网络中的易受攻击目标）和示例任务配置。**请勿将代理指向您无法完全控制的环境之外的任何目标。** ## 项目结构 ``` Pathfinder-AI/ ├── pathfinder/ # Core Python package │ ├── core/ # ORDA control loop, Protocols, state, types, errors │ ├── agents/ # MechanicalObserver, OllamaReasonerDecider, MockActor │ ├── policy/ # NullPolicy, ScopedPolicy │ ├── prompts/ # PromptLoader for versioned Jinja2 templates │ ├── telemetry/ # JsonLinesTelemetry (hash-chained run logs) │ ├── tools/ # MCPActor (Model Context Protocol) │ ├── memory/ # Short- and long-term memory backends (planned) │ └── evaluation/ # Harnesses for quantitative experiments (planned) ├── scripts/ # Standalone executables │ └── mcp_servers/ # MCP servers Pathfinder communicates with │ └── nmap_mcp_server.py # Nmap MCP server (Phase 2) ├── prompts/ # Versioned prompt templates (v1/ live) ├── docs/ # Architecture, ethics, roadmap ├── tests/ # Unit and integration tests ├── .github/ # Issue/PR templates, CODEOWNERS ├── configs/ # Engagement and experiment configs (planned) ├── labs/ # Lab target definitions (planned) ├── README.md ├── SECURITY.md ├── CONTRIBUTING.md ├── CONTRIBUTORS.md ├── CITATION.cff ├── LICENSE ├── LOCAL_SETUP.md ├── pyproject.toml └── uv.lock ``` 标记为 *(计划中)* 的目录目前作为包存根存在，但尚未包含领域代码。随着开发按照[路线图](docs/roadmap.md)推进，它们将逐渐被填充。 ## 技术栈 Pathfinder 以 **Python** 优先 (3.11+)，使用 [uv](https://docs.astral.sh/uv/) 管理，并使用 [hatchling](https://hatch.pypa.io/) 构建。 | 工具 | 用途 | |---|---| | **uv** | 包和依赖管理 | | **ruff** | Linting 和格式化 | | **mypy** | 静态类型检查 | | **pytest** | 测试和覆盖率 | | **Ollama** | 本地 LLM 推理（主要推理后端，例如 DeepSeek R1） | | **MCP** | Model Context Protocol — Pathfinder 消耗专门构建的 MCP 服务器（例如 `scripts/mcp_servers/nmap_mcp_server.py`）以进行受治理的工具调用 | | **httpx** | 异步 HTTP 客户端（用于 LLM 和基于 HTTP 的 MCP 传输） | | **Jinja2** | 版本化的 prompt 模板 | | **Docker Compose** | 测试床环境 | 代理循环有意在一个小型、显式的核心之上实现，而不是使用沉重的现成框架，以便每个组件都可以独立地被替换、插桩和消融。Pathfinder 不会训练、fine-tune、托管或分发任何模型 —— 它通过定义良好的接口调用外部 LLM（通过 Ollama 本地调用，或通过 API 远程调用）以及外部工具（通过 MCP 服务器）。 ## 研究与引用 Pathfinder 伴随基尔大学 关于代理式和生成式 AI 在自主 VAPT 中应用的持续研究，包括一篇目前正在编辑部修订中的合著系统综述。一旦相关工作公开发表，完整的引用条目将发布在 [`CITATION.cff`](CITATION.cff) 中。 如果您希望在发表之前讨论本研究，请通过 [`SECURITY.md`](SECURITY.md) 中列出的联系方式与维护人员联系。 ## 许可证 Pathfinder 采用 **Apache License 2.0** 授权。完整文本请参见 [`LICENSE`](LICENSE)。 Apache 2.0 许可证授予您使用、修改和重新分发本软件的广泛权利，**前提是需遵守本 README 顶部规定的授权使用限制**。该许可证管辖知识产权；它并不授权对本软件的非法使用。 ## 致谢 Pathfinder 是在基尔大学 的博士研究背景下开发的。 **指导老师：** Mohamed Chahine Ghanem (University of Liverpool)，Marcio Lacerda (London Metropolitan University)。 **AI 工具披露：** 本框架的开发得到了 Claude (Anthropic) 在架构设计、代码生成、文档起草和代码审查方面的协助。所有设计决策、研究方向和最终的实现选择均由维护人员负责。Pathfinder 不包含任何 AI 生成的模型权重或训练数据。

标签：AES-256, AI风险缓解, CISA项目, CTI, IP 地址批量处理, LLM评估, MCP工具集成, Ollama, Red Teaming, VAPT, Web报告查看器, 人工智能, 安全合规, 安全报告, 安全规则引擎, 密码管理, 恶意样本开发, 授权测试, 插件系统, 攻击模拟, 智能体框架, 本地LLM, 漏洞评估, 版权保护, 用户模式Hook绕过, 网络代理, 网络安全, 运行时操纵, 逆向工具, 隐私保护, 驱动签名利用