# bytemonk-academy/owasp-agentic-lab architecture

> Architecture diagram of the GitHub repository bytemonk-academy/owasp-agentic-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bytemonk-academy/owasp-agentic-lab
- Repository: https://github.com/bytemonk-academy/owasp-agentic-lab

## Overview

This repository is a hands-on agent-security lab: a deterministic or optional Anthropic planner proposes actions for a triage agent, while task-scoped controls determine which actions may run. The main workflow is task and context preparation, planning, goal-drift and policy checks, capability issuance, tool execution, and tagged results returned to context. The fake world makes reads, writes, execution, memory, and damage observable; the labs teach five external controls. Source excerpts show the main loop and tool wiring; unsampled model and world internals are represented only where the README or source index supports them.

Main entry points: [`src/agent/agent.ts`](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/agent/agent.ts) (Agent loop), [`src/tools/index.ts`](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts) (Tool registry), [`src/world/state.ts`](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/state.ts) (World and damage ledger), [`src/model/index.ts`](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/index.ts) (Model loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_tasks["Task definitions<br/>[tasks.ts]"]
  node_agent["Agent loop<br/>[agent.ts]"]
  node_model_loader["Model loader<br/>[index.ts]"]
  node_scripted["Scripted planner<br/>[scripted.ts]"]
  node_anthropic["Anthropic planner<br/>[anthropic.ts]"]
  node_shared_types["Agent contracts<br/>[types.ts]"]
end

subgraph group_controls["Security controls"]
  node_untrusted["Provenance controls<br/>[untrusted.ts]"]
  node_policy["Action policy<br/>[policy.ts]"]
  node_capability["Task capabilities<br/>[capability.ts]"]
  node_sandbox["Execution sandbox<br/>[sandbox.ts]"]
  node_memory_guard["Memory guard<br/>[memory-guard.ts]"]
end

subgraph group_tools["Agent tools"]
  node_tool_registry["Tool registry<br/>[index.ts]"]
  node_issues_docs["Issue and docs tools<br/>[index.ts]"]
  node_sensitive_reads["Config and customer tools<br/>[index.ts]"]
  node_side_effects["Write and shell tools<br/>[index.ts]"]
end

subgraph group_world["Simulated world"]
  node_fixtures["Fake fixtures<br/>[fixtures.ts]"]
  node_world_state[("World and damage ledger<br/>[state.ts]")]
  node_dropbox["Attacker drop box<br/>[dropbox.ts]"]
  node_harness["Attack harness<br/>[repro.js]"]
end

node_operator(("Operator"))

node_operator -->|"defines task"| node_tasks
node_tasks -.->|"supplies task"| node_agent
node_agent -->|"loads planner"| node_model_loader
node_model_loader -->|"selects default"| node_scripted
node_model_loader -.->|"selects optionally"| node_anthropic
node_agent -->|"prepares context"| node_untrusted
node_agent -->|"authorizes call"| node_policy
node_agent -->|"mints authority"| node_capability
node_agent -->|"filters recall"| node_memory_guard
node_agent -->|"dispatches calls"| node_tool_registry
node_tool_registry -->|"asserts authority"| node_capability
node_tool_registry -->|"checks persistence"| node_memory_guard
node_tool_registry -->|"executes command"| node_sandbox
node_tool_registry -->|"registers tools"| node_issues_docs
node_tool_registry -->|"registers tools"| node_sensitive_reads
node_tool_registry -->|"registers tools"| node_side_effects
node_issues_docs -->|"reads issue and docs"| node_fixtures
node_sensitive_reads -->|"reads fake records"| node_fixtures
node_issues_docs -->|"looks up issue"| node_world_state
node_sensitive_reads -->|"records reads"| node_world_state
node_side_effects -->|"records effects"| node_world_state
node_world_state -->|"initializes from"| node_fixtures
node_side_effects -.->|"may invoke"| node_harness

click node_tasks "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/agent/tasks.ts"
click node_agent "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/agent/agent.ts"
click node_model_loader "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/index.ts"
click node_scripted "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/scripted.ts"
click node_anthropic "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/anthropic.ts"
click node_shared_types "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/types.ts"
click node_untrusted "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/untrusted.ts"
click node_policy "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/policy.ts"
click node_capability "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/capability.ts"
click node_sandbox "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/sandbox.ts"
click node_memory_guard "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/memory-guard.ts"
click node_tool_registry "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts"
click node_issues_docs "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts"
click node_sensitive_reads "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts"
click node_side_effects "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts"
click node_fixtures "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/fixtures.ts"
click node_world_state "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/state.ts"
click node_dropbox "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/dropbox.ts"
click node_harness "https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/attacker-harness/scripts/repro.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tasks,node_agent,node_model_loader,node_scripted,node_anthropic,node_shared_types toneBlue
class node_untrusted,node_policy,node_capability,node_sandbox,node_memory_guard toneAmber
class node_tool_registry,node_issues_docs,node_sensitive_reads,node_side_effects toneMint
class node_fixtures,node_world_state,node_dropbox,node_harness toneRose
class node_operator toneIndigo
```

## Components

### Agent runtime

- [Task definitions](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/agent/tasks.ts): `src/agent/tasks.ts`
- [Agent loop](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/agent/agent.ts): `src/agent/agent.ts`
- [Model loader](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/index.ts): `src/model/index.ts`
- [Scripted planner](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/scripted.ts): `src/model/scripted.ts`
- [Anthropic planner](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/model/anthropic.ts): `src/model/anthropic.ts`
- [Agent contracts](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/types.ts): `src/types.ts`

### Security controls

- [Provenance controls](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/untrusted.ts): `src/security/untrusted.ts`
- [Action policy](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/policy.ts): `src/security/policy.ts`
- [Task capabilities](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/capability.ts): `src/security/capability.ts`
- [Execution sandbox](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/sandbox.ts): `src/security/sandbox.ts`
- [Memory guard](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/security/memory-guard.ts): `src/security/memory-guard.ts`

### Agent tools

- [Tool registry](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Issue and docs tools](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Config and customer tools](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Write and shell tools](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/tools/index.ts): `src/tools/index.ts`

### Simulated world

- [Fake fixtures](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/fixtures.ts): `src/world/fixtures.ts`
- [World and damage ledger](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/state.ts): `src/world/state.ts`
- [Attacker drop box](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/dropbox.ts): `src/world/dropbox.ts`
- [Attack harness](https://github.com/bytemonk-academy/owasp-agentic-lab/blob/main/src/world/attacker-harness/scripts/repro.js): `src/world/attacker-harness/scripts/repro.js`

### Other components

- **Operator**

## Connections

- Operator → Task definitions: defines task (evidence: `README.md`)
- Task definitions → Agent loop: supplies task
- Agent loop → Model loader: loads planner (evidence: `src/agent/agent.ts`)
- Model loader → Scripted planner: selects default (evidence: `src/model/index.ts`)
- Model loader → Anthropic planner: selects optionally (evidence: `src/model/index.ts`)
- Agent loop → Provenance controls: prepares context (evidence: `src/agent/agent.ts`)
- Agent loop → Action policy: authorizes call (evidence: `src/agent/agent.ts`)
- Agent loop → Task capabilities: mints authority (evidence: `src/agent/agent.ts`)
- Agent loop → Memory guard: filters recall (evidence: `src/agent/agent.ts`)
- Agent loop → Tool registry: dispatches calls (evidence: `src/agent/agent.ts`)
- Tool registry → Task capabilities: asserts authority (evidence: `src/tools/index.ts`)
- Tool registry → Memory guard: checks persistence (evidence: `src/tools/index.ts`)
- Tool registry → Execution sandbox: executes command (evidence: `src/tools/index.ts`)
- Tool registry → Issue and docs tools: registers tools (evidence: `src/tools/index.ts`)
- Tool registry → Config and customer tools: registers tools (evidence: `src/tools/index.ts`)
- Tool registry → Write and shell tools: registers tools (evidence: `src/tools/index.ts`)
- Issue and docs tools → Fake fixtures: reads issue and docs (evidence: `src/tools/index.ts`)
- Config and customer tools → Fake fixtures: reads fake records (evidence: `src/tools/index.ts`)
- Issue and docs tools → World and damage ledger: looks up issue (evidence: `src/tools/index.ts`)
- Config and customer tools → World and damage ledger: records reads (evidence: `src/tools/index.ts`)
- Write and shell tools → World and damage ledger: records effects (evidence: `src/tools/index.ts`)
- World and damage ledger → Fake fixtures: initializes from (evidence: `src/world/state.ts`)
- Write and shell tools → Attack harness: may invoke
