Pathfinder-AI

# Pathfinder > **An agentic AI framework for autonomous vulnerability assessment and penetration testing (VAPT).** > Pathfinder implements an *observe–reason–decide–act* loop over modular security tooling, with the goal of evaluating how far large language model–driven agents can autonomously plan, execute, and report on offensive security engagements within controlled, authorised environments. > > Current status: end-to-end functional. Core agent loop, governance layer (ScopedPolicy), telemetry (hash-chained run logs), prompt template system, local LLM integration (Ollama), and a custom MCP server wrapping Nmap are all implemented and tested. Lab configs, the PEER orchestrator, and the evaluation harness are next. As of 9 May 2026, the framework has run a full LLM → MCP → real-tool → structured-result cycle locally in ~115ms. --- ## ⚠️ Authorised Use Only — Read This First Pathfinder is offensive security research software. It is designed to **plan and execute actions that would be illegal if performed against systems you do not own or do not have explicit, written permission to test.** **You may use Pathfinder only against:** - Systems you own outright, or - Isolated lab environments under your sole control, or - Third-party systems for which you hold **explicit, written authorisation** (a signed Rules of Engagement, statement of work, or equivalent) covering the specific testing activity, scope, and time window. **You must not use Pathfinder to:** - Test, scan, probe, or attempt to exploit any system without prior written authorisation from its owner. - Conduct testing that exceeds the scope, methods, or timeframe defined in your authorisation. - Process, exfiltrate, or retain data belonging to third parties beyond what your authorisation permits. - Circumvent any law, regulation, or contractual obligation in your jurisdiction or the target's. The author and contributors accept no liability for misuse. Unauthorised use of this software against systems you do not have permission to test is a criminal offence in most jurisdictions, including under the **Computer Misuse Act 1990** (UK), the **Computer Fraud and Abuse Act** (US), and equivalent statutes elsewhere. **You are solely responsible for ensuring your use of Pathfinder is lawful and authorised.** If you are unsure whether your intended use is authorised, **do not run this software** until you have written confirmation from the system owner and, where appropriate, legal counsel. See [`SECURITY.md`](SECURITY.md) for vulnerability disclosure policy and [`docs/ethics.md`](docs/ethics.md) for the full research ethics statement. --- ## Current status Pathfinder is in active pre-alpha development. As of 9 May 2026, the framework runs end-to-end: a local LLM (Ollama) reasons about authorised assessment tasks, the ScopedPolicy governance layer enforces engagement scope from YAML configuration, and a custom MCP server invokes real security tools (Nmap) under a strict argument allowlist. The framework has been verified against localhost in a 115ms end-to-end run. Phases 0–2 of the [roadmap](docs/roadmap.md) are complete. Lab integration (Phase 3), full PEER orchestration (Phase 4), and quantitative evaluation (Phase 5) are next. --- ## About Pathfinder is the engineering artefact of an ongoing PhD research programme at Keele University investigating agentic and generative AI for autonomous VAPT. It is intended as both a **research platform** — a substrate for empirical study of agent behaviour in offensive security tasks — and a **reference implementation** of the architectural patterns described in the accompanying systematic review and forthcoming publications. The framework is deliberately modular so that individual components (planners, reasoners, tool wrappers, memory backends, target environments, evaluation harnesses) can be swapped, ablated, or instrumented independently for experimental study. ### What Pathfinder is - A research framework for studying agentic AI in authorised security testing contexts. - A modular agent architecture implementing an explicit observe–reason–decide–act loop. - A platform for repeatable, instrumented experiments in controlled lab environments. ### What Pathfinder is not - A turnkey "autonomous hacker" — it requires expert oversight, scoped lab targets, and careful configuration. - A replacement for human penetration testers — the research question is precisely *how far* agents can go, not whether they should replace practitioners. - Production-ready offensive tooling — this is research-grade software with research-grade caveats. --- ## Architecture Pathfinder operates at two levels: **PEER lifecycle** — the assessment workflow follows a Plan–Enumerate–Exploit–Report structure, reflecting the sequential phases of practical VAPT engagements. | Phase | Responsibility | |-----------|-----------------------------------------------------------------------------------------------| | Plan | Define scope, objectives, constraints, permitted actions, and rules of engagement. | | Enumerate | Reconnaissance and service discovery within the authorised scope. | | Exploit | Validate selected weaknesses safely, with policy enforcement and human approval gates. | | Report | Convert evidence into structured findings, remediation recommendations, and audit artefacts. | **ORDA control loop** — within each PEER phase, the agent runs an observe–reason–decide–act loop that drives iteration-level behaviour. Each phase of the loop is a pluggable Protocol; swapping implementations is a constructor argument, not a subclass. Around these sit the **governance layer** (policy enforcement before every tool call), **telemetry** (structured logging of every iteration), **memory** (observation and decision history), and **tool integration** (external security tools via MCP servers). For the full architecture — including Protocol definitions, data types, loop execution model, and implementation status — see [`docs/architecture.md`](docs/architecture.md). --- ## Repository status | Item | Status | |-------------------|------------------------------------------------------------------------| | Visibility | **Public** — published for transparency and reproducibility during active research. | | Stability | Pre-alpha. Interfaces are unstable and will change without notice. | | Contributions | By invitation only. See [`CONTRIBUTING.md`](CONTRIBUTING.md). | | Roadmap | Phased build plan. See [`docs/roadmap.md`](docs/roadmap.md). | | Architecture | PEER lifecycle + ORDA control loop. See [`docs/architecture.md`](docs/architecture.md). | | Citation | See [`CITATION.cff`](CITATION.cff). | --- ## Getting started > Detailed installation, configuration, and lab setup instructions will be added as the framework stabilises. The notes below describe the *intended* developer workflow. ### Prerequisites - **Python 3.11+** (developed on 3.14) - **uv** — package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/)) - **Ollama** — for local LLM inference ([ollama.com](https://ollama.com/)) — required from Phase 1 onwards - **Docker + Docker Compose** — for testbed environments — required from Phase 3 onwards - A controlled, isolated lab environment for any execution beyond unit tests - LLM provider credentials where applicable (configured via environment variables; see `.env.example`) ### Installation (intended) ```bash git clone <repository-url> 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 ``` ### Running the test suite ```bash pytest ``` Unit and integration tests are designed to run without contacting external systems or LLM APIs by default. ### Running the agent against a lab target A scripted lab setup (vulnerable targets in an isolated network) and example engagement configurations will be provided under `labs/` and `configs/`. **Do not point the agent at any target outside an environment you fully control.** --- ## Project layout ``` 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 ``` Directories marked *(planned)* exist as package stubs but do not yet contain domain code. They will be populated as development progresses through the [roadmap](docs/roadmap.md). --- ## Tech stack Pathfinder is **Python-first** (3.11+), managed with [uv](https://docs.astral.sh/uv/) and built with [hatchling](https://hatch.pypa.io/). | Tool | Purpose | |---|---| | **uv** | Package and dependency management | | **ruff** | Linting and formatting | | **mypy** | Static type checking | | **pytest** | Testing and coverage | | **Ollama** | Local LLM inference (primary reasoning backend, e.g. DeepSeek R1) | | **MCP** | Model Context Protocol — Pathfinder consumes purpose-built MCP servers (e.g. `scripts/mcp_servers/nmap_mcp_server.py`) for governed tool invocation | | **httpx** | Async HTTP client (LLM and HTTP-based MCP transports) | | **Jinja2** | Versioned prompt templates | | **Docker Compose** | Testbed environments | The agent loop is intentionally implemented over a small, explicit core rather than a heavy off-the-shelf framework, so that each component can be swapped, instrumented, and ablated independently. Pathfinder does not train, fine-tune, host, or distribute any model — it calls external LLMs (local via Ollama, remote via API) and external tools (via MCP servers) through well-defined interfaces. --- ## Research and citation Pathfinder accompanies ongoing research at Keele University on agentic and generative AI for autonomous VAPT, including a co-authored systematic review currently under editorial revision. A full citation entry will be published in [`CITATION.cff`](CITATION.cff) once the related work is publicly available. If you wish to discuss the research prior to publication, please contact the maintainer through the channel listed in [`SECURITY.md`](SECURITY.md). --- ## License Pathfinder is licensed under the **Apache License 2.0**. See [`LICENSE`](LICENSE) for the full text. The Apache 2.0 licence grants you broad rights to use, modify, and redistribute this software, **subject to the authorised-use restrictions set out at the top of this README**. The licence governs intellectual property rights; it does not authorise unlawful use of the software. --- ## Acknowledgements Pathfinder is developed in the context of doctoral research at Keele University. **Supervisors:** Mohamed Chahine Ghanem (University of Liverpool), Marcio Lacerda (London Metropolitan University). **AI tooling disclosure:** Development of this framework has been assisted by Claude (Anthropic) for architectural design, code generation, documentation drafting, and code review. All design decisions, research direction, and final implementation choices are the responsibility of the maintainer. Pathfinder does not contain any AI-generated model weights or training data.