# cloudtrail

Provisions an organization-level AWS CloudTrail trail with CloudWatch Logs integration.

Creates an organization-wide, multi-region trail that delivers logs to a central S3 bucket (provisioned separately via the `storage/s3-bucket` module) and streams events to a CloudWatch log group. Configures a dedicated IAM role for CW delivery, optional KMS encryption, log file validation, and data event capture for S3 objects and Lambda functions by default.

## Usage

```hcl
module "cloudtrail" {
  source  = "hcassc.jfrog.io/iac-terraform-modules-virtual/governance/cloudtrail/aws"
  version = "0.1.0"

  trail_name     = "org-trail"
  s3_bucket_name = module.cloudtrail_bucket.id
  kms_key_id     = module.kms.key_arn
}
```

<!-- BEGIN_TF_DOCS — DO NOT EDIT BELOW THIS LINE -->
## Requirements

| Name | Version |
| ---- | ------- |
| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | ~> 1.5 |
| <a name="requirement_aws"></a> [aws](#requirement_aws) | ~> 6.50 |

## Providers

| Name | Version |
| ---- | ------- |
| <a name="provider_aws"></a> [aws](#provider_aws) | 6.50.0 |

## Resources

| Name | Type |
| ---- | ---- |
| [aws_cloudtrail.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudtrail) | resource |
| [aws_cloudwatch_log_group.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudwatch_log_group) | resource |
| [aws_iam_role.cloudtrail_cw](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
| [aws_iam_role_policy.cloudtrail_cw](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy) | resource |

## Inputs

| Name | Description | Type | Default | Required |
| ---- | ----------- | ---- | ------- | :------: |
| <a name="input_s3_bucket_name"></a> [s3_bucket_name](#input_s3_bucket_name) | Name of the S3 bucket for CloudTrail log delivery | `string` | n/a | yes |
| <a name="input_cloudwatch_logs_retention_days"></a> [cloudwatch_logs_retention_days](#input_cloudwatch_logs_retention_days) | Retention period in days for the CloudWatch log group | `number` | `365` | no |
| <a name="input_data_resources"></a> [data_resources](#input_data_resources) | Data event resources to capture. Map key is a logical name.<br/>type is the CloudTrail resource type (e.g. AWS::S3::Object).<br/>values is the list of ARNs or ARN prefixes to include. | <pre>map(object({<br/>    type   = string<br/>    values = list(string)<br/>  }))</pre> | <pre>{<br/>  "all_lambda": {<br/>    "type": "AWS::Lambda::Function",<br/>    "values": [<br/>      "arn:aws:lambda"<br/>    ]<br/>  },<br/>  "all_s3": {<br/>    "type": "AWS::S3::Object",<br/>    "values": [<br/>      "arn:aws:s3:::"<br/>    ]<br/>  }<br/>}</pre> | no |
| <a name="input_enable_log_file_validation"></a> [enable_log_file_validation](#input_enable_log_file_validation) | Enable log file integrity validation | `bool` | `true` | no |
| <a name="input_include_global_service_events"></a> [include_global_service_events](#input_include_global_service_events) | Include global service events (IAM, STS, etc.) | `bool` | `true` | no |
| <a name="input_is_multi_region_trail"></a> [is_multi_region_trail](#input_is_multi_region_trail) | Capture events from all regions | `bool` | `true` | no |
| <a name="input_is_organization_trail"></a> [is_organization_trail](#input_is_organization_trail) | Enable organization-level trail spanning all member accounts | `bool` | `true` | no |
| <a name="input_kms_key_id"></a> [kms_key_id](#input_kms_key_id) | KMS key ARN for trail log encryption (optional) | `string` | `null` | no |
| <a name="input_management_events_rw_type"></a> [management_events_rw_type](#input_management_events_rw_type) | Read/Write type for management events — All, ReadOnly, WriteOnly, or None | `string` | `"All"` | no |
| <a name="input_s3_key_prefix"></a> [s3_key_prefix](#input_s3_key_prefix) | S3 key prefix for CloudTrail log objects | `string` | `"cloudtrail"` | no |
| <a name="input_tags"></a> [tags](#input_tags) | Resource tags to apply to all resources | `map(string)` | `{}` | no |
| <a name="input_trail_name"></a> [trail_name](#input_trail_name) | Name of the CloudTrail trail | `string` | `"org-trail"` | no |

## Outputs

| Name | Description |
| ---- | ----------- |
| <a name="output_arn"></a> [arn](#output_arn) | CloudTrail trail ARN |
| <a name="output_cloudwatch_log_group_arn"></a> [cloudwatch_log_group_arn](#output_cloudwatch_log_group_arn) | ARN of the CloudWatch log group receiving trail events |
| <a name="output_cloudwatch_role_arn"></a> [cloudwatch_role_arn](#output_cloudwatch_role_arn) | ARN of the IAM role used for CloudWatch Logs delivery |
| <a name="output_home_region"></a> [home_region](#output_home_region) | Region in which the trail was created |
| <a name="output_id"></a> [id](#output_id) | CloudTrail trail ID (name) |
<!-- END_TF_DOCS — DO NOT EDIT ABOVE THIS LINE -->