NetGuardian is a comprehensive network security and automation tool designed to facilitate efficient network discovery, scanning, monitoring, and reporting. The project integrates several key components to provide a holistic approach to network management and security analysis. Below are the main components and their functionalities:
The interactive menu engine (NetGuardian.py) is the entry point. It routes the user to the four functional modules, which persist their findings through the shared ReportGenerator. Note that the modules use different report formats: PortScanner writes CSV, TXT, and JSON; Discover writes CSV and TXT; the Analyzer detection routines report their results to the console and do not currently persist through ReportGenerator.
flowchart TD
User([User]) --> Menu["Menu Engine<br/>(NetGuardian.py)"]
subgraph Modules
Discover[Discover]
Scanner[PortScanner]
Analyzer[Analyzer]
Automation[TaskAutomation]
end
Menu --> Discover
Menu --> Scanner
Menu --> Analyzer
Menu --> Automation
Discover --> Report[ReportGenerator]
Scanner --> Report
Analyzer --> Report
Automation --> Report
Report --> Formats["CSV / TXT / JSON"]
The Discover module focuses on identifying and mapping network devices and their attributes. Its primary functions include:
- Network Data Retrieval: Gathers detailed network data such as IP addresses, network interfaces, and subnet information.
- Host Discovery: Utilizes ARP and ICMP protocols to identify active hosts on the network.
- MAC Address Management: Changes the MAC address of the network interface for anonymity or testing purposes.
- Network Mapping: Creates a visual representation of the network with discovered hosts.
- Traceroute and DNS Lookup: Provides path information to a destination and resolves domain names.
- OS Fingerprinting: Identifies the operating system running on a target IP.
Built on the NetworkConfig class, the Port_Scanner module offers extensive network scanning capabilities. Key features include:
- Targeted Scanning: Scans specified IP addresses and ports to identify open ports and services.
- Protocol and Service Detection: Identifies running services and their versions on open ports.
- SSL Certificate Retrieval: Fetches SSL certificates to ensure secure communication.
- Geolocation and MAC Address Resolution: Determines the physical location of IP addresses and retrieves MAC addresses.
- Extended Scanning Options: Includes additional functionalities like OS detection and banner grabbing.
The Analyzer module provides advanced network traffic analysis and anomaly detection. Its capabilities include:
- Traffic Monitoring: Captures and analyzes network traffic to identify devices based on traffic patterns.
- Rogue Device Detection: Identifies unauthorized devices and access points within the network.
- DNS Analysis: Performs DNS lookups and detects potential DNS spoofing or poisoning.
- Suspicious Activity Detection: Monitors the network for unusual activities, such as SYN flood attacks.
The TaskAutomation module allows users to automate and manage multiple tasks efficiently. It supports various execution modes:
- Sequential and Parallel Execution: Runs tasks one after another or simultaneously.
- Timed and Safe Modes: Adds delays between tasks for better management.
- Hardcore Mode: Retries failed tasks up to three times.
- Focus and Live Monitor Modes: Provides real-time monitoring and detailed logs of task execution.
- Smart Mode: Includes random delays and MAC address changes for enhanced security.
The Report_Generator module produces detailed reports in multiple formats. It includes:
- CSV, TXT, and JSON Report Generation: Converts scanned data into easily readable reports. CSV/TXT are used by Discover and PortScanner; JSON is produced by PortScanner. The JSON report stores metadata and records as structured keys so the output is always valid JSON.
- Metadata Addition: Includes essential information such as generation timestamp, user, and system details (as a header in TXT reports and as a
metadataobject in JSON reports). - Unique Filename Handling: Ensures reports do not overwrite existing files by generating unique filenames.
- Network Security Audits: Conduct comprehensive security audits to identify vulnerabilities and unauthorized devices.
- Routine Network Monitoring: Continuously monitor network traffic and detect any anomalies or suspicious activities.
- Incident Response: Quickly scan and analyze network segments in response to security incidents.
- Compliance Reporting: Generate detailed reports for compliance with industry regulations and standards.
- Penetration Testing: Use advanced scanning and MAC address spoofing techniques during penetration testing engagements.
NetGuardian offers a robust suite of tools for network administrators, security professionals, and IT auditors to maintain secure and well-managed network environments. Its combination of discovery, scanning, monitoring, and reporting capabilities ensures comprehensive coverage of all aspects of network security.
- Python 3.8+ (developed and tested on Python 3.12).
- A Linux host. The tool shells out to Linux utilities (
ping,timeout,ifconfig,sysctl) and reads/etc/sysctl.conf, so it is not portable to Windows/macOS as-is. - Root / sudo privileges. Raw packet operations (ARP/ICMP discovery, SYN and other scapy-based scans, traffic sniffing, MAC address changes, IP-forwarding toggling) require elevated privileges. Run with
sudo. - libpcap installed on the system (required by
scapyfor packet capture, e.g.sudo apt install libpcap-dev). - Python dependencies listed in
requirements.txt:scapy,netifaces,requests,networkx,matplotlib.
MAC.CSV (bundled) is the public IEEE OUI registry used for offline MAC-vendor lookups.
Clone the repository:
git clone https://github.com/kassam-99/NetGaurdian.git
cd NetGaurdian
(Optional) create a virtual environment:
python3 -m venv venv
source venv/bin/activate
Install dependencies:
pip install -r requirements.txt
Run the main interactive menu with root privileges:
sudo python3 NetGuardian.py
Individual modules can also be run on their own, e.g.:
sudo python3 Discover.py
sudo python3 Analyzer.py
python3 PortScanner.py
Follow the on-screen prompts to select a module and an action. See Instructions.txt for a per-module command reference.
A Dockerfile is provided so you can run NetGuardian with a reproducible dependency
environment (Python 3.12 + scapy/netifaces/networkx/matplotlib and the required
Linux packet utilities) instead of installing everything on the host.
Docker here provides reproducible dependencies, not isolation. NetGuardian is a raw-packet tool: ARP/ICMP discovery, SYN/ACK/FIN/etc. scans, traffic sniffing, MAC-address spoofing, and IP-forwarding toggling all need the host network and the
NET_RAW/NET_ADMINcapabilities. The container therefore shares the host's network stack and runs privileged operations directly against it.
Build the image:
docker build -t netguardian .
Run the interactive menu (Linux host required):
docker run --rm -it \
--net=host \
--cap-add=NET_RAW \
--cap-add=NET_ADMIN \
netguardian
Notes:
--net=hostis required so the tool sees your real interfaces; the added capabilities let scapy open raw sockets and let the MAC /sysctlpaths work.- To keep generated reports and captures on the host, bind-mount a directory onto
the working directory, e.g.
-v "$PWD/reports:/app"(or mount a subpath), then choose Save report to file in the menu. - The image intentionally runs as
root: the added capabilities are only effective for uid 0, and a non-root user would silently break every raw-socket feature.
Only run this against networks you own or are explicitly authorized to assess (see Authorized Use Only below). Running inside a container does not change your legal responsibilities.
NetGuardian is intended for defensive network administration, monitoring, and security auditing on networks you own or are explicitly authorized to assess. Scanning, sniffing, MAC-address spoofing, or otherwise probing networks and hosts without permission may be illegal in your jurisdiction. You are solely responsible for complying with all applicable laws and for obtaining written authorization before use. The authors accept no liability for misuse.
Earlier revisions of this project used the misspelling NetGaurdian for the
repository, entry-point script, and help file. These have all been corrected to
NetGuardian (NetGuardian.py). GitHub redirects the old repository URL, so
existing clones and links continue to work.
Contributing: Contributions, bug reports, and feature requests are welcome! Feel free to fork the repository, make your changes, and submit a pull request.