# trailsamuel/cloudsec-range architecture

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

- Interactive diagram: https://gitdiagram.com/trailsamuel/cloudsec-range
- Repository: https://github.com/trailsamuel/cloudsec-range

## Overview

cloudsec-range pairs an intentionally misconfigured AWS training range with a boto3 scanner evaluated against a ground-truth findings manifest. The operator deploys the range, runs a regional or multi-region scan, and receives findings plus recall scoring. The scanner entry point dispatches registered service checks; shared context and finding types support them. Terraform’s documented resource domains and all four scanner check modules are represented. Terraform’s deployment wiring and some check implementations were not excerpted, so those relationships are included only where the README documents them.

Main entry points: [`scanner/__main__.py`](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/__main__.py) (Scan Runner), [`scanner/core.py`](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/core.py) (Check Registry), [`scanner/checks_ec2.py`](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_ec2.py) (EC2 Checks), [`scanner/checks_iam.py`](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_iam.py) (IAM Checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_range["AWS Range"]
  node_network["Network<br/>[network.tf]"]
  node_iamrange["IAM Resources<br/>[iam.tf]"]
  node_s3range["S3 Resources<br/>[s3.tf]"]
  node_ec2range["EC2 Resources<br/>[ec2.tf]"]
  node_rdsrange["RDS Resources<br/>[rds.tf]"]
  node_safety["Budget Safety<br/>[safety.tf]"]
end

subgraph group_scan["Scanner"]
  node_entry["Scan Runner<br/>[__main__.py]"]
  node_core["Check Registry<br/>[core.py]"]
  node_ec2checks["EC2 Checks<br/>[checks_ec2.py]"]
  node_iamchecks["IAM Checks<br/>[checks_iam.py]"]
  node_s3checks["S3 Checks<br/>[checks_s3.py]"]
  node_cloudtrailchecks["CloudTrail RDS Checks"]
end

subgraph group_evaluation["Ground Truth"]
  node_manifest["Expected Findings"]
  node_results["Findings and Recall<br/>[__main__.py]"]
end

node_operator(("Operator"))
node_aws{{"AWS Account"}}

node_operator -->|"deploys range"| node_network
node_operator -->|"runs scan"| node_entry
node_network -->|"provisions resources"| node_aws
node_iamrange -->|"provisions resources"| node_aws
node_s3range -->|"provisions resources"| node_aws
node_ec2range -->|"provisions resources"| node_aws
node_rdsrange -->|"provisions resources"| node_aws
node_safety -->|"provisions budget alarm"| node_aws
node_entry -->|"gets registered checks"| node_core
node_entry -->|"dispatches checks"| node_ec2checks
node_entry -->|"dispatches checks"| node_iamchecks
node_entry -->|"dispatches checks"| node_s3checks
node_entry -->|"dispatches checks"| node_cloudtrailchecks
node_ec2checks -->|"uses context and findings"| node_core
node_iamchecks -->|"uses context and findings"| node_core
node_s3checks -->|"uses context and findings"| node_core
node_cloudtrailchecks -->|"uses context and findings"| node_core
node_ec2checks -->|"audits EC2 and IAM"| node_aws
node_iamchecks -->|"audits IAM"| node_aws
node_s3checks -->|"audits S3"| node_aws
node_cloudtrailchecks -->|"audits CloudTrail and RDS"| node_aws
node_entry -->|"scores against"| node_manifest
node_entry -->|"formats findings and recall"| node_results
node_results -->|"reports results"| node_operator

click node_network "https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/network.tf"
click node_iamrange "https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/iam.tf"
click node_s3range "https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/s3.tf"
click node_ec2range "https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/ec2.tf"
click node_rdsrange "https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/rds.tf"
click node_safety "https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/safety.tf"
click node_entry "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/__main__.py"
click node_core "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/core.py"
click node_ec2checks "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_ec2.py"
click node_iamchecks "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_iam.py"
click node_s3checks "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_s3.py"
click node_cloudtrailchecks "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_cloudtrail.py"
click node_manifest "https://github.com/trailsamuel/cloudsec-range/blob/main/findings/expected_findings.json"
click node_results "https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/__main__.py"

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_network,node_iamrange,node_s3range,node_ec2range,node_rdsrange,node_safety toneBlue
class node_entry,node_core,node_ec2checks,node_iamchecks,node_s3checks,node_cloudtrailchecks toneAmber
class node_manifest,node_results toneMint
class node_operator,node_aws toneIndigo
```

## Components

### AWS Range

- [Network](https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/network.tf): `terraform/network.tf`
- [IAM Resources](https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/iam.tf): `terraform/iam.tf`
- [S3 Resources](https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/s3.tf): `terraform/s3.tf`
- [EC2 Resources](https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/ec2.tf): `terraform/ec2.tf`
- [RDS Resources](https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/rds.tf): `terraform/rds.tf`
- [Budget Safety](https://github.com/trailsamuel/cloudsec-range/blob/main/terraform/safety.tf): `terraform/safety.tf`

### Scanner

- [Scan Runner](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/__main__.py): `scanner/__main__.py`
- [Check Registry](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/core.py): `scanner/core.py`
- [EC2 Checks](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_ec2.py): `scanner/checks_ec2.py`
- [IAM Checks](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_iam.py): `scanner/checks_iam.py`
- [S3 Checks](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_s3.py): `scanner/checks_s3.py`
- [CloudTrail RDS Checks](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/checks_cloudtrail.py): `scanner/checks_cloudtrail.py`

### Ground Truth

- [Expected Findings](https://github.com/trailsamuel/cloudsec-range/blob/main/findings/expected_findings.json): `findings/expected_findings.json`
- [Findings and Recall](https://github.com/trailsamuel/cloudsec-range/blob/main/scanner/__main__.py): `scanner/__main__.py`

### Other components

- **Operator**
- **AWS Account**

## Connections

- Operator → Network: deploys range (evidence: `README.md`)
- Operator → Scan Runner: runs scan (evidence: `README.md`)
- Network → AWS Account: provisions resources (evidence: `README.md`)
- IAM Resources → AWS Account: provisions resources (evidence: `README.md`)
- S3 Resources → AWS Account: provisions resources (evidence: `README.md`)
- EC2 Resources → AWS Account: provisions resources (evidence: `README.md`)
- RDS Resources → AWS Account: provisions resources (evidence: `README.md`)
- Budget Safety → AWS Account: provisions budget alarm (evidence: `README.md`)
- Scan Runner → Check Registry: gets registered checks (evidence: `scanner/__main__.py`)
- Scan Runner → EC2 Checks: dispatches checks (evidence: `scanner/__main__.py`)
- Scan Runner → IAM Checks: dispatches checks (evidence: `scanner/__main__.py`)
- Scan Runner → S3 Checks: dispatches checks (evidence: `scanner/__main__.py`)
- Scan Runner → CloudTrail RDS Checks: dispatches checks (evidence: `scanner/__main__.py`)
- EC2 Checks → Check Registry: uses context and findings (evidence: `scanner/checks_ec2.py`)
- IAM Checks → Check Registry: uses context and findings (evidence: `scanner/checks_iam.py`)
- S3 Checks → Check Registry: uses context and findings (evidence: `scanner/checks_s3.py`)
- CloudTrail RDS Checks → Check Registry: uses context and findings (evidence: `scanner/checks_cloudtrail.py`)
- EC2 Checks → AWS Account: audits EC2 and IAM (evidence: `scanner/checks_ec2.py`)
- IAM Checks → AWS Account: audits IAM (evidence: `scanner/checks_iam.py`)
- S3 Checks → AWS Account: audits S3 (evidence: `scanner/checks_s3.py`)
- CloudTrail RDS Checks → AWS Account: audits CloudTrail and RDS (evidence: `scanner/checks_cloudtrail.py`)
- Scan Runner → Expected Findings: scores against (evidence: `scanner/__main__.py`)
- Scan Runner → Findings and Recall: formats findings and recall (evidence: `scanner/__main__.py`)
- Findings and Recall → Operator: reports results (evidence: `README.md`)