# fsociety-team/fsociety architecture

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

- Interactive diagram: https://gitdiagram.com/fsociety-team/fsociety
- Repository: https://github.com/fsociety-team/fsociety

## Overview

##### File structure
- Top‐level package: `fsociety/`
- `__main__.py` and `console.py` implement the CLI front-end.
- `core/` contains the framework’s engine (config loader, host list, menu system, utility functions, package registry).
- Subpackages at the same level as `core/` are feature categories (plugins):
– `information_gathering/`
– `networking/`
– `obfuscation/`
– `passwords/`
– `web_apps/`
- Each feature directory has a `cli.py` (interface), plus one or more tool wrappers (e.g., `nmap.py`, `sqlmap.py`).
- Deployment and CI/CD files:
- `Dockerfile` for container image
- GitHub workflows under `.github/workflows/`
- `setup.py`, `pyproject.toml` for packaging

##### README for additional insights
- Confirms purpose: “A Modular Penetration Testing Framework”
- Usage is purely via CLI flags (`-i`, `-s`, etc.)

##### Main components of the system
a. User CLI (shell)
b. fsociety CLI entrypoint (`__main__.py` → `console.py`)
c. Core framework engine (`core/`):
- Config manager
- Menu & host registry
- Plugin registry & loader
- Utility functions
d. Plugin modules (five categories):
- Information Gathering
- Networking
- Obfuscation
- Password Attacks
- Web App Testing
e. External pentest tools (invoked by plugins)
f. Output & logs (console, optional file)
g. Deployment environments:
- Native Python runtime
- Docker container

##### Relationships and interactions
- CLI Entrypoint calls Console → forwards to Core Engine
- Core Engine loads selected plugin from Plugin Registry
- Plugin’s `cli.py` constructs the command for its external tool
- External tool executes (OS subprocess) → returns results
- Core Engine/Plugin formats results → console output
- Configuration data flows from `core/config.py` → plugins

##### Architectural patterns and design principles
- Plugin architecture: decoupled modules discovered/loaded at runtime
- Single-entrypoint CLI with subcommands
- Separation of concerns: core engine vs. feature plugins vs. external tools
- Extensibility: new plugin = new subpackage with `cli.py` and tool wrapper
- Containerization: Dockerfile encapsulates runtime dependencies

##### Diagramming recommendations
- User Shell
- fsociety CLI Entrypoint
- Core Framework
- Plugin Categories (grouped)
- External Tools
- Runtime Environments
- CLI → Core → Plugins → External Tools → Console
- Config flow from Core to Plugins
- Blue for fsociety internal components
- Green for plugins
- Orange for external tools
- Gray for deployment environments
- Rounded rectangles for processes (Core, Plugins)
- Clouds for external tools or services

##### Essential elements to capture
- Plugin discovery/registry
- CLI dispatch mechanism
- Category separation (information_gathering, networking, etc.)
- Subprocess boundaries (when fsociety calls `nmap`, `sqlmap`, etc.)
- Dual deployment (host vs. Docker container)
- Clear labels, legends, and a directional‐flow key

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and CLI
    UserShell["User Shell"]:::external
    Entrypoint["fsociety CLI Entrypoint"]:::internal
    Console["Console Front-End"]:::internal

    %% Core Framework
    subgraph "Core Framework"
        Config["Configuration Manager"]:::internal
        Hosts["Host List & Registry"]:::internal
        Menu["Menu System"]:::internal
        Repo["Plugin/Package Registry"]:::internal
        Usernames["Usernames Module"]:::internal
        Utilities["Utility Functions"]:::internal
    end

    %% Plugins
    subgraph "Information Gathering Plugins" 
        IG_CLI["IG CLI Interface"]:::plugin
        GitgraberWrapper["gitgraber Wrapper"]:::plugin
        HydrareconWrapper["hydracrecon Wrapper"]:::plugin
        S3scannerWrapper["s3scanner Wrapper"]:::plugin
        SherlockWrapper["sherlock Wrapper"]:::plugin
        SqlmapWrapper["sqlmap Wrapper"]:::plugin
        StrikerWrapper["striker Wrapper"]:::plugin
        Sublist3rWrapper["sublist3r Wrapper"]:::plugin
    end

    subgraph "Networking Plugins"
        Net_CLI["Networking CLI Interface"]:::plugin
        NmapWrapper["nmap Wrapper"]:::plugin
        BettercapWrapper["bettercap Wrapper"]:::plugin
    end

    subgraph "Obfuscation Plugins"
        Obf_CLI["Obfuscation CLI Interface"]:::plugin
        CuteitWrapper["cuteit Wrapper"]:::plugin
    end

    subgraph "Password Attacks Plugins"
        PW_CLI["Passwords CLI Interface"]:::plugin
        ChangemeWrapper["changeme Wrapper"]:::plugin
        CuppWrapper["cupp Wrapper"]:::plugin
        Cr3dov3rWrapper["cr3dov3r Wrapper"]:::plugin
        HashBusterWrapper["hash_buster Wrapper"]:::plugin
        TraitorWrapper["traitor Wrapper"]:::plugin
    end

    subgraph "Web App Testing Plugins"
        Web_CLI["Web Apps CLI Interface"]:::plugin
        PhotonWrapper["photon Wrapper"]:::plugin
        XSStrikeWrapper["xsstrike Wrapper"]:::plugin
    end

    %% External Tools
    subgraph "External Tools"
        ET_Nmap["nmap"]:::external
        ET_Gitgraber["gitgraber"]:::external
        ET_Hydrarecon["hydracrecon"]:::external
        ET_S3scanner["s3scanner"]:::external
        ET_Sherlock["sherlock"]:::external
        ET_Sqlmap["sqlmap"]:::external
        ET_Striker["striker"]:::external
        ET_Sublist3r["sublist3r"]:::external
        ET_Bettercap["bettercap"]:::external
        ET_Cuteit["cuteit"]:::external
        ET_Changeme["changeme"]:::external
        ET_Cupp["cupp"]:::external
        ET_Cr3dov3r["cr3dov3r"]:::external
        ET_HashBuster["hash_buster"]:::external
        ET_Traitor["traitor"]:::external
        ET_Photon["photon"]:::external
        ET_XSStrike["xsstrike"]:::external
    end

    %% Deployment Environments
    subgraph "Deployment Environments"
        Native["Native Python Runtime"]:::env
        Docker["Docker Container"]:::env
    end

    %% Flow
    UserShell -->|"fsociety"<| Entrypoint
    Entrypoint -->|calls| Console
    Console -->|loads| Repo
    Console -->|forwards to| Config
    Console -->|forwards to| Hosts
    Console -->|forwards to| Menu
    Console -->|forwards to| Utilities
    Console -->|forwards to| Usernames

    Repo -->|discovers| IG_CLI
    Repo -->|discovers| Net_CLI
    Repo -->|discovers| Obf_CLI
    Repo -->|discovers| PW_CLI
    Repo -->|discovers| Web_CLI

    IG_CLI -->|"construct command"| GitgraberWrapper
    IG_CLI -->|"construct command"| HydrareconWrapper
    IG_CLI -->|"construct command"| S3scannerWrapper
    IG_CLI -->|"construct command"| SherlockWrapper
    IG_CLI -->|"construct command"| SqlmapWrapper
    IG_CLI -->|"construct command"| StrikerWrapper
    IG_CLI -->|"construct command"| Sublist3rWrapper

    Net_CLI -->|"construct command"| NmapWrapper
    Net_CLI -->|"construct command"| BettercapWrapper

    Obf_CLI -->|"construct command"| CuteitWrapper

    PW_CLI -->|"construct command"| ChangemeWrapper
    PW_CLI -->|"construct command"| CuppWrapper
    PW_CLI -->|"construct command"| Cr3dov3rWrapper
    PW_CLI -->|"construct command"| HashBusterWrapper
    PW_CLI -->|"construct command"| TraitorWrapper

    Web_CLI -->|"construct command"| PhotonWrapper
    Web_CLI -->|"construct command"| XSStrikeWrapper

    GitgraberWrapper -->|subprocess| ET_Gitgraber
    HydrareconWrapper -->|subprocess| ET_Hydrarecon
    S3scannerWrapper -->|subprocess| ET_S3scanner
    SherlockWrapper -->|subprocess| ET_Sherlock
    SqlmapWrapper -->|subprocess| ET_Sqlmap
    StrikerWrapper -->|subprocess| ET_Striker
    Sublist3rWrapper -->|subprocess| ET_Sublist3r

    NmapWrapper -->|subprocess| ET_Nmap
    BettercapWrapper -->|subprocess| ET_Bettercap

    CuteitWrapper -->|subprocess| ET_Cuteit

    ChangemeWrapper -->|subprocess| ET_Changeme
    CuppWrapper -->|subprocess| ET_Cupp
    Cr3dov3rWrapper -->|subprocess| ET_Cr3dov3r
    HashBusterWrapper -->|subprocess| ET_HashBuster
    TraitorWrapper -->|subprocess| ET_Traitor

    PhotonWrapper -->|subprocess| ET_Photon
    XSStrikeWrapper -->|subprocess| ET_XSStrike

    %% Config flow
    Config -->|provides config| GitgraberWrapper
    Config -->|provides config| NmapWrapper
    Config -->|provides config| CuteitWrapper
    Config -->|provides config| ChangemeWrapper
    Config -->|provides config| PhotonWrapper

    %% Deployment links
    Entrypoint -->|runs on| Native
    Entrypoint -->|runs in| Docker

    %% Click events
    click Entrypoint "https://github.com/fsociety-team/fsociety/blob/main/fsociety/__main__.py"
    click Console "https://github.com/fsociety-team/fsociety/blob/main/fsociety/console.py"
    click Config "https://github.com/fsociety-team/fsociety/blob/main/fsociety/core/config.py"
    click Hosts "https://github.com/fsociety-team/fsociety/blob/main/fsociety/core/hosts.py"
    click Menu "https://github.com/fsociety-team/fsociety/blob/main/fsociety/core/menu.py"
    click Repo "https://github.com/fsociety-team/fsociety/blob/main/fsociety/core/repo.py"
    click Usernames "https://github.com/fsociety-team/fsociety/blob/main/fsociety/core/usernames.py"
    click Utilities "https://github.com/fsociety-team/fsociety/blob/main/fsociety/core/utilities.py"
    click IG_CLI "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/cli.py"
    click GitgraberWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/gitgraber.py"
    click HydrareconWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/hydrarecon.py"
    click S3scannerWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/s3scanner.py"
    click SherlockWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/sherlock.py"
    click SqlmapWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/sqlmap.py"
    click StrikerWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/striker.py"
    click Sublist3rWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/information_gathering/sublist3r.py"
    click Net_CLI "https://github.com/fsociety-team/fsociety/blob/main/fsociety/networking/cli.py"
    click NmapWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/networking/nmap.py"
    click BettercapWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/networking/bettercap.py"
    click Obf_CLI "https://github.com/fsociety-team/fsociety/blob/main/fsociety/obfuscation/cli.py"
    click CuteitWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/obfuscation/cuteit.py"
    click PW_CLI "https://github.com/fsociety-team/fsociety/blob/main/fsociety/passwords/cli.py"
    click ChangemeWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/passwords/changeme.py"
    click CuppWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/passwords/cupp.py"
    click Cr3dov3rWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/passwords/cr3dov3r.py"
    click HashBusterWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/passwords/hash_buster.py"
    click TraitorWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/passwords/traitor.py"
    click Web_CLI "https://github.com/fsociety-team/fsociety/blob/main/fsociety/web_apps/cli.py"
    click PhotonWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/web_apps/photon.py"
    click XSStrikeWrapper "https://github.com/fsociety-team/fsociety/blob/main/fsociety/web_apps/xsstrike.py"
    click Docker "https://github.com/fsociety-team/fsociety/tree/main/Dockerfile"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef plugin fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fce5cd,stroke:#333,stroke-width:1px
    classDef env fill:#e2e3e5,stroke:#333,stroke-width:1px
```
