AISecOps Reference Architecture Diagram
AISecOps Interceptor v1.0.0 reference architecture with local enforcement mode, MCP policy proxy, agent identity layer, structured plan extraction, policy enforcement, runtime budgets, replay diff, and evidence export.

Current OSS reference: AISecOps Interceptor v1.0.0 - Replay Diff Engine + Evidence Export.

The current architecture adds agent identity, local enforcement mode, MCP policy proxy, replay diff, compliance evidence export, and runtime governance APIs so runtime decisions can be reviewed after the fact instead of only logged.

Reference Architecture

A structured blueprint for deploying runtime governance across agentic AI systems - from structured plan extraction to evidence export.

aisecops.net · Last updated March 2026 · ~7 min read

What This Architecture Addresses

Most agentic AI deployments today have no runtime control plane. The LLM is called directly, tool permissions are broad, outputs are passed through without inspection, planning and execution are tightly coupled, and there is no replayable structured audit trail.

This works fine in a demo. It does not work in production.

The AISecOps reference architecture describes where security controls must be placed in an agentic AI system, what each control does, and how they compose into a runtime enforcement layer that is framework-agnostic — the same architecture applies whether your agent runtime is OpenClaw, LangGraph, CrewAI, AutoGen, or a custom system.

The architecture is organized around four control layers that correspond directly to the four threat layers described in the Threat Model.

The Four Control Layers

flowchart TD

A[Any Agent Framework]

A --> B[Agent Runtime]
B --> C[Structured Plan Extraction]
C --> D[Capability Validation]
D --> E[Policy Enforcement]
E --> F[Runtime Budgets]
F --> G[Runtime Controls]
G --> H[Execution]
H --> I[Audit Events]
I --> J[Replay Engine]
J --> K[Replay Diff]
K --> L[Evidence Export]

Each layer addresses a distinct threat surface. No single layer is sufficient. The architecture requires all four operating together.

Agent Runtime and Local Enforcement

Threat addressed: Prompt injection, indirect injection via retrieval, memory poisoning
Position in runtime: Before the LLM is called

AISecOps Interceptor v1.0.0 introduces an optional local enforcement mode before cloud model invocation. This lightweight precheck layer can block obvious prompt injection, dangerous instruction patterns, identity mismatches, and basic data exfiltration attempts before requests ever reach the model.

The first enforcement boundary sits at the edge of the model’s context window. Everything that enters the model — user prompts, retrieved documents, tool results, memory reads, agent messages — is treated as untrusted input until it has been inspected.

Prompt Guard

Scans all input content before it reaches the model. Detects:

The prompt guard may run locally, at the edge, or inside the guarded LLM pipeline depending on deployment topology.

Detected violations raise LLMGuardViolationError and halt the pipeline before the model is called. The event is emitted with full context: input source, detection type, severity.

Output Guard

Scans every model response before it reaches the agent runtime. Detects:

Detected violations suppress the response and emit a structured security event.

Runtime Context Builder

Constructs a typed RuntimeContext object that carries provenance and classification metadata through the full pipeline:

This context object is passed from the prompt guard through to the decision engine, ensuring that every security decision is made with full awareness of where the input came from and what it contains.

Capability Validation and MCP Policy Proxy

Threat addressed: Tool execution abuse, unauthorized tool invocation, tool chaining
Position in runtime: Before any tool or API is executed

The second enforcement boundary governs what the agent is permitted to do.

AISecOps Interceptor v1.0.0 formalizes capability-gated execution before policy enforcement. Agents do not directly invoke tools - they request execution plans that must first pass capability validation and MCP policy proxy checks.

Tool access is not a binary permission — it is a policy surface. The capability control layer evaluates every tool call against a declarative policy before execution is permitted.

Policy Engine

Evaluates tool calls against an ordered set of declarative rules. Each rule matches on:

The first matching rule wins. Capability validation occurs before policy enforcement.

If no rule matches, fallback policy logic applies — covering blocked tools, dangerous argument patterns, allowlists, and monitored tools.

Example rule configuration:

policy = PolicyEngine(
    {
        "rules": [
            {"tool_name": "restart_service", "agent_name": "ops_agent", "action": "require_approval"},
            {"tool_name": "read_customer", "sensitivity_level": "high", "action": "block"},
            {"tool_name": "send_email", "action": "require_approval"},
        ]
    }
)

Policy decisions are scoped to verified runtime identity — not to claimed identity in message content. An agent cannot grant itself permissions it was not provisioned with at runtime.

Capability Gate

The capability gate validates whether the calling agent has been granted access to request a specific class of action.

Capabilities are declarative and externalized into YAML bundles:

The capability gate executes before policy enforcement and prevents agents from bypassing runtime authorization through prompt manipulation or tool chaining.

Runtime Risk Evaluation

Risk metadata is attached to execution plans and propagated through evaluation, approval, execution, and audit events.

Risk classification may be derived from:

Risk metadata feeds:

Runtime Controls and Agent Identity

Threat addressed: Approval bypass, irreversible actions, privilege escalation
Position in runtime: At the point of execution

The third enforcement boundary is the runtime control plane. AISecOps Interceptor v1.0.0 explicitly separates planning, evaluation, and execution and associates each trace with an agent identity layer.

No model response directly executes tools.

flowchart TD

A[Execution Plan]

A --> B[Evaluator]

B --> C{Decision}

C -->|Allow| D[Deterministic Executor]
C -->|Block| E[Reject — Audit Event]
C -->|Require Approval| F[Approval Workflow]

F --> G{Human Decision}

G -->|Approved| D
G -->|Rejected| E

D --> H[Tool / API Execution]
H --> I[Audit Event]

Decision Engine

Takes the RuntimeContext, policy enforcement result, and risk classification as inputs. Returns a typed decision: allow, block, require_approval, dry_run, or explain. The decision phase and execution phase are explicitly separate — no tool executes without passing through the decision engine first.

Execution Gate

The deterministic execution boundary. Approved or allowed execution plans are executed here. Blocked plans are rejected with structured reasons. Approval-required plans are suspended pending human decision. Runtime budgets are checked here as part of the allow or block decision.

Approval Workflow

Human-in-the-loop gating for sensitive actions:

  1. Agent requests a tool call that policy marks require_approval
  2. Interceptor creates a scoped approval_id bound to the specific tool call context
  3. Human reviews and approves or rejects
  4. Approved calls are replayed through the execution gate with the approval_id
  5. The approval decision is recorded as a distinct audit event

Approval IDs are scoped to the exact tool call for which they were issued. Replay attacks — reusing an approval ID for a different call — are rejected.

Replay Engine, Replay Diff, and Evidence Export

Threat addressed: Audit blindness, policy drift, forensic gaps
Position in runtime: All layers — every decision point emits an event

The fourth layer is not a gate — it is a thread that runs through the entire runtime. Every security decision emits a structured event. The audit trail is the forensic record of the decision chain, not a log of what happened.

Structured Event Model

Events are emitted at every enforcement boundary:

EventLayerCarries
prompt_allowed / prompt_blockedL1input source, detection type, severity
output_allowed / output_blockedL1response hash, detection type, data classification
tool_allowedL2/L3tool name, agent name, matched rule, risk level
tool_blockedL2/L3tool name, agent name, block reason, matched rule
tool_approval_requiredL3tool name, agent name, approval ID
approval_issuedL3approval ID, tool call context
approval_granted / approval_rejectedL3approval ID, decision timestamp, reviewer

Every event carries agent_name, tool_name, matched_rule, sensitivity_level, data_classification, and timestamp. The audit trail enables:

AISecOps Interceptor v1.0.0 standardizes replayable structured audit logging using JSONL-compatible event schemas and adds replay diff plus compliance evidence export.

Events SHOULD include:

The same event stream now powers three investigation surfaces:

Full Runtime Security Pipeline

This diagram shows the complete flow from agent prompt to tool execution across all four layers.

flowchart TD

A[Agent Runtime / Framework]

A --> B[Framework Adapter]

B --> C[Optional Local / Edge Guard]

C --> D[Prompt Guard]

D --> E[Guarded LLM Pipeline]

E --> F[LLM Provider]

F --> G[Output Guard]

G --> H[Runtime Context Builder]

H --> I[Capability Validation]

I --> J[Policy Enforcement]

J --> K[Runtime Controls]

K --> L[Execution]

L --> M[Audit Events]

M --> N[Replay Engine]

N --> O[Replay Diff]

O --> P[Evidence Export]

M --> Q{Governance Result}
Q -->|Allow| R[Deterministic Executor]
Q -->|Block| S[Reject Request]
Q -->|Require Approval| T[Approval Workflow]

T --> R

R --> U[Tool / API Execution]

L --> V[Structured Audit Event]
U --> V

Adapters are thin. All security logic lives inside the interceptor core. Framework integrations do not contain capability validation, policy enforcement, approval, execution governance, and audit stay in the runtime.

Framework Integration Model

The architecture is framework-agnostic by design. Agent frameworks plug in via thin adapters that translate framework-specific tool call representations into a common AISecOps execution contract.

flowchart LR

A[LangGraph Agent]
B[OpenClaw Agent]
C[CrewAI Agent]
D[Custom Agent]

A --> E[LangGraph Adapter]
B --> F[OpenClaw Adapter]
C --> G[CrewAI Adapter]
D --> H[Generic Adapter]

E --> I[AISecOps Interceptor Core]
F --> I
G --> I
H --> I

The adapter layer translates framework-specific execution requests into a normalized execution plan consumed by the AISecOps runtime control plane.

Design rule: Adapters translate. They do not enforce. Security logic lives in the core, not in the integration layer.

Current adapters: LangGraph-style, OpenClaw-style, generic.
Roadmap: native integrations for production LangGraph and OpenClaw execution paths.

Deployment Model

The AISecOps Interceptor is designed to deploy as a library embedded in the agent runtime, not as a network proxy or sidecar. This means:

AISecOps additionally supports optional local / edge enforcement where lightweight security checks execute before cloud model invocation.

The FastAPI wrapper is provided for local testing and API-based integration scenarios. It is not the recommended production deployment model — direct library integration is preferred.

What Is Not Yet in the Architecture

An honest architecture document names what is missing.

Replay and forensic tooling. The current implementation emits structured JSONL audit events but does not yet include a full replay engine, anomaly correlation workflow, or historical execution debugger. This is an active roadmap item.

Policy provider abstraction beyond YAML. The current policy engine supports YAML-defined rules and declarative Python configuration. A policy provider abstraction — enabling dynamic policy from OPA, a database, or a control plane API — is a near-term priority.

Distributed policy reconciliation. Local / edge guards currently operate with bundled policy patterns. Centralized synchronization and reconciliation across distributed runtimes is still evolving.

Native real framework integrations. The current LangGraph and OpenClaw adapters are style-compatible implementations. Native integration with the production execution paths of these frameworks is on the roadmap.

Behavioural baseline and anomaly detection. The current architecture enforces explicit policy. It does not yet detect anomalous agent behaviour that falls within policy bounds but deviates from established baselines. This is a longer-horizon capability.

Where to Go From Here

This page describes the architecture. The Threat Model explains what each layer defends against. The Open Source page shows the working implementation across all four layers, including execution splitting, explainable runtime decisions, dry-run evaluation, structured JSONL audit logging, and optional local enforcement.

If you are evaluating this architecture for an enterprise deployment, the whitepaper covers governance requirements, compliance considerations, and adoption patterns in detail.

V

Viplav Fauzdar

Building AISecOps as a discipline and open-source reference implementation. Java/Spring + Python practitioner. Focused on practical, shipped security for agentic AI — not slide decks.

Medium ↗ GitHub ↗ LinkedIn ↗

On This Page

Related Pages