# Module S01 — Security Harness Architecture **Course**: 2A — Building AI Harnesses for Cybersecurity **Module**: S01 — Security Harness Architecture **Duration**: 60 minutes **Level**: Senior Engineer and above **Prerequisites**: Course 1 complete · S00 complete (the legal layer is the input) > *How a general harness changes when retooled for security domains. The offensive state machine, scope enforcement as a hard-wired primitive, and the adversarial tool output problem.* --- ## Learning Objectives After completing this module, you will be able to: 1. Draw the offensive state machine (Recon → Hypothesis → Exploit → Evidence → Triage → Report) and name every structural difference from a general ReAct loop. 2. Implement scope enforcement as harness middleware that intercepts every outbound tool call — and explain why it is a distinct control plane from code-execution sandboxing. 3. Map the CAI autonomy-level model (Level 0–5) and defend which level is appropriate for a given engagement type. 4. Explain the InjecAgent finding (~50% of agentic tasks vulnerable to indirect injection via tool outputs) and apply Course 1's untrusted-content tagging in the offensive context. 5. Specify why offensive harnesses need a stricter trust model than general ones: every external read is potentially hostile. --- ## The transition from Course 1 Course 1's execution loop (Module 1) assumed a cooperative environment. The model calls `read_file`, gets trusted content, reasons about it, calls the next tool. The loop exits when the model says `end_turn`. Verification means "did it work?" None of that holds in a security harness. The target is an adversary. Every HTTP response, every DNS record, every file header, every JSON payload the harness reads from the target may be a weapon pointed back at the model. The loop exits when the evidence threshold is met or the scope is exhausted. Verification means "can I prove this to a client, program, or court?" This module covers the three architectural changes that make a general harness into a security harness. They are not features bolted on — they are structural changes to the loop, the tool layer, and the trust model. --- # S01.1 — The Offensive State Machine *The security-specific execution loop. What changes when the loop's job is to find and prove vulnerabilities.* ## From ReAct to the offensive loop Course 1's ReAct loop is Thought → Action → Observation, repeated until stop. The offensive state machine is a specialization of this loop — same underlying machinery, different states, different stop conditions, different evidence requirements. It is not a replacement for ReAct; it is ReAct retooled for an adversarial domain. The six states: ``` Recon → Hypothesis → Exploit Attempt → Evidence Capture → Triage → Report ↑ | └────────────────────────────────────────────────────────┘ (next finding, or scope exhausted → stop) ``` | State | What happens | Course 1 equivalent | What changes | | --- | --- | --- | --- | | **Recon** | Enumerate the target: ports, services, endpoints, versions, config | Tool call (generic) | Output is adversarial; scope-checked; evidence-tagged at capture | | **Hypothesis** | Model reasons: "based on recon, I hypothesize vulnerability X" | Thought | Hypothesis is testable and falsifiable; logged as an evidence-chain entry | | **Exploit Attempt** | Model constructs and executes a test for the hypothesis | Tool call | The most legally sensitive step; scope enforcement is load-bearing here | | **Evidence Capture** | Structured record of the attempt and its result | Observation | Not free-form — schema-validated, scope-referenced, append-only | | **Triage** | Model evaluates: is this a real finding? severity? in scope? | Reasoning | Signal/noise filter; false-positive suppression (S02.4) | | **Report** | Finding is formalized into a structured finding record | Final answer | Not the end — feeds back to Recon for the next hypothesis | **Three structural differences from a general ReAct loop:** 1. **Adversarial inputs.** In a general harness, tool outputs are trusted. In an offensive harness, tool outputs from the target may contain prompt-injection payloads. The Observation step is no longer a passive receipt — it is a potential attack vector. (Covered in S01.3.) 2. **Evidence-driven stop conditions.** A general loop stops when the model says "done." An offensive loop stops when the evidence threshold is met (enough findings to report) or scope is exhausted (every in-scope target assessed). The stop condition is externally defined, not model-determined. 3. **Domain-specific evidence collection.** A general harness logs tool calls for debugging. An offensive harness logs them as *evidence* — each observation is a structured record with legal weight. The evidence schema (from S00.2) is built into the loop, not bolted on. ## Kill chain state management For multi-stage attacks (privilege escalation chains, lateral movement, multi-step exploits), the harness must track state across many turns without losing intermediate progress. This is the *kill chain state management* problem. A general harness loses track of multi-step reasoning because intermediate state lives in the context window, and context windows fill and compact (Course 1, Module 3). In an offensive harness, losing step 3 of a 10-step kill chain means starting over — or worse, repeating an exploit attempt that already succeeded, creating duplicate evidence and confusing the triage step. The solution is **attack-graph state** — a persistent structure, separate from the context window, that tracks each step of the kill chain with its state: ```typescript interface AttackGraphNode { id: string; step: number; hypothesis: string; action: string; result: "unexplored" | "attempting" | "succeeded" | "failed" | "out_of_scope"; evidence_ref: string | null; // link to evidence chain children: string[]; // next possible steps parent: string | null; session_id: string; } ``` This is not context-window reasoning. It is a separate state structure — persisted in the engagement memory (S02.1) — that survives context compaction, session boundaries, and model failures. The model reads the graph's current state to know where it is in the kill chain; the harness updates the graph after each step. ## The autonomy level model CAI (Cybersecurity AI, Alias Robotics) defines an autonomy-level model for offensive harnesses that maps cleanly onto the engagement types in this course: | Level | Name | Human role | Appropriate for | | --- | --- | --- | --- | | **0** | Manual | Human does everything; harness is a tool wrapper | Training; learning the tool suite | | **1** | Assisted | Human directs; harness suggests next steps | Expert pentest; the harness as force multiplier | | **2** | Guided | Harness proposes; human approves each action | Production bug bounty; the approval gate is a legal control (S00.3) | | **3** | Supervised | Harness executes autonomously within a bounded scope; human monitors | Engagements with well-defined scope and low collateral risk | | **4** | Highly autonomous | Harness operates with minimal oversight; human intervenes on alerts | Isolated lab targets, CTFs, benchmark runs — NOT production | | **5** | Fully autonomous | No human in the loop | Research; never appropriate for real engagements | **Why most production offensive harnesses sit at Level 2–3.** S00.3 established that the approval gate is a legal control: at Level 2, every exploit attempt passes through human approval, which means every legally sensitive action has a documented human decision behind it. At Level 3, the harness operates autonomously within a bounded scope — the scope enforcement middleware (S01.2) is the control, and the human monitors rather than approves each action. Level 4–5 removes the human decision from legally sensitive actions, which is why it is appropriate only for targets where there are no legal consequences (labs, CTFs, benchmarks). **The bounded-autonomy pattern.** The practical implementation of Level 2–3 is the *propose → approve → execute* loop: ``` Harness proposes action (with scope check, evidence plan, expected impact) ↓ [Level 2] Human reviews → approves / rejects / modifies [Level 3] Auto-approved if scope-compliant; human notified if not ↓ Harness executes (with evidence capture, rate limiting) ↓ Harness reports result + evidence to human ``` The approval gate is not a performance bottleneck. It is the point where a human decision is recorded for every legally sensitive action. Removing it for speed gains is the most common production-failure mode in offensive harnesses. --- # S01.2 — Scope Enforcement as a Safety-Critical Layer *Scope is not a system prompt line. It is a hard-wired permission primitive that intercepts every outbound tool call. This is the engineering realization of S00's legal layer.* ## The three components of a scope file S00.1 formalized the scope boundary as a JSON file. S01.2 loads that file into middleware. The scope file has three components, each enforced independently: 1. **Authorized targets** (`in_scope`): the exhaustive list of hosts, domains, IPs, and services the harness may reach. Matching is exact (not glob), and exclusions override apparent matches. 2. **Rules of engagement** (`rules_of_engagement`): the behavioral contract — permitted actions, rate caps, forbidden categories (DoS, exfiltration, social engineering). This is distinct from the target list; an action can be in-scope for the target but forbidden by the RoE. 3. **Evidence constraints** (`evidence_constraints`): what evidence may be captured and retained. Minimum-proof discipline, data classification at capture, retention rules. These flow from S00.2's retention policy directly into the harness's evidence logger. ## Implementing scope as harness middleware The critical architectural decision: scope enforcement sits *between the agent and every network/filesystem action*. It is not part of the system prompt. It is not a tool-level check. It is middleware that wraps the tool execution layer — the same wrapper pattern from Course 1's observability module (M1.4), now applied to authorization. ```typescript // Scope enforcement middleware — wraps every outbound tool call function withScopeEnforcement( executor: ToolExecutor, scope: ScopeFile ): ToolExecutor { return async (toolCall: ToolCall): Promise => { // 1. Check target is in scope if (!scope.isInScope(toolCall.target)) { return blockedResult({ reason: "out_of_scope", target: toolCall.target, scope_ref: null }); } // 2. Check action is permitted by RoE if (scope.roe.forbiddenActions.includes(toolCall.action)) { return blockedResult({ reason: "action_forbidden_by_roe", action: toolCall.action, scope_ref: null }); } // 3. Check scope freshness if (scope.isStale()) { return blockedResult({ reason: "scope_expired", valid_until: scope.validUntil }); } // 4. Stamp the scope reference for the evidence chain const scopeRef = `${toolCall.target}::${toolCall.action}::${new Date().toISOString()}`; // 5. Execute (with rate limiting from the RoE) const result = await rateLimited( () => executor(toolCall), scope.roe.maxRequestsPerSecond ); // 6. Return with scope reference attached return { ...result, scope_ref: scopeRef }; }; } ``` **Key design points:** - **The middleware cannot be bypassed by the model.** It wraps the executor at a layer below the model's control. The model can propose any tool call; the middleware decides whether it reaches the network. This is what makes scope enforcement a *legal control* (S00.3): the harness's legal posture does not depend on model compliance. - **Blocked calls return structured results, not errors.** A blocked call is not a crash — it is a normal tool result that says "this was out of scope." The model receives this and reasons about it (typically by adjusting its plan to stay in scope). This is important: the model should *know* it was blocked, so it can avoid proposing the same call again. - **The scope reference is stamped on every permitted call.** This is the `scope_ref` field from S00's evidence chain — the legal anchor that ties each tool call to the authorization that permitted it. The evidence logger (S02.3) reads this field automatically. ## Scope vs. code execution: two different control planes A common confusion: teams implement a sandbox (Course 1, Module 5) and think they have solved scope. They have not. **Scope enforcement and code-execution sandboxing are two different control planes, and both are required.** | Control plane | What it controls | Question it answers | Course 1 module | | --- | --- | --- | --- | | **Code-execution sandbox** | What the agent can do *locally* | "Can the agent write to the filesystem? Spawn processes? Reach the network at all?" | Module 5 | | **Scope enforcement** | Where the agent can *reach* | "Is this specific host/action authorized by the engagement scope?" | This module (S01.2) | A sandbox without scope enforcement contains the agent but lets it attack the world — the agent can reach any network endpoint the sandbox permits, authorized or not. Scope enforcement without a sandbox prevents unauthorized network access but lets the agent do anything locally (write files, spawn processes, modify the host). An offensive harness needs both: the sandbox defines the blast radius (local containment), and scope enforcement defines the authorization boundary (network reach). The sandbox says "you can reach the network"; scope enforcement says "but only these targets, only these actions." --- # S01.3 — Adversarial Tool Outputs *In security harnesses, the target is an adversary. Every read from the target is potentially hostile. The InjecAgent finding: ~50% of agentic tasks are vulnerable.* ## The inversion of trust Course 1's trust model: tool outputs are trusted. When `read_file` returns content, the model reasons about it as data. When `search` returns results, the model treats them as information. The harness wraps tools to return structured, trustworthy output. In an offensive harness, that trust model inverts. The target is an adversary. Every output the harness reads from the target — HTTP responses, HTML pages, API JSON, response headers, file metadata, DNS records — may contain a payload designed to manipulate the model. This is **indirect prompt injection via tool outputs**, and it is the defining adversarial risk of offensive harnesses. **The attack pattern:** ``` 1. Harness sends HTTP request to target (authorized, in scope) 2. Target returns a response containing an injected instruction: "" 3. The harness places this response into the model's context as an observation 4. The model may follow the injected instruction instead of the system prompt ``` The injected instruction can cause the model to: exfiltrate findings to an attacker-controlled endpoint, suppress real vulnerabilities, propose out-of-scope actions, corrupt the engagement memory, or generate misleading evidence. ## The InjecAgent benchmark InjecAgent (the benchmark referenced throughout this course) measured the vulnerability of agentic systems to indirect prompt injection via tool outputs. The finding: **approximately 50% of agentic tasks are vulnerable.** Half the time, an injected instruction in a tool output causes the model to deviate from its intended behavior. This is not a hypothetical risk. In an offensive harness, the target *will* return adversarial content — either because the target is deliberately defending itself, or because the target's normal content (HTML comments, API documentation, error messages) happens to contain text that the model interprets as instructions. The harness must assume every external read is hostile. ## Applying Course 1's untrusted-content tagging Course 1 (Module 11, Security Engineering) introduced untrusted-content tagging: wrapping external content in the context window with markers that tell the model "this is data, not instructions." In the offensive context, this becomes stricter — every tool output from the target gets the untrusted tag. ```typescript function wrapToolOutput(output: ToolOutput, source: "target" | "local"): string { if (source === "target") { // Every read from the target is untrusted return `\n${output.content}\n`; } // Local reads (engagement memory, scope file) are trusted return output.content; } ``` The model is instructed (in the system prompt, reinforced by the tag structure) to treat content within `` tags as data only — never as instructions. This is a defense-in-depth layer; it is not sufficient on its own (the InjecAgent finding shows models can be tricked past tagging), but it raises the bar significantly. ## Why offensive harnesses need a stricter trust model The trust model for an offensive harness is stricter than a general one in three ways: 1. **Every external read is potentially hostile.** Not just "untrusted" in the general sense — actively adversarial. The content was produced by a system that may be trying to manipulate your model. 2. **The model must never act on instructions found in target content.** A general harness can be somewhat relaxed about this (the search results are probably not trying to manipulate you). An offensive harness cannot — the target content is the attack surface. 3. **Findings derived from adversarial content need cross-validation.** If the model reads an HTTP response and hypothesizes a vulnerability based on it, that hypothesis should be tested against the actual target behavior, not taken at face value. The target can lie in its responses; the harness verifies by independent observation. ## The mitigation stack No single defense fully solves adversarial tool outputs. The mitigation is layered: 1. **Untrusted-content tagging** (above) — every target read tagged as data. 2. **Output sanitization** — strip or neutralize known injection patterns (HTML comments containing "system" or "ignore," JSON fields with instruction-like content). Imperfect but raises the bar. 3. **Separation of concerns** — the model that reads target content is not the same model that decides actions. A "reader" model ingests the raw target output and produces a structured summary; the "actor" model sees only the summary, never the raw adversarial content. (This is the InjecAgent-recommended architecture.) 4. **InjecAgent as a quality gate** — run the InjecAgent benchmark against your harness before deploying it. If your harness fails >20% of injection tests, it is not ready for production. (S05.3 covers this in detail.) 5. **Evidence cross-validation** — findings are never accepted from a single observation. The harness re-tests the hypothesis against the target independently before formalizing it as evidence. --- ## Anti-Patterns ### The scope-as-prompt pattern Putting scope rules in the system prompt. The model is a reasoner, not an access-control system. Cure: scope enforcement middleware (this module). The system prompt can *describe* the scope; it must not *enforce* it. ### The un-sandboxed offensive harness Running an offensive harness without code-execution isolation. The agent reaches out to attack the target but has no local containment — if compromised by a prompt injection, it can modify the host. Cure: both control planes — sandbox for local containment, scope enforcement for network reach. ### The reader-actor collapse Using the same model instance to read target content and decide actions. An injection in the target content directly controls the action-deciding model. Cure: separate the reader and actor models; the actor sees only structured summaries, never raw target output. ### Autonomy level mismatch Running at Level 4–5 against a production target because "the scope is well-defined." Scope enforcement handles the authorization boundary, but it does not handle the judgment calls — what to do when a finding is ambiguous, when an exploit has unexpected effects, when the evidence is contradictory. Cure: autonomy level matched to engagement type (Level 2–3 for production). --- ## The base harness: tau-security Everything above — the offensive state machine, the scope enforcement middleware, the evidence threshold — has been taught conceptually. You understand the architecture. Now you need a running system to build on. Throughout this course, you will extend a real agent harness called **tau-security**, turning it from a coding agent into a security agent. tau-security is a companion to [tau](https://github.com/huggingface/tau), a minimalist Python coding agent published under the Hugging Face org. Its explicit purpose is to be read like a book — it is the most readable coding-agent harness available, and its architecture maps almost perfectly onto security harness requirements. ### Why tau, not CAI or RedTeamLLM? CAI, RedTeamLLM, and Heimdallr are **production systems** — powerful, feature-rich, and opaque. They are excellent case studies (SDD-01, SDD-02, SDD-09) but poor teaching substrates. A student who clones CAI sees thousands of lines across dozens of packages; the security architecture is buried under CTF domain routers, framework abstractions, and production features. tau is different. Its entire portable brain is under 800 lines: ``` tau_agent/harness.py ~298 lines AgentHarness: transcript, steering queue, event listeners tau_agent/loop.py ~276 lines run_agent_loop: the pure provider/tool loop tau_agent/tools.py ~78 lines AgentTool: frozen dataclass + async executor tau_agent/events.py ~134 lines 14 typed events (the contract between layers) ``` You can read all of it in an hour. And its three-layer separation is exactly the design that makes security adaptation clean: ``` tau_ai → provider/model streaming (OpenAI, Anthropic, local) tau_agent → portable agent brain (loop, tools, events, sessions) tau_coding → coding app (read, write, edit, bash tools) tau_security → security app (port_scan, http_probe, code_scan, scope, evidence) ← you build this ``` ### The four-part transformation tau-security makes four changes to tau. None of them touch the brain: 1. **System prompt**: A coding-assistant prompt becomes the offensive state machine (Recon → Hypothesis → Exploit → Evidence → Triage → Report). This is the same state machine you learned above, encoded as instructions the model follows when driving the tools. 2. **Tools**: `read`/`write`/`edit`/`bash` become `port_scan`/`http_probe`/`code_scan`/`record_finding`/`generate_report`. Each security tool follows the same `AgentTool` pattern — a frozen dataclass with a name, description, input schema, and async executor function. The executor is where scope enforcement hooks in. 3. **Scope enforcement**: Every security tool's executor calls `assert_in_scope()` before touching a target. This is the middleware you learned about in this module, hard-wired into the tool layer. The model cannot bypass it; an out-of-scope target returns a blocked result that never executes. 4. **Evidence chain**: tau's event stream (`ToolExecutionEndEvent`) is subscribed to by an evidence logger that captures every tool result with a SHA-256 hash, chained to the previous record for tamper-evidence. This is the evidence-threshold stop made concrete. The agent loop doesn't change. The session durability doesn't change. The provider layer doesn't change. The model doesn't change. **This is the course thesis in code: the harness is 98.4% of the system.** ### What you will do with it Starting in the capstones (C1, C2), you will: - Configure a `SecurityHarness` with a scope object matching a real engagement - Run the harness against a real target (OWASP Juice Shop for bug bounty, a vulnerable repo for AppSec) - Write a custom security tool as an `AgentTool` and register it alongside the defaults - Watch the event stream produce evidence in real time - Run the triage pipeline and generate a client-ready report - Benchmark: scope enforcement (100% OOS block rate), injection defense, finding recall The tau-security package, its teaching documentation, and the SDD-13 deep-dive (which scores tau on the 12-module rubric at 40/60) are your reference materials. The capstones are where the architecture becomes a running system. --- ## Key Terms | Term | Definition | | --- | --- | | **Offensive state machine** | The security-specific execution loop: Recon → Hypothesis → Exploit → Evidence → Triage → Report | | **Attack-graph state** | Persistent structure tracking multi-step kill chains across context windows and sessions | | **Autonomy level** | CAI's Level 0–5 model; production offensive harnesses sit at Level 2–3 | | **Bounded autonomy** | The propose → approve → execute pattern; the approval gate is a legal control | | **Scope enforcement middleware** | The harness layer wrapping every outbound call with scope checks; a legal control | | **Two control planes** | Sandbox (local containment) + scope enforcement (network authorization); both required | | **Adversarial tool output** | Target content designed to manipulate the model via indirect prompt injection | | **InjecAgent finding** | ~50% of agentic tasks vulnerable to indirect injection via tool outputs | | **Untrusted-content tagging** | Wrapping target reads as data-only in the context window | | **Reader-actor separation** | A separate model ingests raw target content; the actor sees only structured summaries | --- ## Lab Exercise See `07-lab-spec.md`. Three labs: (1) draw the CAI state machine from source and map it against a Course 1 ReAct loop; (2) implement the scope enforcement middleware and attempt out-of-scope calls from every direction; (3) serve a prompt injection payload from a mock HTTP server and observe which harness configurations execute the injected instruction. --- ## References 1. **CAI (Cybersecurity AI)** — Alias Robotics. MIT-licensed. The autonomy-level model and the offensive state machine. Primary case study throughout Pillar 1; covered in depth in SDD-01. 2. **InjecAgent** — Adversarial tool output benchmark. ~50% vulnerability finding. Pass/fail quality gate in S05.3 and SDD-12. 3. **RedTeamLLM** (arXiv) — Integrated pentest automation. Plan correction and kill chain state management. Covered in S03 and SDD-02. 4. **Course 1, Module 1** — The execution loop (ReAct). The offensive state machine is a specialization of this loop. 5. **Course 1, Module 5** — Sandboxing & Isolation. The first control plane; S01.2 adds the second. 6. **Course 1, Module 11** — Security Engineering. Untrusted-content tagging, introduced in the general context, now applied to offensive harnesses. 7. **S00** — The legal layer. The scope file from S00.1 is the input to this module's scope enforcement middleware. 8. **tau-security** — The base harness used throughout this course. A companion package to tau (github.com/huggingface/tau) that wraps tau's AgentHarness as a security agent. Covered in the tau-security teaching docs and scored in SDD-13. 9. **tau** — A minimalist Python coding agent by alejandro-ao, published under the Hugging Face org. The most readable coding-agent harness available. Its three-layer architecture (tau_ai / tau_agent / tau_coding) is the foundation for tau-security. Covered in depth in SDD-13.