# Auditing and Logging

Capsule Security provides comprehensive auditing and logging capabilities for AI agent activity across your organization. This guide covers the platform's native observability features and how to export security events to your centralized SIEM.

## Platform Auditing and Logging

### Audit Event Types

Every AI agent interaction monitored by Capsule generates structured audit events. These events are persisted in the platform database and are immediately available for search, filtering, and investigation.

| Event Type | Description |
|  --- | --- |
| **Session Started** | An AI agent session begins |
| **User Message** | A user sends a prompt to an agent |
| **Agent Message** | The agent produces a response |
| **Agent Reasoning** | Internal reasoning steps (chain-of-thought) |
| **Tool Invocation** | An agent calls a tool or action |
| **Data Source Accessed** | An agent reads from a connected data source |
| **Channel Accessed** | An agent interacts with an access channel |
| **Skill Invoked** | An agent triggers a defined skill |
| **Policy Evaluated** | A security policy is evaluated against an action |
| **Detection Created** | A security detection is triggered |
| **Finding Created** | A security finding is generated |
| **Issue Created** | A security issue is opened |
| **Error** | An error occurs during agent execution |
| **System Message** | A platform-level system event |


### Audit Data Structure

Each audit event includes:

- **Timestamp** - when the event occurred
- **Session ID** - groups events into conversation sessions
- **Agent** - the AI agent that generated the event, including platform and environment
- **User** - the identity of the user interacting with the agent
- **Entity** - the tool, data source, skill, or access channel involved
- **Message** - human-readable event content (full-text searchable)
- **Detections** - any security detections triggered by this event
- **Findings** - security findings linked to this event
- **Policies** - policies evaluated during this event
- **Metadata** - raw JSON payload from the source platform for forensic analysis


### Searching and Filtering Audit Logs

Navigate to **Observability** in the Capsule portal to access the full audit log. The interface supports:

- **Full-text search** across event messages and agent names
- **Date range filtering** with custom time windows
- **Agent filtering** by specific agent or platform type (e.g., all Azure AI Foundry agents)
- **Activity type filtering** - narrow to specific event types (sessions, tool calls, detections, etc.)
- **Detection type filtering** - view only events that triggered specific detection categories
- **Finding type filtering** - filter by finding classification
- **Issue filtering** - find all sessions linked to a specific issue
- **Tool / Data Source / Channel / Skill filtering** - drill into events involving a specific entity


Results are sortable by timestamp, agent name, or event type. The timeline chart provides a visual overview of activity density and security indicators across your chosen time window.

### Session-Based Investigation

Audit events are grouped into **sessions** - the complete lifecycle of an agent conversation. Selecting a session in the Observability view shows:

- The full ordered sequence of events (user messages, agent responses, tool calls, etc.)
- Security detections triggered during the session
- Issues created from the session
- Policy evaluation results


This session-level view is the primary interface for incident investigation and forensic review.

### CSV Export

All audit data visible in the portal can be exported to CSV for offline analysis, compliance reporting, or ingestion into external systems. Use the **Export** action in the toolbar of any inventory or observability page. The export runs in batches with progress tracking and supports cancellation.

### Data Retention

Capsule retains all audit data in the platform database for the lifetime of your tenant. Data is soft-deleted (never physically removed during normal operation), ensuring a complete audit trail is available for investigation.

| Deployment Model | Searchable Log Storage | Retention Period | Archive Capability |
|  --- | --- | --- | --- |
| **Enterprise SaaS** | Capsule-managed PostgreSQL | Unlimited (tenant lifetime) | Included - data persists in the managed database with automated backups |
| **Dedicated SaaS with BYOK** | Dedicated PostgreSQL with customer-managed encryption keys | Unlimited (tenant lifetime) | Included - customer controls encryption keys; Capsule manages backups |
| **Customer Hosted VPC** | Amazon RDS in customer VPC | Unlimited (tenant lifetime) | Full customer control - configure RDS snapshots per your requirements |


**90-day searchable / 1-year archive requirement:** All deployment models meet this requirement by default. Audit data is stored in PostgreSQL and remains fully searchable (with full-text search indexes) for the entire retention period - there is no degradation from "searchable" to "archived" state. For Customer Hosted VPC deployments, customers can additionally configure RDS automated snapshot retention to satisfy specific compliance windows.

## SIEM Integration

Capsule exports security events to one of two destinations, configured per integration under **Settings → SIEM**.

**Amazon S3** - Capsule provisions and manages a dedicated bucket for the integration. Your SIEM ingests from it by assuming a read-only IAM role scoped with an External ID. Capsule stores no credentials for your SIEM and needs no inbound access to it. Any SIEM that can read from S3 - [Hunters](/guides/hunters-siem), Microsoft Sentinel, and others - uses this path. See the [Amazon S3 guide](/guides/s3-siem).

**Splunk HTTP Event Collector** - Capsule pushes events to your HEC endpoint as they are produced, sourcetyped so the Capsule Technology Add-on can map them to CIM. See the [Splunk guide](/guides/splunk-siem).

Both destinations carry the same event envelope, so a tenant exporting to both sees identical content.

### What Gets Exported

| Event type | Contents |
|  --- | --- |
| **Detections** | The detection, its anchor resource, and the activities that triggered it |
| **Findings** | Posture and configuration findings with evidence and remediation steps |
| **Policy violations** | The violation with reasoning, severity, and status, plus the findings and detections behind it |


Each event type is toggled independently per integration.

The raw activity stream is not exported wholesale - activities reach your SIEM only as context attached to a detection. For the full audit trail, use CSV export or the GraphQL API.

Evidence text is redacted before export: secrets captured alongside a detection or finding are masked down to a short preview.

### How It Works

```
Capsule event (detection / finding / policy violation)
  → written as NDJSON to the Capsule-managed S3 bucket for that integration
  → your SIEM assumes the read-only role (External ID enforced)
  → your SIEM ingests the objects
```

- **Layout** - objects are keyed by event type and UTC date, `<event-type>/YYYY/MM/DD/<timestamp>-<id>.ndjson`, under three top-level prefixes: `detections/`, `findings/`, `policy-violations/`
- **Format** - NDJSON, one event per line, written as events are produced
- **Retention** - a bucket lifecycle rule expires objects after the window you choose (30, 90, 180, or 365 days); ingest continuously so nothing is missed before expiry
- **Backfill** - export begins when the integration is enabled; events raised before that are not backfilled
- **Access** - the bucket and role live in Capsule's AWS account, not yours. The role grants only `s3:ListBucket`, `s3:GetBucketLocation`, and `s3:GetObject` on that one bucket, and its trust policy requires both your Principal ARN and the matching External ID


### Setting Up an Integration

1. In Capsule, go to **Settings → SIEM** and click **Add integration**
2. Choose which event types to export and the retention window
3. Paste the **Principal ARN** and **External ID** your SIEM gives you for cross-account read access. An External ID is required whenever a Principal ARN is set - it is what protects the role against confused-deputy access
4. Save. Capsule provisions the bucket and the read-only role, then shows **Connection details** - bucket name, region, and read role ARN - to paste back into your SIEM
5. Turn on the **Enabled** switch on the integration's row. New integrations are created disabled, and nothing is exported until you enable one - events raised while it is off are not backfilled once you do


Each integration gets its own bucket and role, so separate SIEMs or event scopes never share a destination.

For a provider-specific walkthrough, see [Hunters SIEM](/guides/hunters-siem).

### Event Schema

Every line is one envelope. `eventType` is `detection.created`, `finding.created`, or `policy_violation.created`, and the shape of `event` follows from it.

```json
{
  "schemaVersion": 1,
  "eventType": "detection.created",
  "tenantId": "b6f0c1d2-4a3e-4c11-9f57-2c8a1de40f9b",
  "exportedAt": "2026-03-19T10:30:02.118Z",
  "event": {
    "detection": {
      "id": "0f8b2c6a-19d4-4f0b-8f3e-51a7c9e2b101",
      "detectionType": "PII_LEAKAGE",
      "title": "Agent returned customer records to an external channel",
      "evidence": ["database_query: SELECT * FROM orders WHERE status = 'pending'"],
      "sessionId": "sess-abc123",
      "triageVerdict": "TRUE_POSITIVE",
      "createdAt": "2026-03-19T10:30:00.000Z"
    },
    "anchorResource": {
      "id": "c4a1e8f7-2b93-4d6a-8e11-77c0b5d3a920",
      "name": "Customer Support Agent",
      "resourceType": "Agent"
    },
    "activities": [
      {
        "id": "9d5f3b21-6c7a-4e88-b2d0-0a4e6f81c733",
        "activityType": "ToolInvocation",
        "activitySource": "Platform",
        "occurredAt": "2026-03-19T10:30:00.000Z",
        "capturedAt": "2026-03-19T10:30:01.400Z",
        "message": "database_query: SELECT * FROM orders WHERE status = 'pending'",
        "wordCount": 12
      }
    ]
  }
}
```

### Alert Forwarding

Separate from the S3 export, Capsule pushes individual alerts to a destination as they happen, configured under **Settings → Notifications**: Microsoft Sentinel, Slack, Microsoft Teams, email, and Freshservice.

Sentinel alerts are delivered through the Azure Monitor Logs Ingestion API into a custom `CapsuleAlert_CL` table in your Log Analytics workspace, where your existing analytics rules and incident workflows can act on them. See [Microsoft Sentinel](/guides/microsoft-sentinel).

Notifications push one alert at a time to a channel; the SIEM export streams the full verbose event record for ingestion and long-term correlation. Most deployments use both.

### Centralized Log Offloading

**Can Capsule offload logs to a centralized SIEM?** Yes, with one scope caveat.

Detections, findings, and policy violations - the security-relevant events - are continuously exported to the S3 bucket your SIEM reads. The complete raw audit trail stays in the platform, where it remains searchable for the tenant lifetime and can be pulled on demand via CSV export or the GraphQL API.

### Retention and Archival Compliance

**Does Capsule support 90-day searchable logs and 1-year archived data?**

Yes. The following table summarizes how each deployment model meets this requirement:

| Requirement | Enterprise SaaS | Dedicated SaaS (BYOK) | Customer Hosted VPC |
|  --- | --- | --- | --- |
| **90-day searchable** | Full-text indexed audit data in managed PostgreSQL - searchable at all times | Same as Enterprise SaaS, with customer-managed encryption keys | Full-text indexed audit data in customer-owned RDS with configurable retention |
| **1-year archive** | Capsule-managed database backups with automated retention | Customer-controlled encryption keys over Capsule-managed backups | Customer-controlled RDS snapshots with lifecycle policies |
| **SIEM archival** | Export detections, findings, and policy violations to the S3 bucket your SIEM ingests from, then apply your organization's retention policies | Same | Same |


For organizations requiring strict compliance with 90-day/1-year retention policies, the recommended approach is:

1. **Primary retention** - Capsule platform retains all audit data with full search capability for the tenant lifetime (exceeds 90-day requirement)
2. **SIEM export** - export detections, findings, and policy violations to S3 for correlation, alerting, and SOC workflows
3. **Long-term archival** - once ingested, apply your SIEM's archival tier to retain the data for 1+ year at reduced storage cost. The Capsule export bucket itself is a delivery buffer, not an archive - objects expire after the retention window you configure


## Security and Compliance

| Control | Details |
|  --- | --- |
| **Encryption in transit** | TLS 1.3 for all API communication and log forwarding |
| **Encryption at rest** | AES-256 for all stored audit data; BYOK available on Dedicated SaaS and VPC deployments |
| **Access control** | Role-based access control (RBAC) governs who can view, search, and export audit data |
| **Immutability** | Audit records use soft-delete - events are never physically removed during normal operation |
| **SOC 2 Type 2** | Audit logging controls verified annually |
| **ISO 27001** | Information security management compliance |


## Support

For help configuring SIEM integrations or meeting specific compliance requirements, contact [support@capsule.security](mailto:support@capsule.security).