How cred-club/dial works
Project Type and Purpose
• Type: Serverless, event-driven security detection framework on AWS
• Purpose: Detect cloud misconfigurations in near real-time (<7s) across multiple AWS accounts and regions, alert via Slack and forward events to a central controller for SIEM/IR ingestion
File Structure
• cfn/ – CloudFormation templates for deploying both Parent and Child controllers (EventBridge rules, API Gateway, Lambda permissions, S3, IAM roles, StackSets for multi-account)
• child/ – Python Lambda code for each event‐handler module (EC2, S3, IAM, VPC, GuardDuty, Secrets Manager, etc.), plus config.yaml, utils, and notification logic
• master/ – Python Lambda code behind API Gateway (aggregator), plus its own config.yaml
• utils/ – Scripts for validating child configurations before deployment
• requirements.txt – Python dependencies; Makefile & DEPLOY.md orchestrate deployment
Extract Key Architectural Insights from README
• Two logical controllers:
– Child Controller: deployed into each target account/region, triggered by EventBridge on-demand
– Parent Controller: single centralized service behind API Gateway to aggregate, store, or forward alerts
• Uses AWS Managed Services only: EventBridge, Lambda, API Gateway, CloudFormation, optional TheHive IR, S3/persistent storage
Main Components and Their Interactions
a. Child Account (deployed via cfn child-stack):
• AWS EventBridge (custom rules for EC2, S3, IAM, etc.)
• Child Lambda Functions (one per event type or a generic dispatcher in dial.py)
• config.yaml defines Slack webhook, severity mappings, parent API endpoint
• NotificationService pushes alerts to Slack
• After local alerting, Lambdas invoke Parent API Gateway endpoint to forward full event object
b. Parent Account (deployed via cfn master-stack):
• AWS API Gateway (secured, configurable auth)
• Parent Lambda (lambda_function.py) receives incoming child payloads
• Processing: optional enrichment, transformation
• Persistence: write to S3/DynamoDB or push to TheHive/SIEM/IR tools
• (Optionally) downstream analytics or dashboards
c. Deployment & Configuration:
• CloudFormation templates in cfn/ for bootstrapping all resources
• StackSet for multi-account child deployment (child-stack-set-cfn-template.yaml)
• validate-child-config.py ensures each child config.yaml is correct before rollout
Architectural Patterns & Design Principles
• Event-Driven Architecture: EventBridge triggers Lambda only on matching events → cost-efficient & low latency
• Modular Handlers: One handler per service/use-case for easy extensibility
• Multi-Account Pattern: Child Controller deployed per account via StackSet, isolated execution
• API-Driven Aggregation: Child→Parent communication through HTTP API layer