Audit logging

Ripple Custody (Wallet) can stream all organization activity to an AWS Data Firehose delivery stream for compliance reporting, incident investigation, and access review. Owners and administrators configure the Firehose connection and manage audit log delivery. AWS Firehose is currently the only supported delivery target; customers on other clouds must ingest from Firehose into their own platform.

This page explains what audit logs capture and how to set up delivery. For IAM policy JSON, the record schema, decode examples, and example payloads, see the Firehose audit log reference.

Audit logs record every action in your organization, including:

• All API calls with request and response details
• User actions in the web console (sign-ins, setting changes, approvals)
• Transaction lifecycle events (creation, policy checks, approvals, signing, confirmation)
• Administrative actions (user management, device management, quorum operations)
• Timestamps and the identity of the user or API credential that performed each action
• Wallet lifecycle events (key provisioning and provisioning failures)

Ripple Custody (Wallet) captures request bodies up to 10 MB and stores them base64-encoded inside the payload. It never logs the Authorization header or response bodies: records carry a truncated hash of the Authorization value and the response body's length instead.

Ripple Custody (Wallet) streams audit log events to an AWS Data Firehose delivery stream in your AWS account. From there, you route the logs to your preferred destination:

• Amazon S3 — for long-term storage and compliance archiving
• Splunk, Datadog, or another SIEM — for real-time monitoring and alerting
• Amazon Redshift or Elasticsearch — for search and analysis

Ripple Custody (Wallet) buffers logs and delivers them approximately every 15 seconds.

Before you begin, set up the following in your AWS account:

• An AWS Data Firehose delivery stream configured with your preferred destination (S3, Splunk, etc.)
• An IAM role that Ripple can assume to write to the Firehose stream

Required role: Owner or Administrator.

1. Go to Settings > Audit logs. The Audit log configuration page opens.
2. Enter the Stream name — the exact name of your Firehose delivery stream (up to 64 characters).
3. Enter the ARN ID — the IAM role ARN that Ripple assumes to write to Firehose.
4. Select the AWS Region that contains your Firehose stream.
5. Select Save.

Create an IAM role with:

• A trust policy that allows Ripple's AWS account to assume the role.
• A permission policy that grants firehose:PutRecordBatch on your delivery stream and sts:GetCallerIdentity.

See Firehose audit log reference for the full IAM trust and permission policy JSON, including the Ripple AWS account IDs.

Required role: Owner or Administrator.

Saving the Firehose connection starts streaming. Ripple Custody (Wallet) validates the configuration, sets its status to Pending, and changes it to Enabled after the first successful delivery.

To temporarily stop streaming, go to Settings > Audit logs, open the actions menu on the audit log configuration, and select Disable. Ripple Custody (Wallet) preserves the configuration so you can re-enable it at any time. To resume streaming, select Enable from the same menu. The menu offers Enable only for a disabled configuration.

If delivery keeps failing, Ripple Custody (Wallet) disables the configuration automatically. For example, this happens when the IAM role stops granting access or the delivery stream no longer exists. Fix the stream or IAM role, and then select Enable to resume streaming. When you re-enable the configuration, Ripple Custody (Wallet) delivers the events it recorded while the configuration was off. You can't fix one case yourself: a record that exceeds the size limit even after truncation. Re-enabling doesn't help in that case, so contact support.

Each audit log entry is a JSON record with a fixed envelope and a compressed payload.

The envelope carries event metadata (id, type, source, receivedAt, createdAt), actor information (userId, deviceId, requestId), and your orgId. The type field identifies the record: 1 for access events, 3 for transaction lifecycle events, and 4 for wallet lifecycle events.

The payload — request and response details for access events, or the changed entity for lifecycle events — travels in compressedJsonData as base64-encoded, Brotli-compressed JSON. Your consumer base64-decodes and decompresses that field to read the event.

See Firehose audit log reference for the full field reference, decode examples, and example payloads.

• Route logs to a SIEM — tools like Splunk, Datadog, or Elastic SIEM let you search, alert on, and visualize audit events in real time.
• Set retention policies — configure retention on your Firehose destination (S3 lifecycle rules, Splunk index policies) to meet your compliance requirements.
• Monitor Firehose delivery — use AWS CloudWatch metrics for your Firehose stream to detect delivery failures or throttling.
• Use audit logs for access reviews — periodically review who is accessing what, which credentials are active, and whether access patterns match expectations.
• Correlate with freeze and approval events — cross-reference audit logs with transaction freeze and approval flow activity for complete compliance reporting.
• Separate sandbox and production — use different Firehose streams and destinations for each environment.

• Ripple Custody (Wallet) delivers audit logs with a small buffer delay (approximately 15 seconds). They aren't suitable for real-time blocking or inline security decisions.
• Log delivery depends on your Firehose stream being available. If AWS throttles the stream or the stream becomes unavailable, Ripple Custody (Wallet) buffers logs and retries delivery.
• A single record must stay below 1,000,000 encoded bytes. When an access record exceeds that, Ripple Custody (Wallet) clears request.body from the payload and marks the record with legacyJsonDataTruncated.

• Firehose audit log reference — Full technical reference with IAM policies, log schema, and example payloads
• Backup and recovery — Set up AWS infrastructure for backups (similar IAM patterns)
• Webhooks overview — Compare webhooks with audit logging