Module Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Module Engine is the core component of OWASP Nettacker responsible for orchestrating the execution of various security scanning tasks. It leverages a modular architecture where specific tasks—such as port scanning, vulnerability assessments, and credential brute-forcing—are implemented as independent modules. The engine manages the lifecycle of these modules, including template loading, target discovery, dependency resolution, and multi-threaded execution.
The engine serves as the bridge between the high-level scan configurations provided by the user (via CLI, API, or Web UI) and the low-level protocol libraries that perform the actual network requests. It ensures that scans are performed efficiently by utilizing multithreading and provides a standardized way to process and log results into the central database.
Sources: nettacker/core/module.py:20-30, README.md:25-40, AGENTS.md:7-12
Core Architecture and Lifecycle
The Module Engine operates by initializing a Module class for each task assigned to a target. The architecture is designed to handle service discovery dynamically, ensuring that modules only run against applicable services unless explicitly overridden.
Execution Workflow
- Initialization: The engine sets up module inputs, including targets and extra arguments.
- Template Loading: It uses the
TemplateLoaderto fetch the module's logic and payloads. - Service Discovery: Unless
skip_service_discoveryis enabled, the engine checks previousport_scanresults in the database to identify open ports and protocols relevant to the current module. - Loop Generation and Sorting: It expands module steps (e.g., iterating over ports/usernames) and sorts them based on dependencies.
- Threaded Execution: It imports the required protocol library and spawns threads to execute the scan logic.
The diagram above illustrates the logical flow from module initialization to execution.
Sources: nettacker/core/module.py:18-120, nettacker/core/lib/base.py:175-220
Module Components and Classes
The Module Class
The Module class is the primary orchestrator. It manages the internal state of a scan task for a specific target.
| Attribute | Description |
|---|---|
module_name | The unique identifier for the scan module (e.g., port_scan). |
module_inputs | Dictionary containing scan parameters, targets, and extra arguments. |
discovered_services | Map of protocols to ports identified during discovery. |
libraries | List of available protocol engines (e.g., http, ftp, ssh). |
Sources: nettacker/core/module.py:18-60
BaseEngine and BaseLibrary
Every protocol engine (like HttpEngine) inherits from BaseEngine, which provides utility methods for processing scan results.
run(): The main entry point for a protocol engine thread. It handles retries, executes the library method, and invokes condition processing.process_conditions(): Evaluates the response against success/failure criteria defined in the module template. It handles logging to both the terminal and the database.replace_dependent_values(): Handles dynamic value replacement for steps that depend on the results of previous "temp" events.
Sources: nettacker/core/lib/base.py:41-170
Dependency Management and Result Processing
The engine supports complex scan logic where steps can be dependent on previous results. This is handled via "temp events" which are stored in a temporary database table and retrieved by subsequent steps.
Dependency Types
- Independent Steps: Can run in any order (usually run first).
- Temp Dependencies: Steps that save results to
save_to_temp_events_onlyfor use by later steps in the same scan. - Normal Dependencies: Standard scan steps that depend on previously successful events.
This sequence shows how the engine handles data flow between execution threads and the database.
Sources: nettacker/core/module.py:100-115, nettacker/core/lib/base.py:100-150
Configuration and Hardware Usage
The engine's performance is highly configurable through the Config system. Users can define hardware usage profiles that dictate thread counts and timing.
| Configuration | Default | Description |
|---|---|---|
thread_per_host | 100 | Maximum concurrent threads for a single target. |
retries | 1 | Number of times to retry a failed request. |
time_sleep_between_requests | 0.0 | Delay (in seconds) between spawning new request threads. |
set_hardware_usage | maximum | Profile for resource allocation (low, normal, high, maximum). |
Sources: nettacker/config.py:170-200, nettacker/locale/en.yaml:120-130
Result Logging and Filtering
To prevent log bloating, the BaseEngine includes a filter_large_content method that truncates extremely large responses before they are displayed in the terminal. Sensitive information is also handled by remove_sensitive_header_keys before database submission, ensuring fields like authorization or cookie are not stored in plaintext logs.
Sources: nettacker/core/lib/base.py:53-65, nettacker/config.py:45-65
Conclusion
The Module Engine provides a robust framework for automated security testing by decoupling the scan logic (templates) from the protocol implementation (libraries). Its ability to dynamically discover services and handle inter-step dependencies allows for intelligent, context-aware scanning that goes beyond simple script execution. Ends.