How htrgouvea/spellbook works
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