# g0ldencybersec/cloudrecon architecture

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

- Interactive diagram: https://gitdiagram.com/g0ldencybersec/cloudrecon
- Repository: https://github.com/g0ldencybersec/cloudrecon

## Overview

##### Project Type and Purpose
- CloudRecon is a command-line suite of Go utilities (scrape, store, retr) designed for red-teamers and bug hunters. It scans IP addresses or CIDRs, performs TLS handshakes to retrieve SSL certificate metadata (CN, SAN, Org), optionally stores results in a local SQLite database, and enables keyword searches against the stored data.

##### File Structure Analysis
- Top-level files:
- main.go: CLI entry point, command dispatch (scrape, store, retr).
- scrape.go: Implements live scanning and JSON output.
- store.go: Similar to scrape, but writes metadata into a local DB.
- retr.go: Queries the local DB based on search flags.
- util.go: Common helpers (parsing IP lists, managing timeouts, goroutine pools).
- go.mod / go.sum: Go module definitions.
- README.md, LICENSE, .gitignore: Documentation & project metadata.

##### README Insights
- Three subcommands with distinct responsibilities.
- Dependencies: Go (with CGO enabled), SQLite3 (via cgo and gcc).
- Concurrency via configurable goroutine pools.
- Input sources: file or inline IP/CIDR lists.
- Output: JSON to stdout or queries to SQLite DB file.

a. Main Components
1. CLI Layer (main.go)
2. Subcommand Executors (Scrape, Store, Retr)
3. Input Parser (utils.go)
4. Certificate Fetcher (TLS handshake module)
5. Data Parser/Serializer (JSON marshaller, DB mapper)
6. Storage Layer (SQLite database via database/sql + sqlite3 driver)
7. Output Layer (stdout JSON or CLI table)

b. Relationships & Data Flow
- User issues “cloudrecon <cmd> -options → CLI Layer → invokes specific Executor.
- Executor loads Input Parser → generates work queue of IP:port tasks.
- Certificate Fetcher picks tasks concurrently → performs TLS handshake → returns raw cert data.
- Data Parser extracts CN, SAN, Org →
- Scrape: serializes to JSON → Output Layer → stdout / file
- Store: maps records to DB schema → Storage Layer (SQLite)
- Retr: Query Storage Layer → Data Parser formats results → Output Layer.

c. Architectural Patterns & Design Principles
- Modular subcommands following the “single responsibility” principle.
- Concurrent worker pool (goroutines + channels) for high-throughput I/O.
- Layered architecture: CLI → Executor → Fetcher → Parser → Storage/Output.
- Dependency injection for testability (passing interfaces for DB, network, parser).

d. Key Technologies & Frameworks
- Language: Go modules
- Concurrency: Goroutines & channels
- TLS: crypto/tls package
- Database: database/sql + mattn/go-sqlite3 (cgo)
- JSON: encoding/json

##### Detailed Architectural Capture
- Configurable parameters (goroutine count, timeout, ports) near the Worker Pool.
- External artifacts: IPv4 range file input, TLS endpoints on port 443 (or custom).
- Wherever possible, annotate the Go packages in use (e.g., “crypto/tls”, “database/sql”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level CLI
    main["CLI Dispatcher"]:::cli
    click main "https://github.com/g0ldencybersec/cloudrecon/blob/master/main.go"

    %% Subcommands grouping
    subgraph "Subcommands"
        scrape["Scrape Executor"]:::executor
        store["Store Executor"]:::executor
        retr["Retr Executor"]:::executor
    end
    click scrape "https://github.com/g0ldencybersec/cloudrecon/blob/master/scrape.go"
    click store "https://github.com/g0ldencybersec/cloudrecon/blob/master/store.go"
    click retr "https://github.com/g0ldencybersec/cloudrecon/blob/master/retr.go"

    main --> scrape
    main --> store
    main --> retr

    %% Scrape Pipeline
    subgraph "Scrape Pipeline"
        sp1["Input Parser & Goroutine Pool"]:::worker
        sp2["TLS Certificate Fetcher"]:::fetcher
        sp3["Metadata Extractor"]:::parser
        sp4["JSON Serializer"]:::serializer
        sp5["JSON Output (stdout)"]:::output
    end
    scrape --> sp1
    sp1 --> sp2
    sp2 --> sp3
    sp3 --> sp4
    sp4 --> sp5

    click sp1 "https://github.com/g0ldencybersec/cloudrecon/blob/master/utils.go"
    click sp2 "https://github.com/g0ldencybersec/cloudrecon/blob/master/scrape.go"
    click sp3 "https://github.com/g0ldencybersec/cloudrecon/blob/master/scrape.go"
    click sp4 "https://github.com/g0ldencybersec/cloudrecon/blob/master/scrape.go"
    click sp5 "https://github.com/g0ldencybersec/cloudrecon/blob/master/scrape.go"

    %% Store Pipeline
    subgraph "Store Pipeline"
        st1["Input Parser & Goroutine Pool"]:::worker
        st2["TLS Certificate Fetcher"]:::fetcher
        st3["Metadata Extractor"]:::parser
        st4["SQLite Storage Layer"]:::datastore
    end
    store --> st1
    st1 --> st2
    st2 --> st3
    st3 --> st4

    click st1 "https://github.com/g0ldencybersec/cloudrecon/blob/master/utils.go"
    click st2 "https://github.com/g0ldencybersec/cloudrecon/blob/master/store.go"
    click st3 "https://github.com/g0ldencybersec/cloudrecon/blob/master/store.go"
    click st4 "https://github.com/g0ldencybersec/cloudrecon/blob/master/store.go"

    %% Retrieval Pipeline
    subgraph "Retrieval Pipeline"
        rt1["SQLite Query Layer"]:::datastore
        rt2["Metadata Formatter"]:::parser
        rt3["CLI Output Formatter"]:::output
    end
    retr --> rt1
    rt1 --> rt2
    rt2 --> rt3

    click rt1 "https://github.com/g0ldencybersec/cloudrecon/blob/master/retr.go"
    click rt2 "https://github.com/g0ldencybersec/cloudrecon/blob/master/retr.go"
    click rt3 "https://github.com/g0ldencybersec/cloudrecon/blob/master/retr.go"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef executor fill:#87CEFA,stroke:#000,stroke-width:1px;
    classDef worker fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef fetcher fill:#FFDAB9,stroke:#000,stroke-width:1px;
    classDef parser fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef serializer fill:#E6E6FA,stroke:#000,stroke-width:1px;
    classDef datastore fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef output fill:#90EE90,stroke:#000,stroke-width:1px;
```
