# musana/cf-hero architecture

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

- Interactive diagram: https://gitdiagram.com/musana/cf-hero
- Repository: https://github.com/musana/cf-hero

## Overview

##### Main Components
- CLI/Entry Point: Represented by the main.go file in the cmd/cf-hero directory. This is where the application starts, processes flags/parameters and orchestrates the scanning.
- Internal Modules:
- Configuration Module (internal/config): Responsible for reading configuration data (e.g., API keys from cf-hero.yaml).
- DNS Reconnaissance Module (internal/dns): Implements functionality to query and process DNS records (A, TXT, etc.).
- HTTP Client Module (internal/http): Manages the HTTP requests for verifying endpoints and validating responses.
- Scanning Module (internal/scanner): The core engine that leverages DNS queries and HTTP validations. It likely integrates worker routines for concurrent processing.
- Utility Functions (internal/utils): Provides helper functions or common operations used across the tool.
- Domain Models: Located in pkg/models. These define the data structures used throughout the modules (for example, representing DNS records, API responses, or target domain information).
- External OSINT/Intelligence Sources: Although not a directory in the codebase, your design should include external integrations with Censys, Shodan, and SecurityTrails as separate components. These represent external services that the scanning process leverages (as indicated by command parameters and the README).

##### Relationships and Data Flows
- Input Layer:
- Command-line input is accepted through flags and piped data (for example, lists of domains).
- The CLI component then passes this input to the Scanner module.
- Processing Pipeline:
- The Scanner module uses the DNS module to perform initial DNS reconnaissance.
- It calls the HTTP Client module to validate findings by making HTTP requests to the discovered IP addresses.
- It may also invoke routines to interact with external intelligence sources (Censys, Shodan, SecurityTrails) to enrich the gathered data.
- Configuration module is used throughout the process to load necessary API keys and parameters.
- Utility functions support data transformations and helper operations.
- Output:
- Processed results (domains behind Cloudflare or not, real IP addresses) are output to the terminal.
- There is also support for additional output based on flags (like printing just CF or non-CF domains).

##### Architectural Patterns and Design Principles
- Modular Design: The separation into distinct packages (cmd, internal, pkg) follows a clear modular design with separation of concerns.
- Concurrency: The tool supports concurrent scanning with a configurable worker count, pointing to a design that accommodates parallel processing.
- Extensibility: The use of external APIs and clear modular boundaries hints at an extensible design. Future integration points (or enhancements such as JA3 randomization) can be added with minimal impact on the overall architecture.
- Configuration Management: The use of a configuration file (cf-hero.yaml) placed in the user’s config directory abstracts away runtime settings.

- “DNS Reconnaissance” (internal/dns)
- “HTTP Client” (internal/http)
- “Configuration” (internal/config)
- “Utilities” (internal/utils) which support both the DNS and HTTP modules.
- “Models” (pkg/models) can be shown as a shared data schema.
- On the side, illustrate the external components (Censys, Shodan, SecurityTrails) linked to the Scanner (and possibly indirectly via the Config module for API key management).
- Flow of validated data (e.g., “validated IP responses”) returning to the Scanner and then being rendered to output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level CLI Component
    CLI["CF-Hero CLI"]:::cli

    %% Scanner Module
    Scanner["Scanner Module"]:::module

    %% Internal Modules
    DNS["DNS Reconnaissance"]:::module
    HTTP["HTTP Client"]:::module
    Config["Configuration"]:::module
    Utils["Utilities"]:::module
    Models["Domain Models"]:::module

    %% External OSINT Services
    Censys["Censys OSINT API"]:::external
    Shodan["Shodan OSINT API"]:::external
    SecurityTrails["SecurityTrails OSINT API"]:::external

    %% Define flow from CLI to Scanner
    CLI -->|"processes flags"| Scanner

    %% Scanner uses internal modules for processing
    Scanner -->|"performs DNS query"| DNS
    Scanner -->|"makes HTTP request"| HTTP
    Scanner -->|"loads configuration"| Config
    Scanner -->|"calls helper functions"| Utils
    Scanner -->|"uses data models"| Models

    %% HTTP Client returns validated response to Scanner
    HTTP -->|"returns response"| Scanner

    %% Scanner interacts with external OSINT APIs
    Scanner -->|"queries data"| Censys
    Scanner -->|"queries data"| Shodan
    Scanner -->|"queries data"| SecurityTrails

    %% Define styles for the nodes with color     
    classDef cli fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef module fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef external fill:#f8bbd0,stroke:#c2185b,stroke-width:2px;

    %% Click Events for Component Mapping
    click CLI "https://github.com/musana/cf-hero/blob/main/cmd/cf-hero/main.go"
    click Config "https://github.com/musana/cf-hero/blob/main/internal/config/config.go"
    click DNS "https://github.com/musana/cf-hero/blob/main/internal/dns/dns.go"
    click HTTP "https://github.com/musana/cf-hero/blob/main/internal/http/client.go"
    click Scanner "https://github.com/musana/cf-hero/blob/main/internal/scanner/scanner.go"
    click Utils "https://github.com/musana/cf-hero/blob/main/internal/utils/utils.go"
    click Models "https://github.com/musana/cf-hero/blob/main/pkg/models/models.go"
```
