Terraform module which configures AWS datastores for audit logging and integrates them with IBM Guardium Data Protection via Universal Connector.
This module automates the configuration of audit logging for various AWS datastores (DynamoDB, DocumentDB, MariaDB RDS, PostgreSQL RDS) and establishes integration with IBM Guardium Data Protection for comprehensive database activity monitoring, security analysis, and compliance reporting.
The following diagram illustrates how this module orchestrates the configuration of AWS datastores and their integration with Guardium Data Protection:
┌─────────────────────────────────────────────────────────────────────────────────┐
│ │
│ Guardium Datastore Audit Configuration Module │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
│ Orchestrates
▼
┌───────────────────────────────────────────────────────────┐
│ │
│ AWS Datastore Configuration │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ DynamoDB │ │ DocumentDB │ │ MariaDB RDS │ │
│ │ + CloudTrail│ │ + Audit Logs│ │ + Audit Plugin │ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ PostgreSQL RDS │ │
│ │ + pgAudit (Object/Session Level) │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
│
│ Audit Logs
▼
┌───────────────────────────────────────────────────────────┐
│ │
│ AWS Log Aggregation Layer │
│ │
│ ┌─────────────────┐ ┌──────────────────────┐ │
│ │ CloudWatch │ │ S3 Buckets │ │
│ │ Log Groups │ │ (CloudTrail Logs) │ │
│ └─────────────────┘ └──────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
│
│ Log Streaming
▼
┌───────────────────────────────────────────────────────────┐
│ │
│ Guardium Universal Connector (UC) │
│ │
│ • Reads logs from CloudWatch/S3 │
│ • Parses and normalizes audit data │
│ • Applies security policies │
│ • Forwards to Guardium Data Protection │
│ │
└───────────────────────────────────────────────────────────┘
│
│ Processed Audit Data
▼
┌───────────────────────────────────────────────────────────┐
│ │
│ Guardium Data Protection (GDP) │
│ │
│ • Security monitoring and threat detection │
│ • Compliance reporting and auditing │
│ • Policy enforcement and alerting │
│ • Activity analysis and forensics │
│ │
└───────────────────────────────────────────────────────────┘
-
Datastore Configuration: The module configures each AWS datastore to enable audit logging:
- DynamoDB: Enables CloudTrail data events to capture API calls
- DocumentDB: Enables audit and profiler logs via parameter groups
- MariaDB RDS: Enables MariaDB Audit Plugin via option groups
- PostgreSQL RDS: Configures pgAudit extension for object or session-level auditing
-
Log Aggregation: Audit logs are collected in AWS:
- CloudWatch Log Groups store structured logs
- S3 buckets provide long-term storage for CloudTrail logs
- IAM roles and policies ensure secure access
-
Universal Connector: The module deploys and configures Guardium Universal Connector:
- Establishes connection to CloudWatch Logs or S3
- Uses AWS credentials configured in Guardium
- Applies parsing rules specific to each datastore type
- Streams processed data to Guardium Data Protection
-
Guardium Integration: Audit data flows into Guardium for:
- Real-time security monitoring
- Compliance reporting (PCI-DSS, HIPAA, GDPR, etc.)
- Threat detection and alerting
- Forensic analysis and investigation
This module provides audit configuration for the following AWS datastores:
| Datastore | Module Path | Audit Method | Log Destination |
|---|---|---|---|
| AWS DynamoDB | modules/aws-dynamodb |
CloudTrail Data Events | CloudWatch Logs |
| AWS DocumentDB | modules/aws-documentdb |
DocumentDB Audit Logs | CloudWatch Logs |
| AWS MariaDB RDS | modules/aws-mariadb-rds-audit |
MariaDB Audit Plugin | CloudWatch Logs |
| AWS PostgreSQL RDS (Object) | modules/aws-postgresql-rds-object |
pgAudit (Object-Level) | CloudWatch/SQS |
| AWS PostgreSQL RDS (Session) | modules/aws-postgresql-rds-session |
pgAudit (Session-Level) | CloudWatch/SQS |
Before using this module, ensure you have:
-
AWS Account: With appropriate permissions to create and manage:
- CloudTrail and CloudWatch resources
- IAM roles and policies
- S3 buckets
- Database parameter/option groups
- SQS queues (for PostgreSQL modules)
-
Guardium Data Protection Instance: A running GDP cluster with:
- SSH access configured
- Web UI credentials with appropriate permissions
- OAuth client registered via
grdapi register_oauth_client - AWS credentials configured in Universal Connector
-
Terraform: Version 1.0.0 or later
-
AWS CLI: Configured with appropriate credentials
Monitor DynamoDB tables with comprehensive API call tracking:
module "dynamodb_audit" {
source = "IBM/datastore-audit/guardium//modules/aws-dynamodb"
# AWS Configuration
aws_region = "us-east-1"
dynamodb_tables = "users-table,orders-table" # or "all" for all tables
name_prefix = "my-dynamodb-audit"
# Guardium Configuration
gdp_server = "guardium.example.com"
gdp_port = "8443"
gdp_username = "admin"
gdp_password = "password"
gdp_ssh_username = "root"
gdp_ssh_privatekeypath = "~/.ssh/guardium_key"
gdp_client_id = "client1"
gdp_client_secret = "client-secret"
# Universal Connector Configuration
udc_aws_credential = "aws-credential-name"
gdp_mu_host = "guardium-mu.example.com"
tags = {
Environment = "production"
Project = "data-security"
}
}Enable comprehensive audit logging for DocumentDB clusters:
module "documentdb_audit" {
source = "IBM/datastore-audit/guardium//modules/aws-documentdb"
# AWS Configuration
aws_region = "us-east-1"
documentdb_cluster_identifier = "my-docdb-cluster"
# Guardium Configuration
gdp_server = "guardium.example.com"
gdp_port = "8443"
gdp_username = "admin"
gdp_password = "password"
gdp_ssh_username = "root"
gdp_ssh_privatekeypath = "~/.ssh/guardium_key"
gdp_client_id = "client1"
gdp_client_secret = "client-secret"
# Universal Connector Configuration
udc_name = "docdb-connector"
udc_aws_credential = "aws-credential-name"
gdp_mu_host = "guardium-mu.example.com"
tags = {
Environment = "production"
}
}Configure MariaDB Audit Plugin for RDS instances:
module "mariadb_audit" {
source = "IBM/datastore-audit/guardium//modules/aws-mariadb-rds-audit"
# AWS Configuration
aws_region = "us-east-1"
mariadb_rds_cluster_identifier = "my-mariadb-instance"
mariadb_major_version = "10.6"
# Audit Configuration
audit_events = "CONNECT,QUERY,TABLE"
# Guardium Configuration
gdp_server = "guardium.example.com"
gdp_username = "admin"
gdp_password = "password"
gdp_ssh_username = "root"
gdp_ssh_privatekeypath = "~/.ssh/guardium_key"
gdp_client_id = "client1"
gdp_client_secret = "client-secret"
# Universal Connector Configuration
udc_aws_credential = "aws-credential-name"
log_export_type = "Cloudwatch"
tags = {
Environment = "production"
}
}Monitor specific tables with granular control:
module "postgres_object_audit" {
source = "IBM/datastore-audit/guardium//modules/aws-postgresql-rds-object"
# AWS Configuration
aws_region = "us-east-1"
postgres_rds_cluster_identifier = "my-postgres-db"
# Database Connection
db_host = "my-postgres-db.example.region.rds.amazonaws.com"
db_port = 5432
db_username = "admin"
db_password = "password"
db_name = "postgres"
# Tables to Monitor
tables = [
{
schema = "public"
table = "users"
grants = ["SELECT", "INSERT", "UPDATE", "DELETE"]
},
{
schema = "public"
table = "orders"
grants = ["SELECT", "INSERT"]
}
]
# Guardium Configuration
gdp_server = "guardium.example.com"
gdp_username = "admin"
gdp_password = "password"
gdp_ssh_username = "root"
gdp_ssh_privatekeypath = "~/.ssh/guardium_key"
gdp_client_id = "client1"
gdp_client_secret = "client-secret"
# Universal Connector Configuration
udc_aws_credential = "aws-credential-name"
log_export_type = "Cloudwatch"
}Capture all database activity comprehensively:
module "postgres_session_audit" {
source = "IBM/datastore-audit/guardium//modules/aws-postgresql-rds-session"
# AWS Configuration
aws_region = "us-east-1"
postgres_rds_cluster_identifier = "my-postgres-db"
# Guardium Configuration
gdp_server = "guardium.example.com"
gdp_username = "admin"
gdp_password = "password"
gdp_ssh_username = "root"
gdp_ssh_privatekeypath = "~/.ssh/guardium_key"
gdp_client_id = "client1"
gdp_client_secret = "client-secret"
# Universal Connector Configuration
udc_aws_credential = "aws-credential-name"
log_export_type = "Cloudwatch"
}Complete working examples are available in the examples/ directory:
- aws-documentdb - DocumentDB audit configuration with Universal Connector
- aws-dynamodb - DynamoDB audit configuration with Universal Connector
- aws-mariadb-rds-audit - MariaDB RDS audit configuration
- aws-postgresql-rds-object - PostgreSQL object-level auditing
- aws-postgresql-rds-object-tables - PostgreSQL object-level auditing with specific tables
- aws-postgresql-rds-session - PostgreSQL session-level auditing
Each example includes:
- Complete Terraform configuration
terraform.tfvars.examplefile with all required variables- README with specific instructions
- Automated Configuration: Automatically configures audit logging for AWS datastores
- Universal Connector Integration: Seamlessly integrates with Guardium Universal Connector
- Multiple Datastore Support: Supports DynamoDB, DocumentDB, MariaDB RDS, and PostgreSQL RDS
- Flexible Audit Levels: Choose between object-level and session-level auditing for PostgreSQL
- CloudWatch Integration: Leverages CloudWatch Logs for centralized log management
- Compliance Ready: Supports compliance requirements (PCI-DSS, HIPAA, GDPR, SOC 2)
- Terraform Native: Fully declarative infrastructure as code approach
- Credentials Management: Store sensitive credentials securely using Terraform variables or secret management solutions
- State File Security: Ensure Terraform state files are encrypted and stored securely
- IAM Permissions: Follow the principle of least privilege for all IAM roles and policies
- Network Security: Configure security groups and network ACLs appropriately
- Encryption: Enable encryption for CloudWatch Logs, S3 buckets, and data in transit
- Access Control: Implement proper access controls for Guardium and AWS resources
-
CloudTrail Not Capturing Events:
- Verify CloudTrail is configured with data events for the specific datastore
- Check IAM permissions for CloudTrail
- Ensure CloudWatch Log Group is properly configured
-
Universal Connector Not Processing Logs:
- Verify AWS credentials are correctly configured in Guardium
- Check network connectivity between Guardium and AWS
- Review Universal Connector logs in Guardium UI
-
Parameter/Option Group Changes Not Applied:
- Some changes require database restart or failover
- Check the
force_failovervariable setting - Review AWS RDS events for any errors
-
Authentication Errors:
- Verify Guardium OAuth client credentials
- Ensure SSH key has correct permissions (600)
- Check Guardium user has appropriate permissions
For detailed troubleshooting, refer to the individual module READMEs.
Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
For issues and questions:
- Create an issue in this repository
- Contact the maintainers listed in MAINTAINERS.md
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
#
# Copyright IBM Corp. 2025
# SPDX-License-Identifier: Apache-2.0
#
Module is maintained by IBM with help from these awesome contributors.