Argument Parsing System

Relevant source files

The following files were used as context for generating this wiki page:

• nettacker/core/arg_parser.py
• nettacker/config.py
• nettacker/locale/en.yaml
• AGENTS.md
• pyproject.toml
• nettacker/core/readme.md

Introduction

The Argument Parsing System in OWASP Nettacker is a centralized component responsible for handling user input from both the Command Line Interface (CLI) and internal API requests. It extends the standard Python argparse.ArgumentParser to provide a robust mechanism for configuring scan engines, defining targets, selecting modules, and managing API server settings. This system serves as the primary entry point for orchestrating the framework's behavior based on user-provided flags or programmatic configurations.

The system is designed to be highly modular, loading available scan modules, profiles, languages, and graph engines dynamically from the filesystem before parsing user arguments. This ensures that the help menu and validation logic are always in sync with the current state of the repository.

Sources: nettacker/core/arg_parser.py:31-45, AGENTS.md:1-15

Architecture and Components

The core of the system is the ArgParser class, which inherits from argparse.ArgumentParser. It integrates closely with the Config module to set default values and the locale system for multi-language support.

Component Interaction

The following diagram illustrates how the ArgParser interacts with other components to prepare for scanning:

Initialization and Resource Loading

During instantiation, the parser performs several static resource discovery tasks:

• Module Loading: Scans the modules/ directory for .yaml files, extracting metadata like severity and description.
• Profile Generation: Maps modules to specific "profiles" (e.g., vuln, http) based on tags found in their YAML configuration.
• Language Discovery: Lists available translation files in the locale/ directory.
• Graph Engine Discovery: Identifies available visualization engines within the lib/graph/ directory.

Sources: nettacker/core/arg_parser.py:47-116, nettacker/config.py:110-124

Argument Groups

Arguments are organized into logical groups to improve usability and clarity in the help menu.

Engine Options

These options control the global behavior of the Nettacker engine, including output formats, verbosity, and localization.

Flag	Destination	Default Value	Description
-L, --language	language	en	Selects the system language.
-v, --verbose	verbose_mode	False	Enables verbose logging (levels 0-5).
-o, --output	report_path_filename	Dynamic (HTML)	Path to save scan results.
--graph	graph_name	d3_tree_v2_graph	Selects a visualization engine.
-V, --version	show_version	False	Displays current version and code name.

Sources: nettacker/core/arg_parser.py:121-163, nettacker/config.py:133-145

Target and Method Options

These define the scope of the scan and the specific modules to be executed.

Flag	Destination	Description
-i, --targets	targets	Comma-separated list of targets (IP, CIDR, Domain).
-l, --targets-list	targets_list	Read targets from a text file.
-m, --modules	selected_modules	Choose specific scan modules to run.
--profile	profiles	Run a set of modules associated with a profile.
-x, --exclude-modules	excluded_modules	Modules to skip during the scan.
-g, --ports	ports	Specific ports to scan (e.g., 80,443,1-1000).
-t, --thread-per-host	thread_per_host	Concurrent connections per host.

Sources: nettacker/core/arg_parser.py:165-245, nettacker/locale/en.yaml:120-145

Logic and Validation Flow

The parse_arguments method implements the validation logic to ensure that provided inputs are mutually compatible and syntactically correct.

Target Validation Sequence

Key Validation Rules

1. Language Check: The requested language must exist in the self.languages list.
2. API Conflict: Prevents running the API server from within an existing API session.
3. Module/Profile Selection: At least one module or one profile must be selected unless the help/version menu is requested.
4. Hardware Usage: Validates that --set-hardware-usage is one of: low, normal, high, maximum.
5. Graph/Output Compatibility: If a graph is selected, the output file must end in .html or .htm.

Sources: nettacker/core/arg_parser.py:284-315, nettacker/core/arg_parser.py:350-385, nettacker/core/arg_parser.py:441-450

API Configuration

The system also handles arguments for the REST API server, allowing configuration of the host, port, and security settings.

# API Options setup in add_arguments
api_options = self.add_argument_group(_("API"), _("API_options"))
api_options.add_argument(
    "--start-api",
    action="store_true",
    dest="start_api_server",
    default=Config.api.start_api_server,
    help=_("start_api_server"),
)

Sources: nettacker/core/arg_parser.py:247-280, nettacker/config.py:94-105

API Whitelisting

If --api-client-whitelisted-ips is provided, the parser utilizes functions from nettacker.core.ip to expand CIDR blocks and IP ranges into a flat list of authorized IP addresses.

Sources: nettacker/core/arg_parser.py:317-326

Summary

The Argument Parsing System is a critical infrastructure component that bridges user intent with the engine's execution logic. By centralizing validation and resource discovery, it ensures that OWASP Nettacker operates within safe parameters while providing a flexible interface for both human operators and automated systems.

Sources: nettacker/core/readme.md:1-15, AGENTS.md:1-20