> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3

> Export filtered Forge security events as partitioned JSONL objects.

Forge writes normalized `security_event.v1` records to Amazon S3 or compatible
object storage as newline-delimited JSON. Export scope, content detail,
encryption, replay, and delivery health are configured per destination.

See [Security Exports](/integrations/security-exports) for shared filtering,
health, multiple-destination, and replay behavior.

## Events

| Category                | Records                                   |
| ----------------------- | ----------------------------------------- |
| `agent_event`           | Agent session and event activity          |
| `governance_signal`     | Policy and governance evaluation evidence |
| `finding`               | Security findings                         |
| `org_audit`             | Organization audit records                |
| `managed_config_audit`  | Managed configuration changes and drift   |
| `agent_attribution`     | Provider-to-agent attribution results     |
| `compliance_assessment` | Compliance evaluation records             |
| `governance_workflow`   | Requests, approvals, and workflow state   |

## Destination

| Field             | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| Bucket and prefix | Object destination                                           |
| Region            | AWS region used for S3 delivery                              |
| Endpoint URL      | Optional S3-compatible endpoint                              |
| Path style        | Supports providers without virtual-hosted bucket addressing  |
| Role ARN          | IAM role assumed by Forge                                    |
| External ID       | Value required by the role trust policy                      |
| Access-key refs   | Alternative managed-secret references for compatible storage |
| Encryption        | SSE-S3 or SSE-KMS, optional KMS key, and bucket-key setting  |

## AWS role

Role-based delivery is recommended for AWS S3. The Console generates a trust
policy and a least-privilege write policy for your exact destination. The role
trust policy must allow the Forge AWS principal shown in the Console to call
`sts:AssumeRole` only when the destination's external ID matches.

The minimum S3 permission is `s3:PutObject`, scoped to the configured prefix:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "WriteForgeSecurityTelemetry",
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::<bucket>/<prefix>/*"
    }
  ]
}
```

### SSE-KMS

For SSE-KMS:

* Enter the full KMS key ARN, not a key ID or alias.
* Use a key in the same AWS region as the bucket.
* Grant the delivery role `kms:Encrypt` and `kms:GenerateDataKey` on only that
  key.
* Ensure the KMS key policy allows the delivery role to use those permissions.

```json theme={"system"}
{
  "Sid": "EncryptForgeSecurityTelemetry",
  "Effect": "Allow",
  "Action": ["kms:Encrypt", "kms:GenerateDataKey"],
  "Resource": "arn:aws:kms:<region>:<account-id>:key/<key-id>"
}
```

The generated policy in the Console includes this statement when SSE-KMS and a
valid key ARN are selected. Forge only writes export objects; it does not need
`kms:Decrypt`.

## Filters

| Filter           | Values                                         |
| ---------------- | ---------------------------------------------- |
| Category         | Any supported event categories                 |
| Minimum severity | `info`, `low`, `medium`, `high`, or `critical` |
| Source           | Source adapter keys                            |
| Product          | Product identity keys or product entity IDs    |
| Identity         | Directory user IDs                             |
| Endpoint         | Device IDs                                     |

## Detail

Supported levels are `metadata_only`, `indexed_summary`,
`full_body_reference`, and `full_body_inline`. Prompt, tool-input, tool-output,
and raw-body inclusion are independent switches and remain bounded by available
source detail and privacy policy.

## Object layout

```text theme={"system"}
s3://<bucket>/<prefix>/forge/org_id=<organization_id>/category=<category>/date=YYYY-MM-DD/batch_id=<batch_id>.jsonl
```

Each line contains one event object. Forge also sets object metadata for
`forge_schema`, `organization_id`, `category`, and `batch_id`.

## Connection

1. Open **Settings → Integrations → Amazon S3** and enter the bucket, prefix,
   region, credentials, endpoint behavior, and encryption settings.
2. For AWS role authentication, copy or apply the generated role setup and
   paste the resulting role ARN into Forge.
3. Select event filters, detail policy, replay lookback, and delivery-state
   retention.
4. Send a test batch. Verify the exact object key, object metadata, encryption
   state, and one decoded JSONL row before activating the destination.

## Delivery

Forge tracks category cursors, delivered bytes and events, skipped records,
batch attempts, retryable and permanent failures, and dead letters. A replay
uses an explicit time window and category set without changing continuous
delivery cursors.