REST API Documentation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The OWASP Nettacker REST API provides a programmatic interface for interacting with the framework's core capabilities, including scan execution, result retrieval, and report management. It is built using the Flask web framework and serves as the backend for the integrated Web UI, enabling automation and integration with other security tools or CI/CD pipelines.
The API supports multi-threaded scanning, historical scan comparison, and multi-format report generation (HTML, JSON, CSV). Access is secured via API keys and optional IP whitelisting.
Sources: README.md:28-36, nettacker/api/engine.py:34-45, nettacker/config.py:73-81
API Architecture and Flow
The API operates as a standalone service that interacts with the core Nettacker engine and its underlying database (SQLite by default). It handles incoming HTTP requests, validates credentials, and dispatches tasks to the engine.
Request Processing Flow
When a request is received, the API follows a specific validation and processing sequence:
The diagram shows the lifecycle of an API request from IP filtering to final response.
Sources: nettacker/api/engine.py:102-116, nettacker/api/engine.py:214-228, nettacker/api/engine.py:461-480
Configuration
The API behavior is governed by the ApiConfig class within the project configuration.
| Parameter | Type | Default Value | Description |
|---|---|---|---|
api_hostname | String | 0.0.0.0 | Host address the API server binds to. |
api_port | Integer | 5000 | Port number for the API server. |
api_access_key | String | Random (32 chars) | Secret key required for authenticated endpoints. |
api_client_whitelisted_ips | List | [] | List of authorized IP/CIDR/Ranges. |
api_access_log | String | .nettacker/data/nettacker.log | Path to the API access log file. |
api_debug_mode | Boolean | False | Toggles Flask debug mode. |
Sources: nettacker/config.py:73-88, nettacker/api/engine.py:461-470
Security and Authentication
Authentication is primarily handled via a specific API key. For web sessions, the API supports setting a secure cookie.
Authentication Sequence
Security Headers
The API automatically injects several security headers into every response:
Content-Security-Policy: upgrade-insecure-requestsX-Content-Type-Options: nosniffX-Frame-Options: SAMEORIGINX-XSS-Protection: 1; mode=block
Sources: nettacker/api/engine.py:121-129
API Endpoints
Scan Management
| Endpoint | Method | Description |
|---|---|---|
/new/scan | POST | Submits a new scan task. Requires targets and modules. |
/compare/scans | POST | Compares two historical scans by ID. |
Sources: nettacker/api/engine.py:204, nettacker/api/engine.py:238
Result and Log Retrieval
| Endpoint | Method | Description |
|---|---|---|
/results/get_list | GET | Returns a paginated list of all scan reports. |
/results/get | GET | Downloads a specific report file (HTML/TXT/JSON/CSV). |
/logs/get_list | GET | Returns a paginated list of recent host logs. |
/logs/search | GET | Searches through scan events using a query string. |
Sources: nettacker/api/engine.py:317, nettacker/api/engine.py:330, nettacker/api/engine.py:397, nettacker/api/engine.py:461
Session Management
| Endpoint | Method | Description |
|---|---|---|
/session/check | GET | Verifies if the current session/API key is valid. |
/session/set | GET/POST | Sets an authentication cookie in the browser. |
/session/kill | GET | Clears the authentication cookie (Logout). |
Sources: nettacker/api/engine.py:257, nettacker/api/engine.py:269, nettacker/api/engine.py:289
Implementation Details
Scan Submission
When /new/scan is called, the API sanitizes the report filename and initializes the Nettacker application class. The scan is then executed in a separate thread to avoid blocking the API response.
# From nettacker/api/engine.py:204-235
@app.route("/new/scan", methods=["GET", "POST"])
def new_scan():
api_key_is_valid(app, flask_request)
form_values = dict(flask_request.form)
# ... validation logic ...
nettacker_app = Nettacker(api_arguments=SimpleNamespace(**form_values))
thread = Thread(target=nettacker_app.run)
thread.start()
return jsonify(vars(nettacker_app.arguments)), 200
Sources: nettacker/api/engine.py:204-235
Data Models
The API interacts with the Report model and uses several helper functions for database queries:
select_reports(page): Retrieves report metadata.get_logs_by_scan_id(scan_id): Fetches detailed event logs for a specific scan.search_logs(page, query): Filters events across the entire database.
Sources: nettacker/api/engine.py:53-65, nettacker/api/readme.md:1-10
Summary
The REST API Documentation covers the critical interface for automating OWASP Nettacker. By leveraging Flask and multi-threading, the API allows users to trigger complex security scans, manage report data, and perform drift analysis through scan comparisons. Its integration with the configuration system ensures that security controls like IP whitelisting and API key management are strictly enforced.