# uber/adr architecture

> Architecture diagram of the GitHub repository uber/adr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uber/adr
- Repository: https://github.com/uber/adr

## Overview

#### Purpose and Entry Points
ADR is an enterprise security system for AI agents. This open-source repository provides telemetry collection (Sensor), a benchmark of adversarial agent tasks/MCP servers, and detector implementations; prevention and the offline Explorer are excluded. Primary executable surfaces are `Sensor/adr_sensor/cli.py`, `Detection/main_detector.py`, and `Detection/main_benchmark.py`.

#### Sensor: Endpoint Telemetry Normalization
The Sensor is a Python CLI/runtime that observes local agent activity across coding-agent products and emits a unified event model. Product-specific parsers isolate each tool’s native logs/configuration while the observer coordinates collection:
- `Sensor/adr_sensor/observer.py`
- `Sensor/adr_sensor/parsers/base_parser.py`
- `Sensor/adr_sensor/schemas/agent_event_schema.py`

Platform-specific discovery is bounded in `Sensor/adr_sensor/utils/platform_paths.py`; parsers include Codex, Claude, Cursor, Cline, opencode, Warp, and Claude Desktop.

#### Detection Pipeline
Detection is a separate Python project configured by detector and benchmark YAML. `main_detector.py` selects and runs detectors over session/task inputs, while `main_benchmark.py` drives evaluation. The core detector abstraction enables interchangeable implementations:
- `Detection/main_detector.py`
- `Detection/guardrail/base_detector.py`
- `Detection/config_detector.yaml`

The included ADR baseline is the primary dual-agent detector; LlamaFirewall is an alternative baseline:
- `Detection/guardrail/adr_agent/adr_baseline.py`
- `Detection/guardrail/llamafirewall_agent/llamafirewall_baseline.py`

#### Context and Agentic Reasoning Boundary
The ADR detector is supported by local context-provider services that expose policy, threat intelligence, and source-code analysis. These form an explicit boundary between detection reasoning and security knowledge/tool-code retrieval:
- `Detection/context_providers/policy_store_server.py`
- `Detection/context_providers/threat_intelligence_server.py`
- `Detection/context_providers/source_code_analyzer_server.py`

Their datasets and registries map policies, threats, and simulated MCP implementations:
- `Detection/context_providers/data/policy_store.yaml`
- `Detection/context_providers/data/threat_repository.yaml`
- `Detection/context_providers_registry.json`

#### ADR-Bench Execution Model
ADR-Bench packages attack scenarios, task suites, agents, policy configurations, and results. `benchmark_pack.py` handles benchmark packaging; the vendored AgentDojo framework composes an agent pipeline, planner, prompt-injection detector, and tool execution:
- `Detection/benchmark/benchmark_pack.py`
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/benchmark.py`
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/agent_pipeline/agent_pipeline.py`

Task suites span banking, Slack, travel, and workspace, combining benign user tasks with injection tasks:
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/default_suites/v1/banking/task_suite.py`
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/default_suites/v1/slack/task_suite.py`
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/task_suite/load_suites.py`

#### MCP Simulation and Threat Corpus
The benchmark’s large MCP-server corpus simulates enterprise tools and malicious or risky services. Server registries select available implementations; server code and fixture environments remain local/synthetic rather than production integrations:
- `Detection/mcp_servers_registry.json`
- `Detection/context_providers/source_codes/mcp_servers_0/`
- `Detection/context_providers/source_codes/mcp_servers_2/openai_server.py`

#### Runtimes and External Dependencies
Both major subsystems are Python projects managed with `uv` (`Sensor/pyproject.toml`, `Detection/pyproject.toml`). Detection uses external Anthropic and OpenAI APIs when running the ADR workflow, with LLM adapters in the vendored benchmark:
- `Detection/openai_config.py`
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/agent_pipeline/llms/openai_llm.py`
- `Detection/benchmark/agentdojo/benchmarks/agentdojo/agent_pipeline/llms/google_llm.py`

CI and Sensor release automation run through GitHub Actions:
- `.github/workflows/ci.yml`
- `.github/workflows/release-sensor.yml`

Main entry points: [`Sensor/adr_sensor/observer.py`](https://github.com/uber/adr/blob/main/Sensor/adr_sensor/observer.py) (Observer), [`Detection/guardrail/base_detector.py`](https://github.com/uber/adr/blob/main/Detection/guardrail/base_detector.py) (Detector abstraction), [`Detection/guardrail/adr_agent/adr_baseline.py`](https://github.com/uber/adr/blob/main/Detection/guardrail/adr_agent/adr_baseline.py) (ADR baseline), [`Detection/benchmark/benchmark_pack.py`](https://github.com/uber/adr/blob/main/Detection/benchmark/benchmark_pack.py) (Benchmark pack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensor["Sensor telemetry"]
  node_sensor_cli["Sensor CLI<br/>Python entry point<br/>[cli.py]"]
  node_observer["Observer<br/>collection coordinator<br/>[observer.py]"]
  node_parsers["Product parsers<br/>parser abstraction<br/>[base_parser.py]"]
  node_platform_paths["Platform discovery<br/>path discovery<br/>[platform_paths.py]"]
  node_agent_events["Unified agent events<br/>event schema"]
end

subgraph group_detection["Detection"]
  node_detector_entry["Detector runner<br/>Python entry point<br/>[main_detector.py]"]
  node_detector_base["Detector abstraction<br/>detector interface<br/>[base_detector.py]"]
  node_adr_baseline["ADR baseline<br/>dual-agent detector<br/>[adr_baseline.py]"]
  node_llamafirewall["LlamaFirewall baseline<br/>alternative detector"]
  node_detector_config["Detector config<br/>YAML configuration"]
  node_context_providers["Context providers<br/>local security services"]
  node_security_data[("Policies and threats<br/>security datasets<br/>[policy_store.yaml]")]
  node_provider_registry["Provider registry<br/>JSON registry"]
end

subgraph group_benchmark["ADR-Bench"]
  node_benchmark_entry["Benchmark runner<br/>Python entry point<br/>[main_benchmark.py]"]
  node_benchmark_pack["Benchmark pack<br/>scenario packaging<br/>[benchmark_pack.py]"]
  node_task_suites["Task suites<br/>adversarial tasks<br/>[load_suites.py]"]
  node_agent_pipeline["AgentDojo pipeline<br/>agent runtime<br/>[agent_pipeline.py]"]
  node_mcp_corpus[("Synthetic MCP corpus<br/>simulated tool servers")]
end

subgraph group_automation["Automation"]
  node_ci["CI and Sensor release<br/>GitHub Actions<br/>[ci.yml]"]
end

node_llm_apis(("LLM APIs<br/>external AI services"))

node_sensor_cli -->|"starts"| node_observer
node_observer -->|"discovers logs"| node_platform_paths
node_observer -->|"coordinates"| node_parsers
node_parsers -->|"normalizes to"| node_agent_events
node_detector_entry -->|"loads"| node_detector_config
node_detector_entry -->|"runs"| node_detector_base
node_detector_base -->|"implemented by"| node_adr_baseline
node_detector_base -->|"implemented by"| node_llamafirewall
node_adr_baseline -->|"retrieves context"| node_context_providers
node_context_providers -->|"reads"| node_security_data
node_provider_registry -->|"registers"| node_context_providers
node_adr_baseline -->|"reasons with"| node_llm_apis
node_benchmark_entry -->|"executes"| node_benchmark_pack
node_benchmark_pack -->|"packages"| node_task_suites
node_benchmark_pack -->|"runs"| node_agent_pipeline
node_agent_pipeline -->|"executes tools against"| node_mcp_corpus
node_benchmark_entry -.->|"evaluates detectors via"| node_detector_entry
node_agent_pipeline -->|"uses"| node_llm_apis
node_ci -.->|"validates and releases"| node_sensor_cli

click node_sensor_cli "https://github.com/uber/adr/blob/main/Sensor/adr_sensor/cli.py"
click node_observer "https://github.com/uber/adr/blob/main/Sensor/adr_sensor/observer.py"
click node_parsers "https://github.com/uber/adr/blob/main/Sensor/adr_sensor/parsers/base_parser.py"
click node_platform_paths "https://github.com/uber/adr/blob/main/Sensor/adr_sensor/utils/platform_paths.py"
click node_agent_events "https://github.com/uber/adr/blob/main/Sensor/adr_sensor/schemas/agent_event_schema.py"
click node_detector_entry "https://github.com/uber/adr/blob/main/Detection/main_detector.py"
click node_detector_base "https://github.com/uber/adr/blob/main/Detection/guardrail/base_detector.py"
click node_adr_baseline "https://github.com/uber/adr/blob/main/Detection/guardrail/adr_agent/adr_baseline.py"
click node_llamafirewall "https://github.com/uber/adr/blob/main/Detection/guardrail/llamafirewall_agent/llamafirewall_baseline.py"
click node_detector_config "https://github.com/uber/adr/blob/main/Detection/config_detector.yaml"
click node_context_providers "https://github.com/uber/adr/blob/main/Detection/context_providers/policy_store_server.py"
click node_security_data "https://github.com/uber/adr/blob/main/Detection/context_providers/data/policy_store.yaml"
click node_provider_registry "https://github.com/uber/adr/blob/main/Detection/context_providers_registry.json"
click node_benchmark_entry "https://github.com/uber/adr/blob/main/Detection/main_benchmark.py"
click node_benchmark_pack "https://github.com/uber/adr/blob/main/Detection/benchmark/benchmark_pack.py"
click node_task_suites "https://github.com/uber/adr/blob/main/Detection/benchmark/agentdojo/benchmarks/agentdojo/task_suite/load_suites.py"
click node_agent_pipeline "https://github.com/uber/adr/blob/main/Detection/benchmark/agentdojo/benchmarks/agentdojo/agent_pipeline/agent_pipeline.py"
click node_mcp_corpus "https://github.com/uber/adr/blob/main/Detection/mcp_servers_registry.json"
click node_ci "https://github.com/uber/adr/blob/main/.github/workflows/ci.yml"

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_sensor_cli,node_observer,node_parsers,node_platform_paths,node_agent_events toneBlue
class node_detector_entry,node_detector_base,node_adr_baseline,node_llamafirewall,node_detector_config,node_context_providers,node_security_data,node_provider_registry toneAmber
class node_benchmark_entry,node_benchmark_pack,node_task_suites,node_agent_pipeline,node_mcp_corpus toneMint
class node_ci toneRose
class node_llm_apis toneNeutral
```

## Components

### Sensor telemetry

Local endpoint telemetry normalization.

- [Sensor CLI](https://github.com/uber/adr/blob/main/Sensor/adr_sensor/cli.py): Python entry point · `Sensor/adr_sensor/cli.py`
- [Observer](https://github.com/uber/adr/blob/main/Sensor/adr_sensor/observer.py): collection coordinator · `Sensor/adr_sensor/observer.py`
- [Product parsers](https://github.com/uber/adr/blob/main/Sensor/adr_sensor/parsers/base_parser.py): parser abstraction · Normalizes logs from supported coding agents. · `Sensor/adr_sensor/parsers/base_parser.py`
- [Platform discovery](https://github.com/uber/adr/blob/main/Sensor/adr_sensor/utils/platform_paths.py): path discovery · `Sensor/adr_sensor/utils/platform_paths.py`
- [Unified agent events](https://github.com/uber/adr/blob/main/Sensor/adr_sensor/schemas/agent_event_schema.py): event schema · `Sensor/adr_sensor/schemas/agent_event_schema.py`

### Detection

Detector execution and security reasoning.

- [Detector runner](https://github.com/uber/adr/blob/main/Detection/main_detector.py): Python entry point · `Detection/main_detector.py`
- [Detector abstraction](https://github.com/uber/adr/blob/main/Detection/guardrail/base_detector.py): detector interface · `Detection/guardrail/base_detector.py`
- [ADR baseline](https://github.com/uber/adr/blob/main/Detection/guardrail/adr_agent/adr_baseline.py): dual-agent detector · `Detection/guardrail/adr_agent/adr_baseline.py`
- [LlamaFirewall baseline](https://github.com/uber/adr/blob/main/Detection/guardrail/llamafirewall_agent/llamafirewall_baseline.py): alternative detector · `Detection/guardrail/llamafirewall_agent/llamafirewall_baseline.py`
- [Detector config](https://github.com/uber/adr/blob/main/Detection/config_detector.yaml): YAML configuration · `Detection/config_detector.yaml`
- [Context providers](https://github.com/uber/adr/blob/main/Detection/context_providers/policy_store_server.py): local security services · Policy, threat intelligence, and source-analysis retrieval boundary. · `Detection/context_providers/policy_store_server.py`
- [Policies and threats](https://github.com/uber/adr/blob/main/Detection/context_providers/data/policy_store.yaml): security datasets · `Detection/context_providers/data/policy_store.yaml`
- [Provider registry](https://github.com/uber/adr/blob/main/Detection/context_providers_registry.json): JSON registry · `Detection/context_providers_registry.json`

### ADR-Bench

Adversarial task and MCP simulation runtime.

- [Benchmark runner](https://github.com/uber/adr/blob/main/Detection/main_benchmark.py): Python entry point · `Detection/main_benchmark.py`
- [Benchmark pack](https://github.com/uber/adr/blob/main/Detection/benchmark/benchmark_pack.py): scenario packaging · `Detection/benchmark/benchmark_pack.py`
- [Task suites](https://github.com/uber/adr/blob/main/Detection/benchmark/agentdojo/benchmarks/agentdojo/task_suite/load_suites.py): adversarial tasks · Banking, Slack, travel, and workspace task suites. · `Detection/benchmark/agentdojo/benchmarks/agentdojo/task_suite/load_suites.py`
- [AgentDojo pipeline](https://github.com/uber/adr/blob/main/Detection/benchmark/agentdojo/benchmarks/agentdojo/agent_pipeline/agent_pipeline.py): agent runtime · Composes planning, injection detection, and tool execution. · `Detection/benchmark/agentdojo/benchmarks/agentdojo/agent_pipeline/agent_pipeline.py`
- [Synthetic MCP corpus](https://github.com/uber/adr/blob/main/Detection/mcp_servers_registry.json): simulated tool servers · Local enterprise-tool fixtures and risky server implementations. · `Detection/mcp_servers_registry.json`

### Automation

- [CI and Sensor release](https://github.com/uber/adr/blob/main/.github/workflows/ci.yml): GitHub Actions · `.github/workflows/ci.yml`

### Other components

- **LLM APIs**: external AI services · Anthropic and OpenAI APIs support ADR reasoning.

## Connections

- Sensor CLI → Observer: starts
- Observer → Platform discovery: discovers logs
- Observer → Product parsers: coordinates
- Product parsers → Unified agent events: normalizes to
- Detector runner → Detector config: loads
- Detector runner → Detector abstraction: runs
- Detector abstraction → ADR baseline: implemented by
- Detector abstraction → LlamaFirewall baseline: implemented by
- ADR baseline → Context providers: retrieves context
- Context providers → Policies and threats: reads
- Provider registry → Context providers: registers
- ADR baseline → LLM APIs: reasons with
- Benchmark runner → Benchmark pack: executes
- Benchmark pack → Task suites: packages
- Benchmark pack → AgentDojo pipeline: runs
- AgentDojo pipeline → Synthetic MCP corpus: executes tools against
- Benchmark runner → Detector runner: evaluates detectors via
- AgentDojo pipeline → LLM APIs: uses
- CI and Sensor release → Sensor CLI: validates and releases