feat(permissions): add optional real-time detection to the AWS onboarding templates

permissions/templates/cloudformation/prowler-scan-role.yml

@@ -66,6 +66,35 @@ Parameters:
     Type: String
     Default: ""
 
+  # Real-Time Detection Parameters
+  EnableRealtimeDetection:
+    Description: |
+      Enable real-time detection. Forwards the tracked CloudTrail management events to Prowler Cloud
+      through an EventBridge API destination, so a change is scanned within minutes instead of waiting
+      for the next scheduled scan. Adds no new read permissions to the ProwlerScan role.
+    Type: String
+    Default: false
+    AllowedValues:
+      - true
+      - false
+
+  ProwlerWebhookUrl:
+    Description: |
+      Prowler Cloud endpoint that receives the events. Provided during Prowler Cloud onboarding.
+      Required if EnableRealtimeDetection is true.
+    Type: String
+    Default: ""
+    AllowedPattern: '^(https://.+)?$'
+    ConstraintDescription: "ProwlerWebhookUrl must be an HTTPS URL."
+
+  ProwlerApiKey:
+    Description: |
+      Prowler Cloud API key used to authenticate the events sent to the endpoint above.
+      Shown once during Prowler Cloud onboarding. Required if EnableRealtimeDetection is true.
+    Type: String
+    Default: ""
+    NoEcho: true
+
   # Deployment Control Parameters
   DeployStackSet:
     Description: |
@@ -134,6 +163,7 @@ Conditions:
   DeployStackSetEnabled: !Equals [!Ref DeployStackSet, true]
   DeployLocalRoleEnabled: !Equals [!Ref DeployLocalRole, true]
   UseDelegatedAdmin: !Equals [!Ref DeployFromDelegatedAdmin, true]
+  RealtimeDetectionEnabled: !Equals [!Ref EnableRealtimeDetection, true]
 
 Rules:
   S3IntegrationRequiresParams:
@@ -144,6 +174,14 @@ Rules:
       - Assert: !Not [!Equals [!Ref S3IntegrationBucketAccountId, ""]]
         AssertDescription: "S3IntegrationBucketAccountId is required when EnableS3Integration is true."
 
+  RealtimeDetectionRequiresParams:
+    RuleCondition: !Equals [!Ref EnableRealtimeDetection, "true"]
+    Assertions:
+      - Assert: !Not [!Equals [!Ref ProwlerWebhookUrl, ""]]
+        AssertDescription: "ProwlerWebhookUrl is required when EnableRealtimeDetection is true."
+      - Assert: !Not [!Equals [!Ref ProwlerApiKey, ""]]
+        AssertDescription: "ProwlerApiKey is required when EnableRealtimeDetection is true."
+
 Resources:
   # Local ProwlerScan Role (deployed in this account)
   ProwlerScan:
@@ -583,6 +621,130 @@ Resources:
             Export:
               Name: !Sub "${AWS::StackName}-ProwlerScanRoleArn"
 
+  # Real-Time Detection: forwards the tracked CloudTrail events to Prowler Cloud
+  ProwlerRealtimeConnection:
+    Type: AWS::Events::Connection
+    Condition: RealtimeDetectionEnabled
+    Properties:
+      Name: ProwlerRealtimeDetection
+      Description: Holds the Prowler Cloud API key used to authenticate forwarded events
+      AuthorizationType: API_KEY
+      AuthParameters:
+        ApiKeyAuthParameters:
+          ApiKeyName: x-api-key
+          ApiKeyValue: !Ref ProwlerApiKey
+
+  ProwlerRealtimeApiDestination:
+    Type: AWS::Events::ApiDestination
+    Condition: RealtimeDetectionEnabled
+    Properties:
+      Name: ProwlerRealtimeDetection
+      Description: Prowler Cloud endpoint that receives the forwarded CloudTrail events
+      ConnectionArn: !GetAtt ProwlerRealtimeConnection.Arn
+      InvocationEndpoint: !Ref ProwlerWebhookUrl
+      HttpMethod: POST
+
+  ProwlerRealtimeInvokeRole:
+    Type: AWS::IAM::Role
+    Condition: RealtimeDetectionEnabled
+    Properties:
+      RoleName: ProwlerRealtimeInvoke
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              Service: events.amazonaws.com
+            Action: "sts:AssumeRole"
+            Condition:
+              StringEquals:
+                "aws:SourceAccount": !Ref AWS::AccountId
+              ArnLike:
+                # Built from the rule name to avoid a circular dependency with the rule
+                "aws:SourceArn": !Sub "arn:${AWS::Partition}:events:${AWS::Region}:${AWS::AccountId}:rule/ProwlerRealtimeDetection"
+      Policies:
+        - PolicyName: InvokeApiDestination
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: "events:InvokeApiDestination"
+                Resource: !GetAtt ProwlerRealtimeApiDestination.Arn
+      Tags:
+        - Key: "Service"
+          Value: "https://prowler.com"
+        - Key: "Support"
+          Value: "support@prowler.com"
+        - Key: "CloudFormation"
+          Value: "true"
+        - Key: "Name"
+          Value: "ProwlerRealtimeInvoke"
+
+  ProwlerRealtimeRule:
+    Type: AWS::Events::Rule
+    Condition: RealtimeDetectionEnabled
+    Properties:
+      Name: ProwlerRealtimeDetection
+      Description: Forwards the CloudTrail management events tracked by Prowler real-time detection to Prowler Cloud
+      State: ENABLED
+      EventPattern:
+        detail-type:
+          - "AWS API Call via CloudTrail"
+        detail:
+          eventSource:
+            - ec2.amazonaws.com
+            - rds.amazonaws.com
+            - iam.amazonaws.com
+            - s3.amazonaws.com
+            - s3-control.amazonaws.com
+            - cloudtrail.amazonaws.com
+            - config.amazonaws.com
+            - guardduty.amazonaws.com
+          eventName:
+            # Security group opened to 0.0.0.0/0
+            - AuthorizeSecurityGroupIngress
+            - ModifySecurityGroupRules
+            # RDS instance made publicly accessible
+            - CreateDBInstance
+            - ModifyDBInstance
+            # Administrator privileges attached to a principal
+            - AttachUserPolicy
+            - AttachRolePolicy
+            - AttachGroupPolicy
+            - PutUserPolicy
+            - PutRolePolicy
+            # S3 bucket policy or ACL grants public access
+            - PutBucketPolicy
+            - PutBucketAcl
+            # S3 Block Public Access weakened
+            - PutAccountPublicAccessBlock
+            - DeleteAccountPublicAccessBlock
+            - PutBucketPublicAccessBlock
+            - DeleteBucketPublicAccessBlock
+            # CloudTrail logging stopped or trail deleted
+            - StopLogging
+            - DeleteTrail
+            - UpdateTrail
+            # AWS Config recorder stopped or deleted
+            - StopConfigurationRecorder
+            - DeleteConfigurationRecorder
+            # GuardDuty detector disabled or deleted
+            - UpdateDetector
+            - DeleteDetector
+      Targets:
+        - Id: ProwlerCloud
+          Arn: !GetAtt ProwlerRealtimeApiDestination.Arn
+          RoleArn: !GetAtt ProwlerRealtimeInvokeRole.Arn
+      Tags:
+        - Key: "Service"
+          Value: "https://prowler.com"
+        - Key: "Support"
+          Value: "support@prowler.com"
+        - Key: "CloudFormation"
+          Value: "true"
+        - Key: "Name"
+          Value: "ProwlerRealtimeDetection"
+
 Metadata:
   AWS::CloudFormation::Interface:
     ParameterGroups:
@@ -599,11 +761,17 @@ Metadata:
           - IAMPrincipal
           - EnableOrganizations
           - EnableS3Integration
+          - EnableRealtimeDetection
       - Label:
           default: Optional S3 Integration
         Parameters:
           - S3IntegrationBucketName
           - S3IntegrationBucketAccountId
+      - Label:
+          default: Optional Real-Time Detection (Required if EnableRealtimeDetection is true)
+        Parameters:
+          - ProwlerWebhookUrl
+          - ProwlerApiKey
       - Label:
           default: StackSet Configuration (Required if DeployStackSet is true)
         Parameters:
@@ -624,3 +792,17 @@ Outputs:
     Condition: DeployStackSetEnabled
     Description: "StackSet ID for the ProwlerScan role deployment across accounts"
     Value: !Ref ProwlerScanStackSet
+
+  ProwlerRealtimeRuleArn:
+    Condition: RealtimeDetectionEnabled
+    Description: "ARN of the EventBridge rule forwarding the tracked CloudTrail events to Prowler Cloud"
+    Value: !GetAtt ProwlerRealtimeRule.Arn
+    Export:
+      Name: !Sub "${AWS::StackName}-ProwlerRealtimeRuleArn"
+
+  ProwlerRealtimeApiDestinationArn:
+    Condition: RealtimeDetectionEnabled
+    Description: "ARN of the EventBridge API destination targeting Prowler Cloud"
+    Value: !GetAtt ProwlerRealtimeApiDestination.Arn
+    Export:
+      Name: !Sub "${AWS::StackName}-ProwlerRealtimeApiDestinationArn"

permissions/templates/terraform/README.md

@@ -25,6 +25,9 @@ This Terraform configuration creates the necessary IAM role and policies to allo
 - `enable_s3_integration` (optional): Enable S3 integration for storing scan reports (default: false)
 - `s3_integration_bucket_name` (conditional): S3 bucket name for reports (required if `enable_s3_integration` is true)
 - `s3_integration_bucket_account_id` (conditional): S3 bucket owner account ID (required if `enable_s3_integration` is true)
+- `enable_realtime_detection` (optional): Forward the tracked CloudTrail management events to Prowler Cloud through an EventBridge API destination (default: false)
+- `prowler_webhook_url` (conditional): Prowler Cloud endpoint that receives the events (required if `enable_realtime_detection` is true)
+- `prowler_api_key` (conditional): Prowler Cloud API key used to authenticate the events (required if `enable_realtime_detection` is true)
 
 ### Usage Examples
 
@@ -42,6 +45,17 @@ terraform apply \
   -var="s3_integration_bucket_account_id=123456789012"
 ```
 
+#### With real-time detection enabled
+```bash
+terraform apply \
+  -var="external_id=your-external-id-here" \
+  -var="enable_realtime_detection=true" \
+  -var="prowler_webhook_url=https://api.prowler.com/api/v1/realtime/events" \
+  -var="prowler_api_key=your-prowler-api-key-here"
+```
+
+> **Note:** the EventBridge rule is regional. It forwards only the events delivered to the default event bus of the region Terraform deploys to (`us-east-1` by default, see `versions.tf`). IAM events are global and always land in `us-east-1`, but regional services (EC2 security groups, RDS, per-region Config and GuardDuty) are only covered in that region. Deploy the module in every region you want covered.
+
 #### Using terraform.tfvars file (Recommended)
 ```bash
 cp terraform.tfvars.example terraform.tfvars
@@ -60,5 +74,8 @@ After successful deployment, you'll get:
 - `prowler_role_arn`: The ARN of the created IAM role (use this in Prowler App)
 - `prowler_role_name`: The name of the IAM role
 - `s3_integration_enabled`: Whether S3 integration is enabled
+- `realtime_detection_enabled`: Whether real-time detection is enabled
+- `prowler_realtime_rule_arn`: ARN of the EventBridge rule (null if real-time detection is disabled)
+- `prowler_realtime_api_destination_arn`: ARN of the EventBridge API destination (null if real-time detection is disabled)
 
 > **Note:** Terraform will use the AWS credentials of your default profile or AWS_PROFILE environment variable.

permissions/templates/terraform/main.tf

@@ -15,6 +15,13 @@ check "s3_integration_requirements" {
   }
 }
 
+check "realtime_detection_requirements" {
+  assert {
+    condition     = !var.enable_realtime_detection || (var.prowler_webhook_url != "" && var.prowler_api_key != "")
+    error_message = "When enable_realtime_detection is true, both prowler_webhook_url and prowler_api_key must be provided and non-empty."
+  }
+}
+
 # IAM Role
 ###################################
 data "aws_iam_policy_document" "prowler_assume_role_policy" {
@@ -113,8 +120,19 @@ module "s3_integration" {
 
   source = "./s3-integration"
 
-  s3_integration_bucket_name    = var.s3_integration_bucket_name
+  s3_integration_bucket_name       = var.s3_integration_bucket_name
   s3_integration_bucket_account_id = var.s3_integration_bucket_account_id
 
   prowler_role_name = aws_iam_role.prowler_scan.name
 }
+
+# Real-Time Detection Module
+###################################
+module "realtime_detection" {
+  count = var.enable_realtime_detection ? 1 : 0
+
+  source = "./realtime-detection"
+
+  prowler_webhook_url = var.prowler_webhook_url
+  prowler_api_key     = var.prowler_api_key
+}

permissions/templates/terraform/outputs.tf

@@ -20,3 +20,18 @@ output "s3_integration_enabled" {
   description = "Whether S3 integration is enabled"
   value       = var.enable_s3_integration
 }
+
+output "realtime_detection_enabled" {
+  description = "Whether real-time detection is enabled"
+  value       = var.enable_realtime_detection
+}
+
+output "prowler_realtime_rule_arn" {
+  description = "ARN of the EventBridge rule forwarding the tracked CloudTrail events to Prowler Cloud (null if real-time detection is disabled)"
+  value       = try(module.realtime_detection[0].prowler_realtime_rule_arn, null)
+}
+
+output "prowler_realtime_api_destination_arn" {
+  description = "ARN of the EventBridge API destination targeting Prowler Cloud (null if real-time detection is disabled)"
+  value       = try(module.realtime_detection[0].prowler_realtime_api_destination_arn, null)
+}

permissions/templates/terraform/realtime-detection/data.tf

@@ -0,0 +1,3 @@
+data "aws_partition" "current" {}
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}