# cred-club/dial architecture

> Architecture diagram of the GitHub repository cred-club/dial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cred-club/dial
- Repository: https://github.com/cred-club/dial

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Multiple AWS Accounts (Child Controllers)"
        direction TB
        EB["EventBridge"]:::integration
        EB -->|"Event Pattern"| EC2["Lambda: EC2EventHandler"]:::compute
        EB -->|"Event Pattern"| S3EH["Lambda: S3EventHandler"]:::compute
        EB -->|"Event Pattern"| IAMEH["Lambda: IAMEventHandler"]:::compute
        EB -->|"Event Pattern"| SSMeh["Lambda: SSMEventHandler"]:::compute
        EB -->|"Event Pattern"| GDEH["Lambda: GDEventHandler"]:::compute
        EB -->|"Event Pattern"| SMEH["Lambda: SecretsManagerEventHandler"]:::compute
        EB -->|"Event Pattern"| REH["Lambda: RootEC2EventHandler"]:::compute
        EB -->|"Event Pattern"| GEC["Lambda: GenericEventClassifier"]:::compute
        GEC -->|"dispatch"| DIAL["Lambda: dial.py"]:::compute
        DIAL -->|"sendAlert()"| NS["NotificationService"]:::notification
        CONF_C["config.yaml"]:::config
        CONF_C --> DIAL
        NS -->|"Slack Webhook"| SLACK["Slack"]:::notification
        DIAL -->|"HTTP POST"| APIGW["API Gateway"]:::integration
    end

    subgraph "Parent Account"
        direction TB
        APIGW -->|"POST /alert"| PL["Lambda: lambda_function.py"]:::compute
        CONF_P["config.yaml"]:::config
        CONF_P --> PL
        PL -->|"enrich"| STORE["S3 / DynamoDB"]:::datastore
        PL -->|"push"| THEHIVE["TheHive / SIEM"]:::datastore
    end

    subgraph "Deployment & Utilities"
        direction TB
        CFN1["cfn/child-deployment-stack.yaml"]:::infra
        CFN2["cfn/child-stack-set-cfn-template.yaml"]:::infra
        CFN3["cfn/master-deployment-stack.yaml"]:::infra
        CFN4["cfn/s3-buckets.yaml"]:::infra
        CFN5["cfn/eventBridge/"]:::infra
        CFN6["cfn/DEPLOY.md"]:::infra
        UT["utils/validate-child-config.py"]:::infra
        REQ["requirements.txt"]:::infra
        MF["Makefile"]:::infra
        AWSMD["AWS-APIs.md"]:::infra
        README["README.md"]:::infra
    end

    click EC2 "https://github.com/cred-club/dial/blob/main/child/EC2EventHandler.py"
    click GDEH "https://github.com/cred-club/dial/blob/main/child/GDEventHandler.py"
    click IAMEH "https://github.com/cred-club/dial/blob/main/child/IAMEventHandler.py"
    click SSMeh "https://github.com/cred-club/dial/blob/main/child/SSMEventHandler.py"
    click SMEH "https://github.com/cred-club/dial/blob/main/child/SecretsManagerEventHandler.py"
    click S3EH "https://github.com/cred-club/dial/blob/main/child/s3EventHandler.py"
    click REH "https://github.com/cred-club/dial/blob/main/child/RootEC2EventHandler.py"
    click GEC "https://github.com/cred-club/dial/blob/main/child/GenericEventClassifier.py"
    click DIAL "https://github.com/cred-club/dial/blob/main/child/dial.py"
    click NS "https://github.com/cred-club/dial/blob/main/child/NotificationService.py"
    click CONF_C "https://github.com/cred-club/dial/blob/main/child/config.yaml"
    click PL "https://github.com/cred-club/dial/blob/main/master/lambda_function.py"
    click CONF_P "https://github.com/cred-club/dial/blob/main/master/config.yaml"
    click CFN1 "https://github.com/cred-club/dial/blob/main/cfn/child-deployment-stack.yaml"
    click CFN2 "https://github.com/cred-club/dial/blob/main/cfn/child-stack-set-cfn-template.yaml"
    click CFN3 "https://github.com/cred-club/dial/blob/main/cfn/master-deployment-stack.yaml"
    click CFN4 "https://github.com/cred-club/dial/blob/main/cfn/s3-buckets.yaml"
    click CFN5 "https://github.com/cred-club/dial/tree/main/cfn/eventBridge/"
    click CFN6 "https://github.com/cred-club/dial/blob/main/cfn/DEPLOY.md"
    click UT "https://github.com/cred-club/dial/blob/main/utils/validate-child-config.py"
    click REQ "https://github.com/cred-club/dial/blob/main/requirements.txt"
    click MF "https://github.com/cred-club/dial/tree/main/Makefile"
    click AWSMD "https://github.com/cred-club/dial/blob/main/AWS-APIs.md"
    click README "https://github.com/cred-club/dial/blob/main/README.md"

    classDef compute fill:#c6f5c6,stroke:#333,stroke-width:1px
    classDef integration fill:#c6d8f5,stroke:#333,stroke-width:1px
    classDef datastore fill:#f5e88e,stroke:#333,stroke-width:1px
    classDef notification fill:#f5cc8e,stroke:#333,stroke-width:1px
    classDef config fill:#e0b3ff,stroke:#333,stroke-width:1px
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px
```
