"Because bad logs are the blue pill."

Imagine a security camera system that records everything — except when you need the footage, you discover it was never turned on. That's what happens when AWS CloudTrail is misconfigured.

What breaks when CloudTrail is misconfigured:

• You can't prove who did what. When a breach happens, investigators need immutable audit logs to trace the attacker's path. Without proper log file validation, those logs can be modified after the fact — making them useless as evidence.

• You fail audits. SOC 2 and ISO 27001 require evidence of operational security. If your CloudTrail isn't multi-region, isn't encrypted at rest, or doesn't send logs to CloudWatch, you'll face finding after finding.

• You have no alert when something goes wrong. A misconfigured trail is like a smoke detector with no batteries. You only discover the fire when it's already too late.

• Your insurance claim gets denied. Cyber insurance policies increasingly require proof of logging and monitoring. Misconfigured CloudTrail = denied claims.

For non-technical stakeholders: TrailWarden answers the question "Are our cloud audit logs actually working?" — and provides the evidence to prove it.

I built TrailWarden after watching compliance teams spend 3-5 days manually clicking through AWS console, screenshotting configurations, and building spreadsheets that were outdated the moment they were created. I realized these teams were doing manually in days what code could do in seconds.

The final straw was watching an auditor ask for "evidence of CloudTrail log file integrity" — and the team scrambling to explain that AWS has this feature, but nobody had ever enabled it. They had no way to prove their logs hadn't been tampered with. The answer lived in a checkbox buried in the console, and nobody knew it was off.

So I built the tool I wanted to exist: one that scans all your CloudTrail trails across all regions, runs the 10 critical compliance checks, classifies risk, and produces audit-ready reports — with ready-to-run AWS CLI commands to fix whatever it finds.

This isn't a compliance tool that makes you fill out forms. It's a GRC engineering tool that treats compliance as code — version-controlled, repeatable, and automatically verified. Every run produces evidence. Every finding includes remediation. Every report is ready for an auditor.

TrailWarden demonstrates that I don't just understand compliance frameworks — I can operationalize them. I can take something that takes days of manual work and turn it into a single command that runs in seconds. That's what I'm building my next role around.

Feature	What It Does	Compliance Control	Risk if Missing
Multi-Region Trail Coverage	Verifies CloudTrail is capturing events from all AWS regions, not just one	SOC 2 CC7.2, NIST AU-2
Log File Integrity Validation	Confirms cryptographic signing is enabled so logs can't be tampered with	NIST AU-9(3), NIST SI-7(5)
S3 Bucket Encryption	Checks that the CloudTrail S3 bucket has default encryption enabled	NIST AU-9, SOC 2 CC7.2
KMS Key Encryption	Verifies CloudTrail is using a customer-managed KMS key for additional encryption layer	NIST AU-9
CloudWatch Logs Integration	Confirms CloudTrail is streaming to CloudWatch for real-time alerting and retention	NIST AU-12, SOC 2 CC7.2
Trail Active Status	Verifies logging is actually turned on (yes, it can be accidentally disabled)	NIST AU-2
S3 Server Access Logging	Confirms S3 access logging is enabled to track who accesses your log bucket	NIST AU-9
S3 Public Access Block	Ensures the CloudTrail log bucket can't be accidentally made public	NIST AU-9
MFA Delete on S3 Bucket	Verifies MFA delete is enabled on the bucket to prevent accidental/l malicious deletion	NIST AU-9
Management Events Scope	Confirms management events (not just data events) are being captured	NIST AU-3

flowchart TB
    subgraph CLI["CLI Entry Point"]
        A["python cloudtrail_compliance_validator.py"] --> B["--dry-run / --profile / --region"]
    end

    subgraph Auth["AWS Authentication"]
        B --> C{Use Mock Data?}
        C -->|Yes| D["Dry-Run Mode"]
        C -->|No| E["boto3 Session"]
        E --> F["sts:GetCallerIdentity"]
        F --> G["Validate Credentials"]
    end

    subgraph Discovery["Region Discovery"]
        G --> H["ec2:DescribeRegions"]
    end

    subgraph Fetch["Trail Fetcher"]
        H --> I["cloudtrail:DescribeTrails"]
        I --> J["For Each Trail..."]
    end

    subgraph Validation["Compliance Validation"]
        J --> K["Run 10 Checks in Parallel"]
        K --> L1["Multi-Region Coverage"]
        K --> L2["Log File Validation"]
        K --> L3["S3 Encryption"]
        K --> L4["KMS Encryption"]
        K --> L5["CloudWatch Logs"]
        K --> L6["Trail Status"]
        K --> L7["S3 Access Logging"]
        K --> L8["S3 Public Access"]
        K --> L9["MFA Delete"]
        K --> L10["Management Events"]
        
        L1 --> M{"HIGH Risk?"}
        L2 --> M
        L3 --> M
        M -->|Yes| N["HIGH Risk Path"]
        M -->|No| O{"MEDIUM Risk?"}
        O -->|Yes| P["MEDIUM Risk Path"]
        O -->|No| Q{"LOW Risk?"}
        Q -->|Yes| R["LOW Risk Path"]
        Q -->|No| S["COMPLIANT Path"]
        
        style N fill:#fee2e2,stroke:#f87171,stroke-width:2px
        style P fill:#fef3c7,stroke:#fbbf24,stroke-width:2px
        style R fill:#f3e8ff,stroke:#a78bfa,stroke-width:2px
        style S fill:#dcfce7,stroke:#4ade80,stroke-width:2px
    end

    subgraph Risk["Risk Classifier"]
        M --> T["classify_trail_risk()"]
        T --> U["HIGH / MEDIUM / LOW / COMPLIANT"]
    end

    subgraph Reports["Report Generator"]
        U --> V["Generate JSON Report"]
        U --> W["Generate CSV Report"]
        U --> X["Generate XLSX Report"]
        U --> Y["Generate HTML Report"]
    end

    subgraph Output["Console Summary"]
        V --> Z["✓ Report: cloudtrail_compliance_report.json"]
        W --> AA["✓ Report: cloudtrail_compliance_report.csv"]
        X --> AB["✓ Report: cloudtrail_compliance_report.xlsx"]
        Y --> AC["✓ Report: cloudtrail_compliance_report.html"]
    end

    D --> J

SOC 2 (Service Organization Control 2) is a widely recognized audit framework that demonstrates a company has appropriate controls for protecting customer data. NIST 800-53 is the US federal government's security control framework, widely adopted in regulated industries.

TrailWarden uses a hierarchical risk classification system that ensures the most critical issues bubble to the top:

Plain English explanation: If any HIGH-risk check fails, the entire trail is classified as HIGH risk. If no HIGH risks exist but a MEDIUM risk fails, it's MEDIUM. If only LOW risks fail, it's LOW. If everything passes, it's COMPLIANT.

flowchart TD
    A["Start: Evaluate All Checks"] --> B{"Any HIGH-risk checks<br/>with FAIL status?"}
    
    B -->|Yes| C["Trail = HIGH Risk"]
    B -->|No| D{"Any MEDIUM-risk checks<br/>with FAIL status?"}
    
    D -->|Yes| E["Trail = MEDIUM Risk"]
    D -->|No| F{"Any LOW-risk checks<br/>with FAIL status?"}
    
    F -->|Yes| G["Trail = LOW Risk"]
    F -->|No| H["Trail = COMPLIANT"]
    
    C --> I["🚨 Urgent: Fix immediately<br/>Audit finding likely"]
    E --> J["⚠️ Important: Plan remediation<br/>Document risk acceptance if needed"]
    G --> K["📝 Low: Schedule improvement<br/>Not urgent but worth fixing"]
    H --> L["✅ Clean: All checks passing<br/>Evidence ready for auditors"]
    
    style C fill:#fee2e2,stroke:#f87171,stroke-width:3px
    style E fill:#fef3c7,stroke:#fbbf24,stroke-width:3px
    style G fill:#f3e8ff,stroke:#a78bfa,stroke-width:3px
    style H fill:#dcfce7,stroke:#4ade80,stroke-width:3px

{
  "scan_metadata": {
    "scan_date": "2026-03-23T16:09:30+00:00",
    "aws_account_id": "123456789012",
    "total_trails_scanned": 1,
    "compliant_trails": 0,
    "high_risk_trails": 0,
    "medium_risk_trails": 1,
    "low_risk_trails": 0
  },
  "trails": [
    {
      "trail_name": "legacy-migration-trail",
      "trail_arn": "arn:aws:cloudtrail:us-west-2:123456789012:trail/legacy-migration-trail",
      "home_region": "us-west-2",
      "overall_risk": "MEDIUM",
      "checks": [
        {
          "check_name": "Multi-Region Coverage",
          "status": "FAIL",
          "risk_level": "HIGH",
          "compliance_mappings": ["SOC2_CC7.2", "NIST_AU-2"],
          "details": "IsMultiRegionTrail: False, IncludeGlobalServiceEvents: False",
          "remediation_cli": "aws cloudtrail update-trail --name legacy-migration-trail --is-multi-region-trail --include-global-service-events"
        },
        {
          "check_name": "KMS Encryption",
          "status": "FAIL",
          "risk_level": "MEDIUM",
          "compliance_mappings": ["NIST_AU-9"],
          "details": "KMSKeyId: Not Set",
          "remediation_cli": "aws cloudtrail update-trail --name legacy-migration-trail --kms-key-id <your-kms-key-arn>"
        },
        {
          "check_name": "Log File Validation",
          "status": "PASS",
          "risk_level": "HIGH",
          "compliance_mappings": ["NIST_AU-9(3)", "NIST_SI-7(5)"],
          "details": "LogFileValidationEnabled: True",
          "remediation_cli": ""
        }
      ]
    }
  ]
}

legacy-migration-trail,arn:aws:cloudtrail:us-west-2:123456789012:trail/legacy-migration-trail,us-west-2,MEDIUM,Multi-Region Coverage,FAIL,HIGH,SOC2_CC7.2|NIST_AU-2,IsMultiRegionTrail: False, IncludeGlobalServiceEvents: False,aws cloudtrail update-trail --name legacy-migration-trail --is-multi-region-trail --include-global-service-events

• Python 3.9 or later — Check with python --version
• AWS CLI configured — Run aws configure or use IAM role/SSO
• IAM permissions — See the Security section below for the exact policy

# Clone the repository
git clone https://github.com/webber/trailwarden.git
cd trailwarden

# Install dependencies
pip install -r requirements.txt

# Example 1: Basic scan using the default AWS profile and region
# No flags needed — uses your default credentials and scans all regions
python cloudtrail_compliance_validator.py

# Example 2: Scan a specific region with verbose output
# --region limits scan to one region; --verbose prints each check as it runs
python cloudtrail_compliance_validator.py --region us-east-1 --verbose

# Example 3: Use a specific AWS profile and output only JSON to a custom directory
# --profile uses a named AWS credential profile; --output-dir sets where reports go
python cloudtrail_compliance_validator.py --profile prod-admin --format json --output-dir ./audit-evidence

# Example 4: Dry-run mode (no AWS credentials required)
# Perfect for testing or demonstrations — uses detailed mock data
python cloudtrail_compliance_validator.py --dry-run --format both --verbose

Why read-only matters: Junior developers often forget that security tools need write permissions "just in case." But auditors trust tools that can't modify their environment. By using only read-only IAM permissions, TrailWarden signals to security teams that it's designed for assessment, not operation — the same mindset you'd want in a penetration tester or compliance auditor.

The principle: A compliance tool should never be able to change what it's measuring. If it could, the measurement becomes unreliable.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TrailWardenReadOnly",
      "Effect": "Allow",
      "Action": [
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:GetEventSelectors",
        "cloudtrail:ListTrails",
        "s3:GetBucketAcl",
        "s3:GetBucketEncryption",
        "s3:GetBucketLogging",
        "s3:GetBucketPolicy",
        "s3:GetBucketPublicAccessBlock",
        "s3:GetBucketVersioning",
        "s3:ListBucket",
        "ec2:DescribeRegions",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

Note: This policy contains zero write permissions. It cannot:

• Modify any CloudTrail configuration
• Change any S3 bucket settings
• Enable or disable logging
• Create or delete resources

This is intentional. The tool is designed for assessment only. For production use, attach this policy to an IAM role with least-privilege access.

TrailWarden is designed to run in automated pipelines. Here's a complete GitHub Actions workflow that runs weekly and on-demand:

name: TrailWarden Compliance Scan

on:
  schedule:
    # Run every Monday at 6 AM UTC
    - cron: '0 6 * * 1'
  workflow_dispatch:
    # Allow manual trigger
  pull_request:
    branches: [main]

permissions:
  id-token: write   # Required for OIDC
  contents: read

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/TrailWardenAuditRole
          aws-region: us-east-1

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt

      - name: Run TrailWarden
        run: |
          python cloudtrail_compliance_validator.py \
            --output-dir ./reports \
            --format both \
            --verbose

      - name: Upload reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: compliance-reports
          path: ./reports/*
          retention-days: 90

Why OIDC (OpenID Connect) matters: This workflow uses IAM role assumption instead of static AWS access keys. This is the mature approach because:

• No long-lived credentials stored in GitHub
• Credentials are automatically rotated by GitHub
• You can revoke access instantly by modifying the IAM role
• It's what security-conscious teams expect in 2026

Compliance Should Be Engineered, Not Administered

Traditional GRC (Governance, Risk, and Compliance) is stuck in the 2000s. It's manual, reactive, and spreadsheet-driven. Teams spend weeks preparing for audits that take minutes to complete — not because the work is complex, but because it's repetitive and disconnected from actual systems.

I don't think that's acceptable anymore.

GRC engineering is the practice of treating compliance as software:

• Automated: Code runs on schedules or triggers, not human memory
• Proactive: Issues are caught before audits, not during them
• Evidence-first: Every finding includes proof, not just assertions
• Version-controlled: Compliance state is tracked in git, not shared drives

TrailWarden is my proof-of-concept for this philosophy. It's not a product — it's a demonstration that compliance can be operationalized. That you can answer an auditor's question in seconds, not days. That you can show your CISO exactly where the risk is, right now, with evidence.

That's the work I want to do. I'm looking for a team that treats compliance as a technical problem to be solved, not a administrative burden to be tolerated. If that's the kind of engineering culture you're building, I want to be part of it.

• GitHub: github.com/webber
• LinkedIn: linkedin.com/in/webber

"There is no spoon." — The realization that changes everything about what's possible.

TrailWarden — because your audit evidence shouldn't depend on whether someone remembered to click a checkbox in the AWS console.