# hardik-aws/ctaudit architecture

> Architecture diagram of the GitHub repository hardik-aws/ctaudit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hardik-aws/ctaudit
- Repository: https://github.com/hardik-aws/ctaudit

## Overview

ctaudit is an in-process AWS log auditor: users select a log family and scope, it reads objects from S3, analyzes records, and produces terminal/HTML reports with optional PDF output. Its five audit domains cover CloudTrail, ELB, WAF, S3 access, and VPC Flow Logs; long-running serve mode adds periodic scans and metrics/output integrations. The sampled sources show the shared scan, VPC and S3 processing, report and sink layers. Some domain-specific wiring is documented in the README but its implementation was not sampled, so those links are marked unverified.

Main entry points: [`cmd/ctaudit/main.go`](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/main.go) (CLI commands), [`internal/report`](https://github.com/hardik-aws/ctaudit/tree/main/internal/report) (HTML and terminal reports), [`cmd/ctaudit/serve.go`](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/serve.go) (Serve scanner), [`internal/engine/engine.go`](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/engine.go) (CloudTrail analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands and serving"]
  node_commands["CLI commands<br/>[main.go]"]
  node_cloudtrail_cmd["CloudTrail command<br/>[cloudtrail.go]"]
  node_elb_cmd["ELB command<br/>[elb.go]"]
  node_waf_cmd["WAF command<br/>[waf.go]"]
  node_s3_cmd["S3 command<br/>[s3.go]"]
  node_vpc_cmd["VPC command<br/>[vpc.go]"]
  node_serve["Serve scanner<br/>[serve.go]"]
  node_serve_state["Serve state<br/>[serve_state.go]"]
end

subgraph group_input["S3 input and decoding"]
  node_s3_source["S3 object source<br/>[store.go]"]
  node_elb_decode["ELB log decoding<br/>[elblog.go]"]
  node_waf_decode["WAF log decoding<br/>[waflog.go]"]
  node_s3_decode["S3 log decoding<br/>[s3log.go]"]
  node_vpc_decode["Flow log decoding<br/>[flowlog.go]"]
end

subgraph group_analysis["Audit analysis"]
  node_shared_scan["Shared scan engine<br/>[engine.go]"]
  node_cloudtrail["CloudTrail analysis<br/>[engine.go]"]
  node_elb["ELB analysis<br/>[elb.go]"]
  node_waf["WAF analysis<br/>[waf.go]"]
  node_s3_analysis["S3 log analysis<br/>[s3.go]"]
  node_vpc_analysis["VPC analysis<br/>[vpc.go]"]
  node_cloudtrail_rules["CloudTrail rules<br/>[rules.go]"]
  node_s3_rules["S3 findings<br/>[rules.go]"]
  node_waf_rules["WAF findings<br/>[rules.go]"]
  node_vpc_rules["VPC findings<br/>[rules.go]"]
  node_stats["Domain summaries"]
end

subgraph group_presentation["Reports and exports"]
  node_reports["HTML and terminal reports"]
  node_pdf["PDF reports<br/>[pdf.go]"]
end

subgraph group_operations["Serve integrations"]
  node_sink["Output sinks<br/>[lines.go]"]
  node_metrics["Prometheus metrics<br/>[metrics.go]"]
  node_loki["Loki output<br/>[loki.go]"]
end

node_operator(("Auditor"))
node_s3_bucket[("Log bucket")]
node_http_client(("HTTP clients"))

node_operator -->|"selects command"| node_commands
node_commands -.->|"routes to"| node_cloudtrail_cmd
node_commands -.->|"routes to"| node_elb_cmd
node_commands -.->|"routes to"| node_waf_cmd
node_commands -.->|"routes to"| node_s3_cmd
node_commands -.->|"routes to"| node_vpc_cmd
node_s3_bucket -->|"serves objects"| node_s3_source
node_s3_source -->|"lists and fetches"| node_shared_scan
node_shared_scan -.->|"runs scan"| node_cloudtrail
node_cloudtrail_cmd -.->|"starts audit"| node_cloudtrail
node_elb_cmd -.->|"starts audit"| node_elb
node_waf_cmd -.->|"starts audit"| node_waf
node_s3_cmd -.->|"starts audit"| node_s3_analysis
node_vpc_cmd -->|"runs audit"| node_vpc_analysis
node_s3_decode -->|"decodes records"| node_s3_analysis
node_vpc_decode -->|"decodes flows"| node_vpc_analysis
node_elb_decode -.->|"decodes entries"| node_elb
node_waf_decode -.->|"decodes requests"| node_waf
node_cloudtrail -->|"inspects events"| node_cloudtrail_rules
node_cloudtrail -->|"aggregates records"| node_stats
node_s3_analysis -->|"detects findings"| node_s3_rules
node_s3_analysis -->|"aggregates entries"| node_stats
node_vpc_analysis -->|"detects findings"| node_vpc_rules
node_vpc_analysis -->|"aggregates flows"| node_stats
node_waf -.->|"detects findings"| node_waf_rules
node_elb -.->|"aggregates traffic"| node_stats
node_cloudtrail_cmd -->|"renders reports"| node_reports
node_elb_cmd -->|"renders reports"| node_reports
node_waf_cmd -->|"renders reports"| node_reports
node_s3_cmd -->|"renders reports"| node_reports
node_vpc_cmd -->|"renders reports"| node_reports
node_reports -.->|"optionally renders"| node_pdf
node_serve -.->|"runs scans"| node_shared_scan
node_serve -->|"updates state"| node_serve_state
node_serve -->|"emits records"| node_sink
node_sink -.->|"exports metrics"| node_metrics
node_sink -.->|"pushes output"| node_loki
node_http_client -->|"requests endpoints"| node_serve

click node_commands "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/main.go"
click node_cloudtrail_cmd "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/cloudtrail.go"
click node_elb_cmd "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/elb.go"
click node_waf_cmd "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/waf.go"
click node_s3_cmd "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/s3.go"
click node_vpc_cmd "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/vpc.go"
click node_serve "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/serve.go"
click node_serve_state "https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/serve_state.go"
click node_s3_source "https://github.com/hardik-aws/ctaudit/blob/main/internal/s3src/store.go"
click node_shared_scan "https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/engine.go"
click node_cloudtrail "https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/engine.go"
click node_elb "https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/elb.go"
click node_waf "https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/waf.go"
click node_s3_analysis "https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/s3.go"
click node_vpc_analysis "https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/vpc.go"
click node_cloudtrail_rules "https://github.com/hardik-aws/ctaudit/blob/main/internal/findings/rules.go"
click node_s3_rules "https://github.com/hardik-aws/ctaudit/blob/main/internal/s3rules/rules.go"
click node_waf_rules "https://github.com/hardik-aws/ctaudit/blob/main/internal/wafrules/rules.go"
click node_vpc_rules "https://github.com/hardik-aws/ctaudit/blob/main/internal/vpcrules/rules.go"
click node_stats "https://github.com/hardik-aws/ctaudit/tree/main/internal/stats"
click node_elb_decode "https://github.com/hardik-aws/ctaudit/blob/main/internal/elblog/elblog.go"
click node_waf_decode "https://github.com/hardik-aws/ctaudit/blob/main/internal/waflog/waflog.go"
click node_s3_decode "https://github.com/hardik-aws/ctaudit/blob/main/internal/s3log/s3log.go"
click node_vpc_decode "https://github.com/hardik-aws/ctaudit/blob/main/internal/flowlog/flowlog.go"
click node_reports "https://github.com/hardik-aws/ctaudit/tree/main/internal/report"
click node_pdf "https://github.com/hardik-aws/ctaudit/blob/main/internal/report/pdf.go"
click node_sink "https://github.com/hardik-aws/ctaudit/blob/main/internal/sink/lines.go"
click node_metrics "https://github.com/hardik-aws/ctaudit/blob/main/internal/sink/metrics.go"
click node_loki "https://github.com/hardik-aws/ctaudit/blob/main/internal/sink/loki.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_commands,node_cloudtrail_cmd,node_elb_cmd,node_waf_cmd,node_s3_cmd,node_vpc_cmd,node_serve,node_serve_state,node_http_client toneBlue
class node_s3_source,node_elb_decode,node_waf_decode,node_s3_decode,node_vpc_decode,node_s3_bucket toneAmber
class node_shared_scan,node_cloudtrail,node_elb,node_waf,node_s3_analysis,node_vpc_analysis,node_cloudtrail_rules,node_s3_rules,node_waf_rules,node_vpc_rules,node_stats toneMint
class node_reports,node_pdf toneRose
class node_sink,node_metrics,node_loki,node_operator toneIndigo
```

## Components

### Commands and serving

- [CLI commands](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/main.go): `cmd/ctaudit/main.go`
- [CloudTrail command](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/cloudtrail.go): `cmd/ctaudit/cloudtrail.go`
- [ELB command](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/elb.go): `cmd/ctaudit/elb.go`
- [WAF command](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/waf.go): `cmd/ctaudit/waf.go`
- [S3 command](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/s3.go): `cmd/ctaudit/s3.go`
- [VPC command](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/vpc.go): `cmd/ctaudit/vpc.go`
- [Serve scanner](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/serve.go): `cmd/ctaudit/serve.go`
- [Serve state](https://github.com/hardik-aws/ctaudit/blob/main/cmd/ctaudit/serve_state.go): `cmd/ctaudit/serve_state.go`

### S3 input and decoding

- [S3 object source](https://github.com/hardik-aws/ctaudit/blob/main/internal/s3src/store.go): `internal/s3src/store.go`
- [ELB log decoding](https://github.com/hardik-aws/ctaudit/blob/main/internal/elblog/elblog.go): `internal/elblog/elblog.go`
- [WAF log decoding](https://github.com/hardik-aws/ctaudit/blob/main/internal/waflog/waflog.go): `internal/waflog/waflog.go`
- [S3 log decoding](https://github.com/hardik-aws/ctaudit/blob/main/internal/s3log/s3log.go): `internal/s3log/s3log.go`
- [Flow log decoding](https://github.com/hardik-aws/ctaudit/blob/main/internal/flowlog/flowlog.go): `internal/flowlog/flowlog.go`

### Audit analysis

- [Shared scan engine](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [CloudTrail analysis](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/engine.go): `internal/engine/engine.go`
- [ELB analysis](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/elb.go): `internal/engine/elb.go`
- [WAF analysis](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/waf.go): `internal/engine/waf.go`
- [S3 log analysis](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/s3.go): `internal/engine/s3.go`
- [VPC analysis](https://github.com/hardik-aws/ctaudit/blob/main/internal/engine/vpc.go): `internal/engine/vpc.go`
- [CloudTrail rules](https://github.com/hardik-aws/ctaudit/blob/main/internal/findings/rules.go): `internal/findings/rules.go`
- [S3 findings](https://github.com/hardik-aws/ctaudit/blob/main/internal/s3rules/rules.go): `internal/s3rules/rules.go`
- [WAF findings](https://github.com/hardik-aws/ctaudit/blob/main/internal/wafrules/rules.go): `internal/wafrules/rules.go`
- [VPC findings](https://github.com/hardik-aws/ctaudit/blob/main/internal/vpcrules/rules.go): `internal/vpcrules/rules.go`
- [Domain summaries](https://github.com/hardik-aws/ctaudit/tree/main/internal/stats): `internal/stats`

### Reports and exports

- [HTML and terminal reports](https://github.com/hardik-aws/ctaudit/tree/main/internal/report): `internal/report`
- [PDF reports](https://github.com/hardik-aws/ctaudit/blob/main/internal/report/pdf.go): `internal/report/pdf.go`

### Serve integrations

- [Output sinks](https://github.com/hardik-aws/ctaudit/blob/main/internal/sink/lines.go): `internal/sink/lines.go`
- [Prometheus metrics](https://github.com/hardik-aws/ctaudit/blob/main/internal/sink/metrics.go): `internal/sink/metrics.go`
- [Loki output](https://github.com/hardik-aws/ctaudit/blob/main/internal/sink/loki.go): `internal/sink/loki.go`

### Other components

- **Auditor**
- **Log bucket**
- **HTTP clients**

## Connections

- Auditor → CLI commands: selects command (evidence: `README.md`)
- CLI commands → CloudTrail command: routes to
- CLI commands → ELB command: routes to
- CLI commands → WAF command: routes to
- CLI commands → S3 command: routes to
- CLI commands → VPC command: routes to
- Log bucket → S3 object source: serves objects (evidence: `README.md`)
- S3 object source → Shared scan engine: lists and fetches (evidence: `internal/engine/engine.go`)
- Shared scan engine → CloudTrail analysis: runs scan (evidence: `internal/engine/engine.go`)
- CloudTrail command → CloudTrail analysis: starts audit
- ELB command → ELB analysis: starts audit
- WAF command → WAF analysis: starts audit
- S3 command → S3 log analysis: starts audit
- VPC command → VPC analysis: runs audit (evidence: `cmd/ctaudit/vpc.go`)
- S3 log decoding → S3 log analysis: decodes records (evidence: `internal/engine/s3.go`)
- Flow log decoding → VPC analysis: decodes flows (evidence: `internal/engine/vpc.go`)
- ELB log decoding → ELB analysis: decodes entries
- WAF log decoding → WAF analysis: decodes requests
- CloudTrail analysis → CloudTrail rules: inspects events (evidence: `internal/engine/engine.go`)
- CloudTrail analysis → Domain summaries: aggregates records (evidence: `internal/engine/engine.go`)
- S3 log analysis → S3 findings: detects findings (evidence: `internal/engine/s3.go`)
- S3 log analysis → Domain summaries: aggregates entries (evidence: `internal/engine/s3.go`)
- VPC analysis → VPC findings: detects findings (evidence: `internal/engine/vpc.go`)
- VPC analysis → Domain summaries: aggregates flows (evidence: `internal/engine/vpc.go`)
- WAF analysis → WAF findings: detects findings
- ELB analysis → Domain summaries: aggregates traffic
- CloudTrail command → HTML and terminal reports: renders reports (evidence: `README.md`)
- ELB command → HTML and terminal reports: renders reports (evidence: `README.md`)
- WAF command → HTML and terminal reports: renders reports (evidence: `README.md`)
- S3 command → HTML and terminal reports: renders reports (evidence: `README.md`)
- VPC command → HTML and terminal reports: renders reports (evidence: `cmd/ctaudit/vpc.go`)
- HTML and terminal reports → PDF reports: optionally renders (evidence: `README.md`)
- Serve scanner → Shared scan engine: runs scans
- Serve scanner → Serve state: updates state (evidence: `cmd/ctaudit/serve.go`)
- Serve scanner → Output sinks: emits records (evidence: `cmd/ctaudit/serve.go`)
- Output sinks → Prometheus metrics: exports metrics
- Output sinks → Loki output: pushes output
- HTTP clients → Serve scanner: requests endpoints (evidence: `README.md`)