Framework Core Engine
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Framework Core Engine of OWASP Nettacker is a modular, multithreaded system designed for automated information gathering and vulnerability scanning. It serves as the orchestrator for various security modules, managing the execution of tasks such as port scanning, service detection, and credential brute-forcing across diverse target types including IP addresses, CIDR blocks, and domain names.
The engine provides a unified interface for the project's three primary interaction layers: the Command Line Interface (CLI), the REST API, and the Web UI. By leveraging a modular architecture, the core engine allows developers to implement specific security tasks as independent modules that are dynamically loaded and executed during a scan session.
Sources: README.md:14-25, AGENTS.md:7-12
Core Architecture and Data Flow
The core engine is built on a base logic that handles module execution, result processing, and database persistence. It utilizes a multithreaded approach to perform parallel scans across multiple hosts and protocols.
Engine Execution Flow
The engine coordinates the lifecycle of a scan, from target ingestion to final report generation. It manages hardware resource allocation based on user configuration (low, normal, high, maximum) and handles the distribution of tasks across threads.
The diagram above illustrates the high-level workflow of the Nettacker engine during a standard scanning operation.
Sources: nettacker/core/lib/base.py:214-260, README.md:27-33, nettacker/locale/en.yaml:94-100
Base Engine Logic
The BaseEngine class provides essential utilities for all scanning modules, including methods for handling large content and managing dependent events.
- Content Filtering: The
filter_large_contentmethod ensures that excessively large responses are truncated for report readability. - Dependent Events: The engine can retrieve results from previous steps in a scan (dependent events) from the database to use as inputs for subsequent steps.
- Condition Processing: The
process_conditionsmethod evaluates the success of a module's execution against defined criteria and manages the logging of these events.
Sources: nettacker/core/lib/base.py:44-59, nettacker/core/lib/base.py:61-180
Configuration Management
The engine relies on a centralized configuration system defined in nettacker/config.py. This includes default settings for the API, database connectivity, and runtime paths.
Key Configuration Classes
| Class | Purpose | Key Attributes |
|---|---|---|
ApiConfig | API Server defaults | api_hostname, api_port, api_access_key |
DbConfig | Database connection | engine (sqlite/mysql/postgres), name, host |
PathConfig | Framework directories | modules_dir, results_dir, payloads_dir |
DefaultSettings | Scan behavior | thread_per_host, timeout, retries, language |
Sources: nettacker/config.py:77-178
Sensitive Data Handling
The engine maintains a sensitive_headers list to ensure that authentication tokens and cookies are redacted or handled carefully during logging and database submission to prevent sensitive data leakage.
Sources: nettacker/config.py:56-74, nettacker/core/lib/base.py:87-90
Module Integration and Execution
Modules interact with the core engine through the BaseLibrary and BaseEngine abstractions. The engine dynamically calls library methods based on the scan configuration.
Module Lifecycle
This sequence shows how the engine coordinates with specific module libraries and the database to execute multi-step scanning logic.
Sources: nettacker/core/lib/base.py:192-230, nettacker/core/lib/base.py:232-260
Persistence and Data Storage
Nettacker uses a relational database to store scan metadata, logs, and results. It supports SQLite by default but is compatible with MySQL and PostgreSQL.
- Database Schema: Managed via SQLAlchemy or APSW (for SQLite performance).
- Data Integrity: The engine handles retries for database locks (default 100 retries) and manages the removal of old records to maintain performance.
- Drift Detection: By storing historical scan data, the core engine facilitates the comparison of results to detect new hosts, open ports, or infrastructure changes.
Sources: nettacker/config.py:101-127, nettacker/locale/en.yaml:126-130, README.md:30-32
API and Web Interface
The framework includes a built-in REST API that allows for programmatic control of the core engine. The API files are located in nettacker/api/ and manage core functions such as starting scans and interacting with the database.
| Component | File | Description |
|---|---|---|
| API Entry Point | engine.py | Main API functions and routing. |
| Core Functions | api_core.py | Supporting logic for API operations. |
| Scan Manager | start_scan.py | Logic specifically for triggering new scan sessions via API. |
Sources: nettacker/api/readme.md:1-12
Summary
The Framework Core Engine is the central nervous system of OWASP Nettacker, providing the necessary abstractions for modular scanning, multithreaded execution, and robust data persistence. Its architecture allows for flexible deployment across CLI and web environments while maintaining strict control over resource usage and sensitive data handling.