Architecture Overview¶

ARX is structured as a governance proxy between AI agents and the security tools they operate on. Every agent action passes through a three-layer architecture that enforces policy, captures audit data, and manages credentials. No agent communicates directly with a security tool API.

Three-Layer Architecture¶

┌─────────────────────────────────────────────────────┐
│                  AGENT RUNTIME                      │
│                                                     │
│   ┌──────────┐  ┌──────────┐  ┌──────────────┐     │
│   │ Triage   │  │ Remediate│  │ Compliance   │     │
│   │ Agent    │  │ Agent    │  │ Agent        │     │
│   └────┬─────┘  └────┬─────┘  └──────┬───────┘     │
│        │              │               │             │
│        └──────────────┼───────────────┘             │
│                       │                             │
│              ARX SDK (agentvault)                    │
│              POST /v1/sdk/execute                    │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│              ARX GOVERNANCE LAYER                    │
│                                                     │
│   ┌──────────────┐  ┌───────────────┐               │
│   │ Policy       │  │ Audit         │               │
│   │ Engine       │  │ Logger        │               │
│   │ (INV-002)    │  │ (INV-001)     │               │
│   └──────┬───────┘  └───────┬───────┘               │
│          │                  │                       │
│   ┌──────┴───────┐  ┌──────┴───────┐               │
│   │ Approval     │  │ Drift        │               │
│   │ Router       │  │ Detector     │               │
│   └──────────────┘  └──────────────┘               │
│                                                     │
│   ┌──────────────┐  ┌───────────────┐               │
│   │ Secrets      │  │ Connector     │               │
│   │ Vault        │  │ Registry      │               │
│   │ (INV-005)    │  │               │               │
│   └──────┬───────┘  └───────┬───────┘               │
│          │                  │                       │
└──────────┼──────────────────┼───────────────────────┘
           │                  │
           ▼                  ▼
┌─────────────────────────────────────────────────────┐
│               SECURITY TOOLS                         │
│                                                     │
│   CrowdStrike   Splunk   Okta   Jira   Wiz   ...   │
│   SentinelOne   Sentinel Duo    SNOW   Prisma       │
│   Carbon Black  Elastic  Entra  PD     AWS SH       │
└─────────────────────────────────────────────────────┘

Layer 1: Agent Runtime¶

AI agents run in their own compute environment. They import the ARX SDK (agentvault) and use ARXClient to interact with security tools. The SDK is a thin HTTP client that serializes operation requests and sends them to the ARX API at POST /v1/sdk/execute.

Agents do not hold credentials for any security tool. They hold only an ARX API key, which identifies the agent and its organization. All tool-specific authentication is handled by the governance layer.

Layer 2: ARX Governance Layer¶

The governance layer is the core of the platform. It receives every operation request from the SDK and executes the intercept-evaluate-log pattern before the operation reaches any downstream tool.

Layer 3: Security Tools¶

The target tool APIs (CrowdStrike Falcon, Splunk REST, Okta Management, etc.) are accessed only by the governance layer. Connectors within ARX map abstract operations to specific API endpoints, handle authentication flows (OAuth2 client credentials, API tokens, SAML assertions), and normalize response formats.

The Intercept Pattern (INV-002)¶

Every operation routed through BaseConnector.execute() follows a six-step execution flow. This is the INV-002 intercept pattern.

Agent Request
     │
     ▼
┌─────────────────┐
│ 1. Load         │  Credentials retrieved from encrypted vault.
│    Credentials  │  Decrypted at runtime. Never returned to agent.
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 2. Evaluate     │  Policy engine assesses: agent_id, org_id,
│    Policy       │  connector, operation, session_context.
│                 │  Returns: verdict, risk_score, policy_id.
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. Write Audit  │  Immutable audit event written before execution.
│    Entry        │  Includes verdict, risk score, policy match.
│    (INV-001)    │  Append-only. Cannot be modified or deleted.
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. Route on     │  PERMIT  → proceed to step 5.
│    Verdict      │  ESCALATE → create approval request, notify
│                 │             reviewers, block until resolved.
│                 │  DENY    → raise PermissionDeniedError.
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 5. Execute      │  Connector calls the target tool API with
│    Operation    │  injected credentials and operation params.
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 6. Log Result   │  Execution result appended to the audit event.
│                 │  Full response payload recorded.
└─────────────────┘

Steps 3 and 6 together ensure that the audit trail captures both the intent (what was attempted) and the outcome (what happened). If a DENY occurs at step 4, the audit record reflects the denied attempt with no result payload.

Policy Evaluation Flow¶

The policy engine (PolicyEngine.evaluate()) accepts five inputs:

The engine evaluates against the organization's policy rules in priority order. Each rule specifies match criteria (connector, operation pattern, agent identity, risk level) and a verdict. The first matching rule wins.

If no rule matches, the engine applies the organization's default verdict. Most organizations configure a default of PERMIT for read operations and ESCALATE for write operations.

The session context enables behavioral analysis. The engine compares the current action sequence against the agent's declared intent manifest. If the agent is performing operations outside its declared scope, the risk score is elevated, which may trigger different policy matches.

Audit Logging (INV-001)¶

Audit events are written to an append-only table in the Supabase PostgreSQL database. The schema enforces immutability: no UPDATE or DELETE operations are permitted on audit records. Each event contains:

• Event ID -- UUID, generated at write time.
• Timestamp -- Server-side UTC timestamp.
• Agent ID -- The agent that initiated the action.
• Organization ID -- Tenant isolation boundary.
• Connector -- The target tool connector.
• Operation -- The specific operation attempted.
• Verdict -- PERMIT, ESCALATE, or DENY.
• Risk Score -- Integer score computed by the policy engine.
• Policy ID -- The rule that produced the verdict (if any).
• Result -- The execution result payload (for permitted operations).

Audit data can be exported in real time to external systems via Splunk HEC, Microsoft Sentinel, syslog, or webhooks for integration with existing security monitoring and SIEM infrastructure.

Credential Injection (INV-005)¶

Agents never receive or store credentials for security tools. The credential lifecycle is managed entirely within the governance layer:

1. Storage. Connector credentials (OAuth2 client ID/secret pairs, API tokens, service account keys) are stored in the ARX secrets vault. Credentials are encrypted at rest using organization-specific encryption keys. Organizations can optionally bring their own key material via AWS KMS, Azure Key Vault, or GCP KMS.

2. Retrieval. When BaseConnector.execute() runs, it calls _load_credentials(), which decrypts the stored credentials. Credentials exist in plaintext only within the execution context of a single operation and are not cached across requests.

3. Injection. Decrypted credentials are passed to _execute_impl(), the connector-specific implementation method. Each connector uses the credentials to authenticate with the target tool API (e.g., CrowdStrike OAuth2 token exchange, Splunk bearer token).

4. Rotation. Credential rotation is handled through the ARX console or API. When credentials are updated, all subsequent operations use the new values. No agent code changes are required.

Infrastructure¶

ARX is deployed on Aptible, which provides managed container infrastructure with SOC 2 Type II compliance, encryption at rest, and network isolation. The platform runs in both AWS and Microsoft Azure regions. All inter-service communication uses TLS 1.2+. IP allowlisting restricts API access to approved network ranges.

Tenant Isolation¶

Every database query is scoped to an org_id. Row-Level Security (RLS) policies in PostgreSQL enforce that users and API keys can only access data belonging to their organization. Agents, connectors, policies, audit events, and approval requests are all tenant-isolated at the database level.