# alphasoc/flightsim architecture

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

- Interactive diagram: https://gitdiagram.com/alphasoc/flightsim
- Repository: https://github.com/alphasoc/flightsim

## Overview

##### Project Type and Purpose
- This is a command-line utility written in Go that simulates malicious network traffic. Its purpose is to generate realistic attack traffic (DNS tunneling, DGA, C2 communications, SSH transfers, and more) so security teams can evaluate how well they detect or block these network events.
- The README clearly describes it as a tool for simulating various types of “suspicious” or malicious network activities.

##### Analyzing the File Structure
- The project is organized under a top-level “v2” directory that contains the main application code.
- The “cmd” directory contains subcommands (“get” and “run”) that serve as entry points for different functionalities.
- The “simulator” directory houses the individual simulation modules, each representing different network traffic patterns (e.g., dga.go, irc.go, miner.go, tunnel-dns.go, etc.).
- There’s a “utils” directory with helper functions for networking, randomization, and marshaling, which likely provide shared logic across modules.
- Other parts like “wisdom” seem to encapsulate output logic or additional processing.
- Presence of configuration files like .goreleaser.yml and go module files indicate standard Go project layout.

##### Key Components
a. CLI/Command Interface:
- "cmd" package with subcommands “get” and “run” that accept user input and flags.
b. Main Orchestrator:
- The main entry point (v2/main.go) that bootstraps the application and routes command-line arguments to the proper module.
c. Simulation Modules:
- Each module inside “simulator” (for example: dga, c2, ssh-exfil, ssh-transfer, tunnel-dns, etc.) should be depicted as separate components or nodes. You might want to group them under a larger "Simulator" block to show their unified purpose.
d. Utility/Shared Libraries:
- A component for “utils” that provides shared functionality (network connection management, randomness, marshaling).
e. External Interactions:
- Interactions with external services/APIs such as the AlphaSOC API for fetching destination addresses (as used in the “get” command and possibly within simulation modules).
- For simulations that mimic network protocols, indicate connections to external servers (like IRC, SSH servers, SMTP servers, etc.), though these would be simulated and not actual long-lived services.

##### Architectural Patterns or Design Principles
- The design follows a modular, command-based architecture where individual functionalities (different types of network traffic simulation) are encapsulated as modules.
- Separation of concerns: CLI commands are separated from simulation logic and shared utilities.
- Extensibility: new simulation modules can be added without affecting the overall architecture (a potential plug-in style among the simulator modules).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Commands"
        CMD_GET["get Command"]:::cli
        CMD_RUN["run Command"]:::cli
    end

    MO["Main Orchestrator"]:::orchestrator

    subgraph "Simulation Modules"
        DGA["DGA Simulator"]:::simulator
        IRC["IRC Simulator"]:::simulator
        SSH_EXFIL["SSH-Exfil Simulator"]:::simulator
        SSH_TRANSFER["SSH-Transfer Simulator"]:::simulator
        TUNNEL_DNS["Tunnel-DNS Simulator"]:::simulator
    end

    SU["Shared Utils"]:::utility
    WL["Output Logic (Wisdom)"]:::wisdom
    EX["AlphaSOC API"]:::external

    %% Connections
    CMD_RUN -->|"triggers"| MO
    CMD_GET -->|"triggers"| MO
    CMD_GET -->|"fetches"| EX

    MO -->|"activates"| DGA
    MO -->|"activates"| IRC
    MO -->|"activates"| SSH_EXFIL
    MO -->|"activates"| SSH_TRANSFER
    MO -->|"activates"| TUNNEL_DNS

    DGA -->|"uses"| SU
    IRC -->|"uses"| SU
    SSH_EXFIL -->|"uses"| SU
    SSH_TRANSFER -->|"uses"| SU
    TUNNEL_DNS -->|"uses"| SU

    DGA -->|"logs"| WL
    IRC -->|"logs"| WL
    SSH_EXFIL -->|"logs"| WL
    SSH_TRANSFER -->|"logs"| WL
    TUNNEL_DNS -->|"logs"| WL

    DGA -->|"calls"| EX
    IRC -->|"calls"| EX
    SSH_EXFIL -->|"calls"| EX
    SSH_TRANSFER -->|"calls"| EX
    TUNNEL_DNS -->|"calls"| EX

    %% Click Events
    click CMD_GET "https://github.com/alphasoc/flightsim/tree/master/v2/cmd/get"
    click CMD_RUN "https://github.com/alphasoc/flightsim/tree/master/v2/cmd/run"
    click MO "https://github.com/alphasoc/flightsim/blob/master/v2/main.go"
    click DGA "https://github.com/alphasoc/flightsim/blob/master/v2/simulator/dga.go"
    click IRC "https://github.com/alphasoc/flightsim/blob/master/v2/simulator/irc.go"
    click SSH_EXFIL "https://github.com/alphasoc/flightsim/blob/master/v2/simulator/ssh-exfil.go"
    click SSH_TRANSFER "https://github.com/alphasoc/flightsim/blob/master/v2/simulator/ssh-transfer.go"
    click TUNNEL_DNS "https://github.com/alphasoc/flightsim/blob/master/v2/simulator/tunnel-dns.go"
    click SU "https://github.com/alphasoc/flightsim/tree/master/v2/utils"
    click WL "https://github.com/alphasoc/flightsim/tree/master/v2/wisdom"

    %% Styles
    classDef cli fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef simulator fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef utility fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef wisdom fill:#f8961e,stroke:#333,stroke-width:2px;
    classDef external fill:#a8dadc,stroke:#333,stroke-dasharray: 5,5,stroke-width:2px;
```
