This document serves as the technical guide for the SCAN module. It is designed to provide a comprehensive understanding of the component's inner workings, implementation details, and defensive capabilities for technical presentations and architectural reviews.
Module Philosophy
The SCAN module is fundamentally designed as an Autonomous Diagnostic Expert System rather than a traditional, passive network scanner. Its primary objective is to evaluate target infrastructures by adopting an offensive reconnaissance posture, quantifying security risks through predefined metrics, and executing immediate mitigations or hotfixes.
Internal Architecture and Component Workflow
The codebase is structured into specialized python scripts, executing sequentially to form an automated assessment pipeline:
[ discovery.py ] ──(IPs/MAC)──> [ port_scanner.py ] ──(Services)──> [ vulnerability_scanner.py ]
│
[ auto_patcher.py ] <──(Mitigation Order)── [ resolution_engine.py ] <──────┘
1. Network Discovery — discovery.py
- Mechanism: Maps the local area network (LAN) topology by broadcasting raw Address Resolution Protocol (ARP) requests.
- Implementation Details: Leverages the Scapy library to forge custom network packets from scratch. Unlike standard ICMP ping requests, which are frequently dropped or restricted by modern host-based firewalls, ARP resolution is technically mandatory for local subnet communications. This architectural choice makes the discovery phase resilient against standard stealth configurations.
- Collected Data: Target IP addresses, MAC addresses, and resolved hostnames.
2. Surface Reconnaissance — port_scanner.py
- Mechanism: Probes designated network interfaces to identify active listener ports and available attack surfaces.
- Core Engine: Integrates the OWASP Nettacker framework to ensure industrial-grade reliability, multi-threading capabilities, and native JSON output formatting.
- Output: A structured mapping of open ports associated with their respective network transport protocols and services (e.g., HTTP on port 80, SSH on port 22).
3. Vulnerability Assessment — vulnerability_scanner.py
- Mechanism: Inspects the application layer of identified open services to detect known misconfigurations and software flaws.
-
Targeted Checks:
- Software Version Heuristics: Banner grabbing to identify outdated software components exposed to known CVEs.
-
Information Disclosure: Scanning for orphaned repositories, exposed metadata, or backup files (e.g.,
.gitdirectories,backup.zip). - Web Application Flaws: Verifying the absence of essential security headers, such as anti-clickjacking directives.
4. Resolution Engine & Scoring Matrix — resolution_engine.py
This component serves as the core algorithmic decision layer of the pipeline.
-
Expert System Knowledge Base: Utilizes a static dictionnaire (
RESOLUTION_GUIDES) that maps specific vulnerability signatures to explicit technical remediation scripts. - Fail-Safe Mechanism (Generic Alerting): In the event that the scanner encounters an undocumented or highly specialized flaw, the pipeline handles the exception without crashing. It generates a Generic Alert that enforces system logging and prompts administrative intervention, ensuring no anomaly goes unnoticed.
-
Quantitative Scoring Algorithm:
- Each target host initializes with a baseline security posture score of 100.
- Deductions are dynamically calculated and subtracted from the total based on the CVSS-aligned severity of discovered vulnerabilities.
-
Posture Classifications:
- Safe (>80): Healthy security posture; low risk profile.
- At Risk (50-80): Noticeable configuration drifts; remediation required.
- Critical (<50): Immediate risk of system compromise or intrusion.
5. Automated Remediation — auto_patcher.py
- Mechanism: Operates as an automated maintenance agent to enforce immediate threat mitigation.
-
Concrete Operations: Programmatically modifies local service configurations (e.g., hardening encryption parameters within
/etc/ssh/sshd_config) and injects strict access control rules into the Uncomplicated Firewall (UFW) subsystem to apply the principle of least privilege.
Subsystem Interactions: SCAN vs SENTINELLE
The table below outlines the operational boundaries and synergies between the proactive assessment layer (SCAN) and the reactive monitoring layer (SENTINELLE):
| Operational Metric | SCAN Module | SENTINELLE Module |
|---|---|---|
| Operational Mode | Proactive (Audit & Hardening) | Reactive (Detection & Blocking) |
| Temporal Layout | Execution via cron scheduling or manual trigger. | Continuous background daemon execution (Real-time). |
| Port Management | Identifies open ports and restricts unauthorized ones. | Monitors inbound connections to detect external port scans. |
| System Analogy | An inspector verifying physical structural integrity. | A security guard and motion sensor monitoring access. |
Operational Synergy: If the SCAN module leaves a port open to accommodate specific business requirements, the SENTINELLE module monitors traffic anomalies on that vector. If unauthorized or malicious activity occurs, SENTINELLE isolates the threat vector and blocks the source IP address immediately.
Technical Design Decisions & Defensive FAQ
Why implement OWASP Nettacker over Nmap?
While Nmap remains an industry standard for raw network discovery and packet-level manipulation, Nettacker is natively structured around vulnerability assessment workflows. Its plugin architecture and modular JSON outputs integrate seamlessly with a centralized cloud database, simplifying data parsing for the resolution engine.
What are the operational risks of automated patching?
Automated patching introduces risks regarding service availability and configuration regression. To mitigate this, the feature can be toggled by the system administrator. However, on critical or highly exposed infrastructures, automating remediation significantly decreases the window of exposure—the time elapsed between vulnerability discovery and patch deployment.
How does the SCAN module patch remote hosts without inbound SSH access?
MIRAGE utilizes a decoupled, asynchronous messaging architecture. When the SCAN module identifies a vulnerability on a remote host, it does not connect directly to the target machine. Instead, it publishes the diagnostic report and a standardized remediation order to a central cloud instance (MongoDB Atlas). The remote target runs a local SENTINELLE agent that maintains an outbound connection to this database cluster. Upon receiving the JSON-encoded command, the local agent executes the instructions natively via its own auto_patcher.py script. This eliminates the requirement to expose administrative management ports to the network.