mouteee/autonomous-offensive-llm-handbookA deterministic harness and handbook for autonomous offensive LLM agents, enforcing authorization, scope, and evidence gates to ensure reproducible and honest penetration testing.
📖 Read the handbook online: follow the lessons from your first fixture run to an agent with clear limits.
AUTONOMOUS SECURITY / THE BUILDER'S FIELD MANUAL
Read the website · Start the course · Run the lab · Connect your model · The build sequence
A practical handbook for building autonomous security agents with explicit limits on what a model may decide. Learn how to turn observations into a plan, admit only permitted actions, bind findings to evidence, and account for work that could not be completed.
The model remains probabilistic. The host application owns authorization, allowed actions, evidence records and acceptance. Replaying frozen inputs and policy can reproduce those control decisions; it does not make a live target or model response repeatable.
You should be comfortable reading basic Python, JSON and HTTP. Follow the core route from the first run through the assembled application. The dispatch lesson points you to a short baseline selection contract; the adaptive controllers are optional after the core build. Along the way, you edit starter files and run checks that fail until your code works. The course runs offline without an API key or target connection.
The reading website presents the lessons in order, with navigation, diagrams and search. Use the website guide to build or preview it locally.
From a local copy of this repository:
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m harness.demo --out /tmp/harness-report.json
diff -u harness/report.json /tmp/harness-report.json
python3 -m pytest tests/test_harness.py
This release is verified on CPython 3.14. Earlier Python versions are not part of the release evidence; if you use one, run the complete gate sequence below before relying on the result.
When the report matches the committed example, diff prints nothing. Open the report and follow the header finding from its proposed severity to its governed severity. Then inspect the rejected raise and the synthetic marker's permitted raise. Both findings still require human review.
Read the input manifest, the implementation, and the adversarial tests beside the example report. You have completed this introduction when you can explain why an action was permitted, why a raise was refused, and what the report's coverage counts actually measure.
The default harness lab makes no network request and calls no model. Its proof predicate is synthetic, its host and adapters are trusted, and every finding is marked as requiring human review. The lab does not implement a person's acceptance or report-signing workflow. A verbatim quote establishes citation integrity, not exploitability. Fewer model calls and less rework are design objectives, not savings measured by the corpus.
Your model supplies proposals. The application keeps policy and state, checks each proposal, runs permitted fixture actions and records the result. This repository gives you the application and exercises; you supply the model connection.
your model -> JSON proposal -> application checks -> fixture tool -> evidence + report
|
reject or stop
Run the assembled application with its fake model transport first:
python3 -m examples.app_agent --out /tmp/agent-report.json --store /tmp/agent-memory.db
python3 -m pytest tests/test_app_agent_example.py -q
Inspect the proposal statuses and evidence in /tmp/agent-report.json. Then follow Connect your own model to use a local model or write a transport wrapper. The older model bridge remains a smaller connection exercise with a different proposal format. Both examples keep tool actions on fixtures, including when a real model supplies the reply.
The guide names what to replace, the JSON to return, the checks to keep, the expected report and the remaining work before adding live tools.
The diagram combines the lab's controls with the proposal connection. The model bridge exercises action admission and evidence capture; the default lab separately demonstrates finding governance. Neither is a complete live security agent.
Any diagram opens at full size when you click it; on a narrow screen you can also scroll it sideways.
This is the learning order. At runtime, authorization and the gate precede dispatch. Each lesson should leave you with a small component, an adversarial test, and an artifact you can inspect.