# Architecture Overview

Capsule Security is an API-first platform for governing the runtime behavior of AI agents across your enterprise. The platform is composed of three core services — the **Portal**, the **Runtime Agent Security Service**, and the **Red Teaming Service** — connected through a strict, well-documented API contract and protected by defense-in-depth security controls.

This guide describes the high-level architecture, the responsibilities of each component, and the security primitives that underpin the platform.

## System Topology


```
┌────────────────────────────────────────────────────────────────────────┐
│                              Internet                                  │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                          ┌────────▼────────┐
                          │       WAF       │   ◀── DDoS, OWASP Top 10
                          └────────┬────────┘
                                   │
                          ┌────────▼────────┐
                          │ Firewall + IDS  │   ◀── L3/L4 + L7 inspection
                          └────────┬────────┘
                                   │
┌──────────────────────────────────▼─────────────────────────────────────┐
│                            Capsule VPC                                 │
│                                                                        │
│   ┌──────────────┐    ┌────────────────────┐    ┌──────────────────┐   │
│   │              │    │                    │    │                  │   │
│   │    Portal    │◀──▶│  Runtime Agent     │◀──▶│   Red Teaming    │   │
│   │  (Web + API) │    │  Security Service  │    │     Service      │   │
│   │              │    │                    │    │                  │   │
│   └──────┬───────┘    └─────────┬──────────┘    └─────────┬────────┘   │
│          │                      │                         │            │
│          └──────────────────────┼─────────────────────────┘            │
│                                 │                                      │
│                  ┌──────────────▼──────────────┐                       │
│                  │  PostgreSQL  +  Audit Log   │   ◀── Encrypted       │
│                  │  (encryption at rest, KMS)  │       at rest         │
│                  └─────────────────────────────┘                       │
└────────────────────────────────────────────────────────────────────────┘
                                   ▲
                                   │  TLS 1.3
            ┌──────────────────────┼───────────────────────┐
            │                      │                       │
     ┌──────▼──────┐        ┌──────▼──────┐        ┌───────▼──────┐
     │     EDR     │        │  Agentic    │        │   Customer   │
     │ (CrowdStrike│        │    APIs     │        │    Hooks     │
     │  / Defender)│        │  (OpenAI,   │        │  (OpenClaw)  │
     │             │        │  Anthropic) │        │              │
     └─────────────┘        └─────────────┘        └──────────────┘
```

## Core Services

### Portal

The Portal is the customer-facing control plane. It hosts the web application used by SOC analysts, security engineers, and executives, and exposes the public **GraphQL API** that all programmatic clients consume.

Responsibilities:

- Inventory management — agents, tools, data sources, users, channels, skills
- Observability — audit log search, session investigation, detection review
- Policy authoring and management
- Integration configuration — EDR, identity providers, agentic platforms, MDM
- Role-based access control and tenant administration


The Portal is the **only** ingress for human users. All write operations are mediated by the same GraphQL API exposed to programmatic clients — there is no privileged "admin path."

### Runtime Agent Security Service

The Runtime Agent Security Service is the policy-enforcement and detection plane. It evaluates agent activity against your configured policies in real time, generates detections, and produces structured audit events.

Responsibilities:

- Policy evaluation against agent prompts, responses, tool calls, and reasoning
- Detection generation (prompt injection, data leakage, dangerous actions, sensitive-data access)
- Real-time event ingestion from connected agentic platforms, EDR, and webhook hooks
- Finding and issue lifecycle management
- Emission of audit events to the platform database and downstream SIEMs


The service is stateless at the request level — all durable state lives in the platform database, allowing horizontal scaling and zero-downtime upgrades.

### Red Teaming Service

The Red Teaming Service continuously and on-demand probes your configured agents and policies to validate their resilience against adversarial behavior.

Responsibilities:

- Automated attack campaigns against deployed agents (prompt injection, jailbreaks, data exfiltration attempts, dangerous actions)
- Policy regression testing — verifying that policy changes don't degrade existing protections
- Assessment reporting and scoring
- Continuous coverage across new agent platforms and updated attack techniques


Findings from the Red Teaming Service feed back into the Runtime Agent Security Service as evidence for policy tuning and detection improvements.

## Integrations

Capsule connects to the surrounding enterprise security and AI ecosystem through three integration surfaces.

### EDR Integration

Capsule integrates with leading Endpoint Detection and Response platforms to correlate agent activity with endpoint posture and to enrich detections with host context.

| EDR Platform | Integration |
|  --- | --- |
| **CrowdStrike Falcon** | Real-time event ingestion and host enrichment |
| **Microsoft Defender for Endpoint** | Real-time event ingestion and host enrichment |


EDR telemetry is correlated with agent sessions to produce composite detections — for example, flagging an AI-assisted coding session that runs on a host with active malware indicators.

### Agentic API Integration

Capsule attaches directly to enterprise agentic platforms via their native APIs, capturing every session, message, tool call, and reasoning step for analysis.

Supported platforms include OpenAI Enterprise / ChatGPT Enterprise, Anthropic Claude (Code and Cowork), Microsoft 365 Copilot, Azure AI Foundry, Google Gemini Enterprise, Salesforce Agentforce, AWS Bedrock, and Microsoft Power Platform.

### Hooks

For runtime intercept use cases that require sub-second policy decisions, Capsule provides a hook-based integration model. Hooks are lightweight shims embedded in the agent runtime (for example, the OpenClaw hook for Claude Code) that forward each event to the Runtime Agent Security Service and apply the returned policy decision before the agent takes action.

Hooks are designed to fail open or fail closed per your configuration, giving you precise control over the availability/security tradeoff.

## API-First Approach

Every capability in the Portal is built on top of the same GraphQL API that is exposed to customers. There is no private back-channel and no admin-only surface.

Consequences:

- **Reproducibility** — anything a human can do in the UI can be scripted against the API
- **Auditability** — every privileged action flows through the same authorization and audit pipeline
- **Composability** — customers can build their own dashboards, automations, and SOC playbooks against the public API
- **Parity** — UI features and API features ship together; the API is never an afterthought


The full GraphQL schema, along with webhook event schemas, is published in the [API Reference](/apis/agent).

## Identity, Authentication, and Authorization

### Strict Access Control — No Password Policy

Capsule does **not** maintain a username/password authentication path for customer users. There are no passwords to rotate, leak, phish, or brute-force, because there are no passwords in the system.

Authentication is exclusively delegated to your enterprise Identity Provider via Single Sign-On.

### Single Sign-On (SSO)

All customer authentication is mediated by SAML 2.0 or OIDC SSO against your IdP (Okta, Azure Entra, Google Workspace, Ping, etc.). This means:

- User lifecycle (joiner / mover / leaver) is governed centrally by your IdP
- MFA, conditional access, and device-trust policies enforced by your IdP apply transparently to Capsule
- Deprovisioning a user in your IdP immediately revokes their Capsule access on the next session


### Role-Based Access Control (RBAC)

Inside the Portal, authorization is enforced by a tenant-scoped RBAC model. Roles are mapped to scoped permissions across the GraphQL API, and every resolver enforces these permissions independently — there is no "trusted UI" assumption.

Tenant isolation is enforced at the database layer: every query includes an explicit `tenant_id` predicate, with defense-in-depth checks above the ORM layer. Cross-tenant data access is structurally prevented, not merely permission-gated.

## Data Protection

### Encryption at Rest

All persistent data — audit events, policy configurations, agent inventory, integration credentials — is encrypted at rest using **AES-256**.

| Deployment Model | Key Management |
|  --- | --- |
| Enterprise SaaS | Capsule-managed keys via AWS KMS |
| Dedicated SaaS with BYOK | Customer-managed keys (BYOK) via AWS KMS |
| Customer Hosted VPC | Customer-managed keys in your AWS account |


### Encryption in Transit (TLS)

**TLS 1.3** is enforced for every network connection — Portal sessions, GraphQL API calls, webhook deliveries, EDR event streams, agentic platform polling, and outbound SIEM forwarding. Older TLS versions and weak cipher suites are rejected.

Internal service-to-service communication inside the VPC is also TLS-encrypted; the platform never relies on a "trusted internal network" assumption.

## Network Architecture

### VPC Isolation

The Capsule platform runs inside a dedicated **Virtual Private Cloud (VPC)**. Data plane services run in private subnets with no direct internet access. All egress is routed through controlled NAT gateways with explicit allowlists for required external endpoints.

For **Customer Hosted VPC** deployments, the data plane runs entirely inside your own VPC; the Capsule control plane connects in via PrivateLink without traversing the public internet.

### Web Application Firewall (WAF)

A **WAF** fronts all public ingress to the Portal and GraphQL API. The WAF provides:

- OWASP Top 10 protection (SQL injection, XSS, command injection, etc.)
- Rate limiting and abuse protection
- Geographic and IP-based filtering as configured per tenant
- DDoS mitigation at the application layer


### Firewall and Intrusion Detection (IDS)

Beneath the WAF, the VPC is protected by a stateful **network firewall** and a network **Intrusion Detection System (IDS)**. The firewall enforces a default-deny posture on both north-south and east-west traffic. The IDS performs signature- and anomaly-based detection on traffic crossing the VPC boundary, with alerts routed to the Capsule SRE on-call rotation.

## Audit Logs

Every action performed by every user, agent, integration, and internal service produces a structured audit event. These events are stored in the platform database with full-text indexing and are immediately searchable through the Portal's Observability view.

Audit logs cover:

- All authentication and authorization events
- All Portal user actions (policy changes, integration configuration, role changes, exports)
- All API calls — both human and programmatic
- All agent session events ingested from connected platforms
- All policy evaluations and detections
- All findings, issues, and red-team campaigns


Audit data can be forwarded in real time to your SIEM (Splunk, Microsoft Sentinel) via the Webhook Events API. For full details on event schemas, retention, and SIEM integration, see [Auditing and Logging](/guides/auditing-and-logging).

## Compliance

The architecture described above underpins our compliance posture:

- **SOC 2 Type 2** — annually audited
- **ISO 27001** — information security management
- **GDPR** — data subject rights and EU data residency options


## Further Reading

- [Deployment Options](/guides/deployment-overview) — Enterprise SaaS, Dedicated SaaS with BYOK, Customer Hosted VPC
- [Auditing and Logging](/guides/auditing-and-logging) — audit event schemas and SIEM forwarding
- [Agent Management](/guides/agent-management) — onboarding agents and policy management
- [API Reference](/apis/agent) — full GraphQL schema