# htrgouvea/spellbook architecture

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

- Interactive diagram: https://gitdiagram.com/htrgouvea/spellbook
- Repository: https://github.com/htrgouvea/spellbook

## Overview

##### Project type and purpose
- Spellbook is a command-line, flow-based micro-framework written in Perl for rapid development of reusable security tools.

##### File structure
- Top level:
- spellbook.pl – CLI entry point
- lib/Spellbook – core framework and modules, organized by category (Core, Recon, Exploit, Advisory, Android, Crypto, Cloud, Parser, Helper, Mail, Platform, Bruteforce)
- files/ and targets/ – static data (wordlists, target YAML)
- Dockerfile, cpanfile, GitHub workflows – build, test, CI/CD artifacts
- Key sub-directories:
- Core/Orchestrator.pm, Core/Module.pm, Core/UserAgent.pm – the FBP engine
- Category folders – each containing many modules that implement distinct steps in a tool pipeline
- Deployment/config:
- Docker container build (Dockerfile)
- CPAN dependencies (cpanfile)
- CI/CD pipelines (GitHub workflows)

##### Extract architecture insights from the README
- Emphasis on reusability: modules can be mixed/connected by the orchestrator without modification
- Supports plugin-style addition of new modules via lib/Spellbook/…

a. Main components
- CLI Interface (spellbook.pl)
- Core Framework
– Argument parser
– Orchestrator (Core::Orchestrator)
– Module loader (Core::Module)
– Shared utilities (Core::Helper, Core::UserAgent, Core::Resources, Core::Search)
- Plugin Modules
– Recon, Exploit, Advisory, Bruteforce, Android, Crypto, Cloud, Parser, Mail, Platform, Helper
- Configuration & Data
– targets/*.yml
– files/*.txt
- External Services & Tools
– HTTP APIs (Shodan, HaveIBeenPwned, cloud providers)
– Local/external scanners (nmap, masscan)
- CI/CD & Containerization (optional overlay)
– GitHub Actions workflows
– Docker build

b. Relationships & interactions
1. User → CLI Interface
2. CLI parses args → Orchestrator
3. Orchestrator reads config/data → constructs an FBP network of module nodes
4. Data/messages flow between modules in sequence (e.g., Recon → Parser → Exploit)
6. Final output streams back to the CLI (console, logs)

c. Architectural patterns & principles
- Plugin architecture – modules discovered/loaded dynamically by naming convention
- Layered design – CLI layer, core orchestration layer, module layer, external integration layer
- Single-responsibility modules – each module does one type of scan/attack/parsing

d. Key technologies/frameworks
- Perl (5.x)
- CPAN modules (HTTP::Tiny, JSON, YAML::XS, etc.)
- Flow-Based core (custom, in Core/)
- External command wrappers (nmap, masscan)
- Docker for containerized execution
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::cli
    end

    %% Core Framework
    subgraph "Core Framework"
        ArgParser["Argument Parser"]:::core
        Orchestrator["Core::Orchestrator"]:::core
        ModuleLoader["Core::Module Loader"]:::core
        subgraph "Utilities"
            HelperU["Core::Helper"]:::core
            UserAgent["Core::UserAgent"]:::core
            Resources["Core::Resources"]:::core
            Search["Core::Search"]:::core
            Credentials["Core::Credentials"]:::core
        end
    end

    %% Plugin Modules
    subgraph "Plugin Modules"
        Recon["Recon Modules"]:::plugin
        Exploit["Exploit Modules"]:::plugin
        Advisory["Advisory Modules"]:::plugin
        Bruteforce["Bruteforce Modules"]:::plugin
        Android["Android Modules"]:::plugin
        Crypto["Crypto Modules"]:::plugin
        Cloud["Cloud Modules"]:::plugin
        ParserMod["Parser Modules"]:::plugin
        MailMod["Mail Modules"]:::plugin
        PlatformMod["Platform Modules"]:::plugin
        HelperMod["Helper Modules"]:::plugin
    end

    %% Configuration & Data
    subgraph "Configuration & Data"
        Wordlists["Wordlists"]:::data
        Targets["Target Manifests"]:::data
    end

    %% External Services & Tools
    subgraph "External Services & Tools"
        HTTPAPIs["HTTP APIs"]:::external
        LocalTools["Local/External Scanners"]:::external
    end

    %% CI/CD & Containerization
    subgraph "CI/CD & Containerization"
        Docker["Dockerfile"]:::cicd
        Cpan["cpanfile"]:::cicd
        Workflows["GitHub Workflows"]:::cicd
    end

    %% Connections
    CLI -->|"invoke"| ArgParser
    ArgParser -->|"init network"| Orchestrator
    Orchestrator -->|"load modules"| ModuleLoader
    ModuleLoader --> Recon
    ModuleLoader --> Exploit
    ModuleLoader --> Advisory
    ModuleLoader --> Bruteforce
    ModuleLoader --> Android
    ModuleLoader --> Crypto
    ModuleLoader --> Cloud
    ModuleLoader --> ParserMod
    ModuleLoader --> MailMod
    ModuleLoader --> PlatformMod
    ModuleLoader --> HelperMod

    Recon -->|"messages"| ParserMod
    ParserMod -->|"messages"| Exploit
    Recon -->|uses| Wordlists
    Exploit -->|uses| Targets

    Recon -->|queries| HTTPAPIs
    Exploit -->|invokes| LocalTools
    Advisory -->|queries| HTTPAPIs

    Orchestrator -->|reads| Wordlists
    Orchestrator -->|reads| Targets

    Exploit -->|"final output"| CLI

    %% Click Events
    click CLI "https://github.com/htrgouvea/spellbook/blob/main/spellbook.pl"
    click Orchestrator "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/Orchestrator.pm"
    click ModuleLoader "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/Module.pm"
    click HelperU "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/Helper.pm"
    click UserAgent "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/UserAgent.pm"
    click Resources "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/Resources.pm"
    click Search "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/Search.pm"
    click Credentials "https://github.com/htrgouvea/spellbook/blob/main/lib/Spellbook/Core/Credentials.pm"
    click Recon "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Recon/"
    click Exploit "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Exploit/"
    click Advisory "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Advisory/"
    click Bruteforce "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Bruteforce/"
    click Android "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Android/"
    click Crypto "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Crypto/"
    click Cloud "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Cloud/"
    click ParserMod "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Parser/"
    click MailMod "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Mail/"
    click PlatformMod "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Platform/"
    click HelperMod "https://github.com/htrgouvea/spellbook/tree/main/lib/Spellbook/Helper/"
    click Wordlists "https://github.com/htrgouvea/spellbook/tree/main/files/"
    click Targets "https://github.com/htrgouvea/spellbook/tree/main/targets/"
    click Docker "https://github.com/htrgouvea/spellbook/tree/main/Dockerfile"
    click Cpan "https://github.com/htrgouvea/spellbook/tree/main/cpanfile"
    click Workflows "https://github.com/htrgouvea/spellbook/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#cceeff,stroke:#0000aa
    classDef plugin fill:#ccffcc,stroke:#008800
    classDef data fill:#dddddd,stroke:#999999
    classDef external fill:#ffdd99,stroke:#cc8800
    classDef cicd fill:#e0ccff,stroke:#6600cc
    classDef cli fill:#e8f4ff,stroke:#3399ff
```
