# 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 **Harvester** - built around 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 │ │ │ │ (Web + API) │ │ Security Service │ │ │ │ │ │ │ │ │ │ │ │ sync: inline policy │ │ │ │ │ │ async: batch analysis │ │ │ └──┬───────┬───┘ └─────┬───────────┬──────┘ │ │ │ │ │ │ │ │ │ ┌──▼──────────────────────────────────▼─────┐ │ │ │ │ │ Pub/Sub message bus │ │ │ │ │ └────────────────┬──────────────────────────┘ │ │ │ │ │ │ │ │ │ ┌─────────▼────────┐ │ │ │ │ │ Harvester │ │ │ │ │ │ (integration │ │ │ │ │ │ ingestion) │ │ │ │ │ └─────────┬────────┘ │ │ │ │ │ │ │ │ └──────────┬──────────┴────────────────────────────────┘ │ │ │ │ │ ┌──────────────▼──────────────┐ │ │ │ PostgreSQL + Audit Log │ ◀── Encrypted at rest │ │ │ (encryption at rest, KMS) │ │ │ └─────────────────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘ ▲ │ TLS 1.3 ┌─────────────────┬───────┴─────────┬─────────────────┐ │ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ EDR │ │ Agentic │ │ Identity │ │ Customer │ │ (CrowdStrike│ │ APIs │ │ Providers │ │ Hooks │ │ / Defender)│ │ (OpenAI, │ │ (Okta, │ │ (OpenClaw) │ │ │ │ Anthropic) │ │ Entra) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ``` ## 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, generates detections, and produces structured audit events. It runs the same policy and detection engine in two modes: - **Synchronous** - inline evaluation on the request path. Hook-based integrations call the service per event and block on the verdict, so a decision is returned before the agent acts. This is the sub-second path, and it is the only one that can prevent an action rather than record it. - **Asynchronous** - batch evaluation off a message bus. When the Harvester finishes an ingestion run it hands the freshly ingested inventory and sessions over, and the service scans them in the background: findings, detections, and policy processing across every agent and entity in the tenant. Splitting the two keeps analysis cost off the latency-sensitive path. Inline evaluation stays fast because deep analysis is not competing with it, and batch analysis can be as thorough as it needs to be because nothing is waiting on it. Async work that fails repeatedly moves to a dead-letter queue rather than blocking the pipeline, and is replayable once the cause is resolved. Responsibilities: - Policy evaluation against agent prompts, responses, tool calls, and reasoning - Detection generation (prompt injection, data leakage, dangerous actions, sensitive-data access) - Findings analysis - posture scanning of agents, tools, data sources, and their configuration - 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. #### Layered Detection with Small Language Models Detection runs as a two-layer model cascade rather than a single pass. The first layer is a **small language model (SLM)**. It sees every session and acts as a cheap, high-recall triage filter, tuned to escalate only high-confidence signals and skip anything ambiguous. Only what it escalates reaches the second layer - a larger model that does the expensive reasoning and produces the final detection with its evidence, severity, and rationale. The cascade is what makes full-coverage detection economically viable. Running the large model over every session would be prohibitively expensive; running only the small model would be imprecise. Splitting them keeps cost proportional to suspicious activity rather than to total traffic, and keeps the quality of an escalated verdict independent of how much benign traffic passed through the filter. Both layers are configured per deployment, so the models can be upgraded, or pinned for regulatory reasons, without changing detection logic. ### Harvester The Harvester is the ingestion plane. It consumes synchronization requests from an internal message bus and pulls data from your connected platforms, on a schedule and on demand. Responsibilities: - Full synchronization of a platform integration - agents, tools, users, skills, sessions, and activity - Targeted synchronization of a single agent, for example when an analyst requests a refresh from the Portal - Normalization of platform-specific payloads into the Capsule resource model - Reconciliation of resources that have disappeared upstream - Handing off completed ingestion runs to the Runtime Agent Security Service for analysis Ingestion runs are scoped to a single tenant and integration. A run that fails repeatedly is moved to a dead-letter queue rather than blocking the pipeline, and can be replayed once the underlying cause is resolved. ## Integrations Capsule connects to the surrounding enterprise security and AI ecosystem through four 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. ### Identity Provider Integration Capsule reads your directory for two distinct things: user and group context, available from every supported IdP, and agent identity records, which today are specific to Microsoft Entra ID. | Identity Provider | What Capsule reads | | --- | --- | | **Okta** | Users and their group memberships, for ownership and access context | | **Microsoft Entra ID** | Users and groups, plus agent identity records (Entra Agent ID) | #### Agent Identity Enrichment (Microsoft Entra ID) Agent identity enrichment is what turns "an agent exists" into "this agent is owned by this person, runs under this directory identity, and is still active." Capsule matches an agent to its Entra identity by the object id the agent's own platform reports, falling back to an unambiguous display name match when a platform reports no id, and surfaces the identity's owners, enabled state, and the application blueprint the agent was created from. An agent whose Entra identity has been disabled shows up as such in the Portal with no manual correlation. These reads are opt-in: a tenant that has not granted the directory permissions still gets a successful user ingestion, with the agent identity slice skipped rather than failing the run. Okta-backed tenants get users and group memberships for ownership and access context. Agent identity records are not available from Okta today, so the enrichment described above is Entra-specific. ### 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 and issues Detections, findings, and policy violations are exported continuously to a Capsule-managed S3 bucket that your SIEM ingests from. 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