Hi there! I'm emmanuelygr, and this is my Network Reconnaissance Toolkit.

This project is a beginner-friendly Python script that acts as a wrapper around Nmap. It performs basic port scanning and service detection, printing out open ports in an easy-to-read format and saving the results to a JSON file.

As I dive into the exciting world of cybersecurity, I realized that understanding how networks and ports work is a fundamental skill. I built this toolkit to demystify port scanning, get hands-on experience with Python scripting, and learn how real-world tools like Nmap operate under the hood. It's a stepping stone on my journey from a beginner to a proficient cybersecurity learner!

Through building this project, I aimed to:

• Understand the basics of TCP/IP and networking.
• Learn how to interact with command-line tools (Nmap) programmatically using Python.
• Practice handling user inputs and command-line arguments gracefully.
• Learn how to structure a Python project and handle errors properly.
• Export data to JSON for reporting purposes.

• Basic Port Scan: Scans the top 1000 ports to identify open doors on a target.
• Service Detection: Identifies the software and version running on open ports.
• JSON Export: Automatically saves scan results into a structured JSON file for easy reading and later analysis.
• Graceful Error Handling: Provides clear error messages if the user enters invalid input or if Nmap isn't installed.
• Beginner Friendly: Heavily commented code to help other beginners understand exactly what each line does.

• Python 3: The main programming language.
• Nmap: The industry-standard network scanner.
• python-nmap: A Python library that helps interact with the Nmap tool.
• argparse: A built-in Python library for building command-line interfaces.
• JSON: Used for storing scan output data.

• TCP/IP: The fundamental protocol suite of the internet. Our scan primarily looks at TCP ports.
• Nmap (Network Mapper): An open-source tool used for network discovery and security auditing.
• Ports: Virtual doors on a computer where services listen for incoming connections. There are 65,535 possible ports!
• Port States:
  • Open: An application is actively accepting connections on this port.
  • Closed: No application is listening, but the port is accessible.
  • Filtered: A firewall or filter is blocking the probe, so Nmap can't tell if it's open or closed.

1. The script uses argparse to read the target IP or hostname from the command line.
2. It initializes the nmap.PortScanner() class.
3. It executes a scan using the arguments -sV (service version detection) and -p 1-1000 (scan first 1000 ports).
4. The script parses the output generated by Nmap.
5. It prints out the open ports and their associated services to the terminal.
6. Finally, it formats this data into a dictionary and saves it as a .json file.

network-recon-toolkit/
├── scanner.py          # The main Python script
├── requirements.txt    # Python dependencies
├── .gitignore          # Files to ignore in Git
├── LICENSE             # MIT License
└── README.md           # This document!

You must have Nmap installed on your system for this script to work.

• Windows: Download the installer from https://nmap.org/download.html.
• Linux (Debian/Ubuntu): Run sudo apt-get install nmap.
• macOS: Run brew install nmap.

Clone the repository and set up a virtual environment (optional but recommended):

# Clone the repository (if hosted) or navigate to the folder
cd network-recon-toolkit

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate

# Install the required Python packages
pip install -r requirements.txt

Run the script from the command line by passing a target. Always make sure you have permission to scan the target!

Basic scan:

python scanner.py 127.0.0.1

Scan and save output to a custom JSON file:

python scanner.py scanme.nmap.org -o my_scan.json

Get help and see all options:

python scanner.py -h

$ python scanner.py 127.0.0.1
[*] Starting scan on target: 127.0.0.1
[*] Running Nmap scan... This might take a moment depending on the target.

[+] Host: 127.0.0.1 (localhost)
[+] Status: up

[*] Protocol: TCP
    Port: 80    State: open    Service: http Apache httpd 2.4.41
    Port: 443   State: open    Service: https

[*] Scan complete. Awesome! Results saved to 'scan_results.json'.

If you are learning like me, try these exercises to improve the code:

1. Change the Nmap arguments to scan all 65,535 ports (-p-).
2. Add a feature to read a list of targets from a text file instead of a single target.
3. Modify the script to also scan for UDP ports.

WARNING: This tool is for educational purposes only.

• Never scan a target without explicit permission. Scanning unauthorized networks or systems is illegal and unethical.
• Use resources like scanme.nmap.org (which is provided by the Nmap creators for testing) or scan your own local devices.

• This script currently only performs basic TCP scanning.
• It requires elevated privileges (root/Admin) for certain Nmap features (like OS detection or SYN scans), though the default settings should work for standard users in most environments.
• Large scans can be slow; this script prioritizes simplicity over aggressive multithreading.

• Error: "Nmap is not installed or not found"
  • Make sure you installed Nmap and that it is in your system's PATH. You can verify by opening a new terminal and typing nmap -V.
• The scan is taking forever!
  • Some targets might be slow to respond or are filtering packets. Try scanning 127.0.0.1 (your local machine) first to ensure the tool works.

Through this project, I really cemented my understanding of how a client application communicates over specific ports, and how Nmap leverages network protocols to extract this information. I also learned a lot about defensive programming in Python—specifically, making sure the script doesn't just crash when a user forgets an argument or if Nmap is missing.

Here are 5+ things I'd like to add in the future:

1. OS Detection: Add Nmap's OS fingerprinting (-O) to guess the operating system of the target.
2. Web Interface: Build a simple Flask or FastAPI web frontend to trigger scans and view results in a browser.
3. Multiple Targets: Allow inputting a subnet (e.g., 192.168.1.0/24) to scan an entire network.
4. Export to CSV: Provide an option to export results to CSV for easier viewing in Excel.
5. Vulnerability Scanning: Integrate Nmap Scripting Engine (NSE) scripts to automatically flag common vulnerabilities.
6. Logging: Implement standard Python logging to keep track of scan history and errors.

Created by emmanuelygr as a cybersecurity learning project.