Audit Logs

Search, download, and manage organization audit logs from the CLI.

Search and download are available on Start-Up and Enterprise plans. Continuous S3 export is available on Enterprise.

Time values can be dates (2026-06-01) or timestamps (2026-06-01T15:04:05Z). Dates begin at midnight UTC.

The kernel audit-logs export group follows the current CLI implementation. Install a CLI release that includes this command group; availability depends on the release you have installed.

kernel audit-logs search

Search audit logs within a time window. Results are ordered newest first.

kernel audit-logs search \
  --start 2026-06-01 \
  --end 2026-06-08 \
  --search /browsers \
  --limit 500 \
  --output json

If you omit the time flags, the command searches from 24 hours ago through now. The start is inclusive and the end is exclusive. Each time window can cover up to 30 days.

Flag	Description
--start <time>	Inclusive start. Defaults to 24 hours ago.
--end <time>	Exclusive end. Defaults to now.
--search <text>	Search path, user ID, email, client IP, and status.
--method <method>	Return only requests that use this HTTP method.
--exclude-method <method>	Exclude requests that use this HTTP method. GET remains excluded unless you pass --include-get.
--include-get	Remove the default GET exclusion when --method is not set.
--service <service>	Filter by service.
--auth-strategy <strategy>	Filter by authentication strategy.
--user-id <id>	Add a user ID to the search. Repeat the flag for multiple IDs.
--limit <n>	Maximum total number of results. Defaults to 100.
--output json, -o json	Output raw JSON array.

--limit controls the total number of CLI results. The CLI automatically requests API pages of up to 100 records until it reaches that limit or runs out of results.

Include GET requests

By default, the CLI returns matching requests for every HTTP method except GET. --include-get removes that default exclusion. --method selects exactly one method, so --method GET returns only GET requests.

# Return all matching methods, including GET
kernel audit-logs search --include-get

# Return only GET requests
kernel audit-logs search --method GET

kernel audit-logs download

Download matching audit logs in a time window as one gzip-compressed JSONL file.

kernel audit-logs download \
  --start 2026-06-01 \
  --end 2026-07-01 \
  --to audit-june.jsonl.gz

--start and --end are required. The start is inclusive and the end is exclusive, and the time window can cover up to 30 days.

Flag	Description
--start <time>	Inclusive start. Required.
--end <time>	Exclusive end. Required.
--search <text>	Search path, user ID, email, client IP, and status.
--method <method>	Return only requests that use this HTTP method.
--exclude-method <method>	Exclude requests that use this HTTP method. GET remains excluded unless you pass --include-get.
--include-get	Remove the default GET exclusion when --method is not set.
--service <service>	Filter by service.
--auth-strategy <strategy>	Filter by authentication strategy.
--user-id <id>	Add a user ID to the search. Repeat the flag for multiple IDs.
--to <path>	Output .jsonl.gz path. For the example above, the default is audit-logs-20260601-20260701.jsonl.gz.
--force	Replace an existing output file.

For example, --start 2026-06-01 --end 2026-07-01 covers all of June in UTC.

Download behavior

The CLI downloads up to 50,000 records per batch, verifies each batch’s SHA-256 checksum, and automatically retries transient failures.

The requested output appears only after the full download succeeds. Failed downloads are removed, though a completed download may remain at <output>.partial if it can’t be moved to the requested path.

Downloads don’t resume: rerunning the command starts over. Existing files are replaced only when you pass --force.

kernel audit-logs export

Manage S3 destinations that receive a continuous export of your organization’s audit logs. The group is also available as kernel audit-logs exports and kernel audit-logs export-destinations.

Objects use the layout <prefix>/destination_id=<destination>/org_id=<org>/date=<YYYY-MM-DD>/hour=<HH>/<window>-<chunk>.jsonl.gz. Delivery is at-least-once.

Create a destination paused, configure the IAM trust and permissions, run test, and then run resume. The create response includes the kernel_role_arn and external_id values needed for the trust policy. The destination must use an organization-level credential; project-scoped API keys are refused.

kernel audit-logs export create

Create an S3 audit log export destination. The destination is created paused.

kernel audit-logs export create \
  --region us-east-1 \
  --bucket customer-audit-logs \
  --prefix audit-logs \
  --role-arn arn:aws:iam::123456789012:role/customer-audit-log-export \
  --output json

Use --kms-key-id when the destination should use SSE-KMS. The command always creates the destination with the s3 type and jsonl.gz format.

Flag	Description
--region <region>	AWS region of the destination bucket. Required.
--bucket <name>	Destination S3 bucket name. Required.
--prefix <prefix>	Key prefix for exported objects; may be empty. Required.
--role-arn <arn>	IAM role ARN Kernel assumes to deliver logs. Required.
--kms-key-id <id|alias|arn>	KMS key ID, alias, or ARN for server-side encryption.
--output json, -o json	Output the raw JSON destination object.

The human-readable output prints the destination details and the activation steps. Use JSON output when a script needs to capture id, kernel_role_arn, and external_id.

kernel audit-logs export list

List audit log export destinations. Human-readable output includes the destination ID, bucket, prefix, region, status, last success, failure count, and last error.

kernel audit-logs export list \
  --limit 20 \
  --output json

Flag	Description
--limit <n>	Maximum number of destinations to return, from 1 to 100. Defaults to 20.
--output json, -o json	Output a JSON object with destinations and next_offset when another page exists.

kernel audit-logs export get <id>

Get details for one audit log export destination.

kernel audit-logs export get y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json

Flag	Description
--output json, -o json	Output the raw JSON destination object.

Without --output json, the command prints configuration, status, and delivery health fields such as last_exported_cursor, last_success_at, last_error, last_error_at, consecutive_failures, and next_attempt_at.

kernel audit-logs export update <id>

Update one or more destination fields. Pass at least one update flag. The API validates the merged destination configuration, so a KMS key ARN must match the destination region.

kernel audit-logs export update y2kkbpcz1lg0h3q6yr8x4m7d \
  --prefix audit-logs-v2 \
  --output json

To remove a configured KMS key and use bucket-default encryption:

kernel audit-logs export update y2kkbpcz1lg0h3q6yr8x4m7d \
  --clear-kms-key

Flag	Description
--region <region>	Update the AWS region of the destination bucket.
--bucket <name>	Update the destination S3 bucket name.
--prefix <prefix>	Update the key prefix for exported objects.
--role-arn <arn>	Update the IAM role ARN Kernel assumes to deliver logs.
--kms-key-id <id|alias|arn>	Update the KMS key ID, alias, or ARN for server-side encryption.
--clear-kms-key	Remove the configured KMS key. Mutually exclusive with --kms-key-id.
--output json, -o json	Output the raw JSON destination object.

A successful update prints the updated destination. A 409 Conflict means the destination changed concurrently; retrieve fresh state and retry with the intended fields.

kernel audit-logs export pause <id>

Pause a destination so new delivery attempts stop.

kernel audit-logs export pause y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json

Flag	Description
--output json, -o json	Output the raw JSON destination object.

An S3 upload already in progress may still complete after the pause. Events recorded while paused are not exported.

kernel audit-logs export resume <id>

Resume a destination. Delivery starts from the time of the resume; events recorded while paused are not exported.

kernel audit-logs export resume y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json

Flag	Description
--output json, -o json	Output the raw JSON destination object.

Use resume only after the destination’s trust policy and permissions are configured and test succeeds.

kernel audit-logs export delete <id>

Delete a destination and stop new delivery attempts.

kernel audit-logs export delete y2kkbpcz1lg0h3q6yr8x4m7d

This command has no flags and does not support JSON output. An S3 upload already in progress may complete after the delete.

kernel audit-logs export test <id>

Test a destination by assuming its role and writing a temporary probe object. The command exits non-zero when the test fails.

kernel audit-logs export test y2kkbpcz1lg0h3q6yr8x4m7d \
  --output json

Flag	Description
--output json, -o json	Output the raw JSON test result.

The result has success and stage fields. The stages are assume_role, put_object, and complete; customer-fixable failures use assume_role_failed or put_object_failed. A successful test reaches complete. The probe is deleted after the write when the role has s3:DeleteObject; grant that permission so test objects are cleaned up.

Activation sequence

Use this sequence for every new destination:

1. Run create. Save the returned destination ID, kernel_role_arn, and external_id.
2. Update the customer role’s trust policy to allow the returned Kernel role ARN with the returned sts:ExternalId.
3. Grant s3:PutObject and, preferably, s3:DeleteObject on the configured prefix. If KMS is configured, grant kms:GenerateDataKey and key-policy access.
4. Run test <id> and fix any assume_role or put_object failure.
5. Run resume <id> to start delivery from that point. There is no backfill.

After a plan downgrade, list, get, and delete remain available for cleanup, while delivery stops and create, update, and test require Enterprise.

Aliases

You can also use kernel audit-log, kernel auditlogs, or kernel auditlog.