# RDS Audit Logs

Ingests audit logs from an AWS RDS DB instance using the RDS log files API.

**Sync Type:** Incremental

## Overview

The AWS RDS Audit Logs input reads audit log files directly from an RDS DB instance using the `DescribeDBLogFiles` and `DownloadDBLogFilePortion` APIs. Each non-empty line in the downloaded log files is emitted as a record. Because log line formats differ across database engines, records are emitted as raw log lines rather than parsed into individual fields.

### How It Works

1. Monad calls `DescribeDBLogFiles` to list log files available on the configured DB instance, filtered to the engine-appropriate file prefix (`audit/` for MySQL and MariaDB; `error/postgresql.log.*` for Postgres).
2. For each new or updated log file, Monad calls `DownloadDBLogFilePortion` to stream the file contents in pages of 1,000 lines.
3. A per-file cursor (marker + last-written timestamp) is persisted in Monad's state store so that subsequent runs resume from where they left off and never re-emit lines already seen.
4. If a run is interrupted mid-download, the next run detects that the stored `LastWritten` value is below the live value and resumes from the saved marker position.

### Supported Engines

| Engine | Audit log file prefix |
|--------|-----------------------|
| MySQL | `audit/` |
| MariaDB | `audit/` |
| Postgres | `error/postgresql.log.*` |

> **Note:** If the RDS instance has audit logs routed to CloudWatch (i.e., `audit` appears in the instance's `EnabledCloudwatchLogsExports`), this input will return an error and you should use the [CloudWatch Logs](./aws-cloudwatch-logs.mdx) input instead.

## Requirements

Before using this connector, ensure the following prerequisites are met.

### 1. Enable Audit Logging on the RDS Instance

Audit logging must be enabled on the DB instance and configured to write to RDS log files (not CloudWatch Logs).

**MySQL / MariaDB** — Enable the MariaDB Audit Plugin or the MySQL Audit Plugin via a custom DB parameter group:

1. Create a custom parameter group for your engine version.
2. Set `server_audit_logging = 1` (and any additional `server_audit_*` parameters you need).
3. Apply the parameter group to your DB instance and reboot if required.

**PostgreSQL** — Enable `pgaudit` via a custom parameter group:

1. Add `pgaudit` to the `shared_preload_libraries` parameter.
2. Set `pgaudit.log` to the statement classes you want to capture (e.g., `ddl, write, role`).
3. Apply the parameter group and reboot if required.

For full setup instructions, see the [Amazon RDS Database Log Files documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_LogAccess.html).

### 2. Grant IAM Permissions

The role or credentials used must have permission to describe and download log files for the target DB instance.

**Minimum required permissions:**

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "RDSAuditLogsPermissions",
      "Effect": "Allow",
      "Action": [
        "rds:DescribeDBInstances",
        "rds:DescribeDBLogFiles",
        "rds:DownloadDBLogFilePortion"
      ],
      "Resource": "arn:aws:rds:<region>:<account-id>:db:<db-instance-identifier>"
    }
  ]
}
```

Replace `<region>`, `<account-id>`, and `<db-instance-identifier>` with your values. To scope the policy to all instances in the account, replace the `Resource` value with `"*"`.

**For Role ARN Authentication:**
1. Create or update an IAM role in your AWS account.
2. Add the above permissions to the role.
3. Update the trust relationship to allow Monad to assume it (see [AWS Authentication Methods](./index.mdx#authentication-methods)).

**For Static Credentials:**
1. Create or use an IAM user with programmatic access.
2. Attach the above policy.
3. Generate or use an existing Access Key ID and Secret Access Key.

## Configuration

### Settings

| Setting | Type | Required | Default | Description |
|---------|------|----------|---------|-------------|
| **Region** | string | Yes | - | The AWS region where the RDS instance is deployed (e.g., `us-east-1`). |
| **DB Instance Identifier** | string | Yes | - | Identifier of the RDS DB instance to fetch audit logs from (e.g., `my-db-instance`). |
| **Role ARN** | string | No | - | ARN of the IAM role to assume for accessing RDS. Use either this or static credentials, not both. |
| **Backfill Start Time** | string | No | - | ISO 8601 date-time (e.g., `2025-01-01T00:00:00Z`) from which to start fetching log files. If omitted, all currently available log files are processed. |

### Secrets (Static Credentials Only)

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| **Access Key** | string | Conditional | AWS Access Key ID. Required only if not using Role ARN. |
| **Secret Key** | string | Conditional | AWS Secret Access Key. Required only if not using Role ARN. |

**Authentication Note:** Choose either Role ARN (recommended) or static credentials (Access Key + Secret Key). See [AWS Authentication Methods](./index.mdx#authentication-methods) for detailed setup instructions.

## Output Record Schema

Each record corresponds to one non-empty log line. Records are not parsed per field because the format differs across engines.

| Field | Type | Description |
|-------|------|-------------|
| `engine` | string | Database engine (`mysql`, `mariadb`, or `postgres`). |
| `instance_id` | string | RDS DB instance identifier. |
| `log_file_name` | string | Name of the log file the line was read from (e.g., `audit/server_audit.log`). |
| `message` | string | The raw log line. |
| `region` | string | AWS region of the DB instance. |
| `source` | string | Always `rds_log_file`. |

## Sample Record

```json
{
  "engine": "mysql",
  "instance_id": "prod-mysql-01",
  "log_file_name": "audit/server_audit.log",
  "message": "20240115 10:30:45,ip-10-0-1-5,admin,prod_db,52,1001,QUERY,`SELECT * FROM users WHERE id = 1`,,0",
  "region": "us-east-1",
  "source": "rds_log_file"
}
```

## Related Articles

- [Amazon RDS Database Log Files](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_LogAccess.html)
- [RDS DescribeDBLogFiles API](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBLogFiles.html)
- [RDS DownloadDBLogFilePortion API](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DownloadDBLogFilePortion.html)
- [Using pgaudit with Amazon RDS for PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.pgaudit.html)
- [MariaDB Audit Plugin for Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.MySQL.Options.AuditPlugin.html)