How fsociety-team/fsociety works
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