How s4dhulabs/vimana-framework works
Project Type and Purpose
• Vimana is a Python-based, command-line, modular security framework.
• It provides a core engine (CLI + orchestration) that dynamically loads and runs “siddhis” (plugins) to audit, fuzz, crawl, track, parse, or exploit Python web applications.
• Plugins live under the “siddhis” directory; resources (payloads, patterns, keywords) under “res”; core logic under “core”; settings under “settings”; and helper scripts under “scripts” and “helpers.”
File-Structure Analysis
• Top-level
• vimana.py – CLI entry point
• core/ – framework engine, argument parser, plugin loader, database operations
• siddhis/ – plugins (each subfolder is a siddhi with code + YAML metadata)
• res/ – static payloads, patterns, banners, session management code
• settings/ – shared settings and YAML config for core/plugins
• helpers/ and scripts/ – utility functions and install/build scripts
• core/_dbops_/vmnf.db – SQLite persistence for plugins, sessions, scans
• Architectural patterns
• Plugin registry/factory (core/vmnf_engine + core/vmnf_navi_*)
• Persistence layer (core/_dbops_)
• CLI Controller (vimana.py + core/vmnf_arg_parser.py)
• Modular resource loader (res/)
README Insights
• Confirms CLI commands (load, run, info, guide)
• Describes plugin categories (fuzzer, exploit, crawler, etc.)
• Emphasizes dynamic plugin registration via vimana load --plugins
• Shows use of a local SQLite DB for storing plugin metadata and sessions
Components
a. Main Components
1. CLI Layer: vimana.py
2. Argument Parser: core/vmnf_arg_parser.py
3. Core Engine & Orchestrator: core/vmnf_engine.py (+ navigator modules)
4. Plugin Manager / Loader: core/vmnf_shared_args.py + core/vmnf_navicontrols.py
5. Persistence Layer: core/_dbops_ (database.py, models/, vmnf.db)
6. Settings Loader: core/load_settings.py + settings/*.yaml
7. Resource Loader: res/ (payloads, patterns, banners)
8. Helpers & Utilities: helpers/, core/vmnf_utils.py, res/print_it.py
9. Siddhis (Plugin Modules): each siddhi under siddhis/
10. External Interfaces: network (HTTP clients within plugins), filesystem (reading configs)
b. Relationships & Data Flow
• User invokes CLI → CLI Layer
• CLI Layer → Argument Parser (parses flags, commands)
• Parsed input → Core Engine
• Core Engine:
– Loads global settings via Settings Loader
– Connects to SQLite via Persistence Layer
– If load --plugins: reads siddhis/ directory, parses each plugin’s YAML, stores metadata in DB
– If run --plugin X: fetch plugin metadata from DB, instantiate plugin module
– Supplies plugin with resources (payloads, patterns) via Resource Loader
– Orchestrates plugin execution (possibly multi-threaded via core/vmnf_thread_handler.py)
– Records sessions, scans, exceptions back to DB
• Results → Helpers/print_it → STDOUT or optional interactive session
c. Architectural Patterns & Principles
• Plugin Architecture (factory + registry)
• Layered Design: CLI → Parser → Engine → Plugin → Persistence
• Separation of Concerns: resources decoupled from code; settings in YAML
• Extensibility: new siddhis drop-in modules auto-registered
d. Key Technologies & Libraries
• Python 3.9+
• SQLite (via core/_dbops_)
• YAML for configs (PyYAML)
• Standard libraries: argparse, threading, sqlite3, importlib
• Scrapy for certain crawler-type plugins
• Dockerfile for containerization
Essential Details
• That adding a new siddhi simply extends the plugin cluster without touching core
• Multi-threading within the engine (thread handler) if needed
• Avoid over-splitting: group related navigator modules under “Engine”