ft_nmap - Network Port Scanner

A custom implementation of the famous Nmap (Network Mapper) port scanner, developed in C as part of the 42 curriculum. This project recreates core functionality of Nmap with additional bonus features including geolocation, reverse DNS lookup, and traceroute capabilities.

🚀 Features

Core Functionality

• Multiple Scan Types: SYN, NULL, FIN, XMAS, ACK, and UDP scans
• Port Range Scanning: Scan individual ports or ranges (default: 1-1024, max: 1024 ports)
• IPv4 & DNS Support: Scan IP addresses or domain names
• Multi-threading: Parallel scanning with up to 250 threads for speed
• Raw Socket Programming: Low-level packet crafting and analysis

Bonus Features

• 🌍 Geolocation: Get geographical location of target IPs
• 🔍 Reverse DNS Lookup: Resolve IP addresses to hostnames
• 📍 Traceroute: Show number of hops to targets
• 📡 Ping Detection: Check if targets are alive before scanning
• 📊 Detailed Results: Comprehensive port status reporting and verbose mode

🏆 Key Achievements

Technical Implementation

• 🔧 Raw Socket Programming: Built from scratch using raw sockets for complete control over packet creation and transmission
• 🧵 Multi-threaded Architecture: Implemented efficient parallel scanning with up to 250 concurrent threads
• 📦 Custom Packet Crafting: Manual TCP/UDP header construction with proper checksum calculation
• 🎯 Network Protocol Mastery: Deep understanding of TCP/IP stack, packet structures, and network scanning techniques

Advanced Features

• 🌐 Cross-Platform Compatibility: Robust implementation working across different Linux distributions
• ⚡ Performance Optimization: Rate limiting for UDP scans and efficient thread management
• 🔍 Network Analysis: Integrated packet capture and analysis using libpcap
• 📡 Bonus Integrations: Successfully integrated external APIs for geolocation and network diagnostics

Code Quality & Design

• 📚 Modular Architecture: Clean separation of concerns with dedicated modules for parsing, scanning, and output
• 🛡️ Error Handling: Comprehensive error management and graceful failure handling
• 📋 Memory Management: Proper resource allocation and cleanup without memory leaks
• ⚙️ Configurable Options: Extensive command-line interface with multiple scanning modes and options

📋 Requirements

System Dependencies

# Ubuntu/Debian
sudo apt install libpcap-dev libcurl4-openssl-dev libcjson-dev

Permissions

This program requires root privileges to create raw sockets:

sudo ./ft_nmap [options]

🛠️ Installation

1. Clone the repository

   git clone https://github.com/jesuserr/42Cursus_ft_nmap.git
   cd 42Cursus_ft_nmap

2. Compile the project

   make

3. Clean build files (optional)

   make clean    # Remove object files
   make fclean   # Remove all generated files
   make re       # Rebuild everything

📖 Usage

Basic Syntax

sudo ./ft_nmap [OPTIONS] --ip IP_ADDRESS
sudo ./ft_nmap [OPTIONS] --file FILE_WITH_IPS

Command Line Options

Option	Description	Example
--help	Display help and exit	--help
--ports [RANGE]	Port range to scan (default: 1-1024, max: 1024 ports)	--ports 80-443
--ip ADDRESS	Target IP or hostname	--ip scanme.nmap.org
--file FILE	File with target IPs (max: 5)	--file targets.txt
--speedup [N]	Use N parallel threads (max: 250)	--speedup 100
--scan [TYPES]	Scan types (comma-separated)	--scan SYN,UDP
--ping	Ping targets before scanning	--ping
--trace	Show hops to target	--trace
--rdns	Reverse DNS lookup	--rdns
--open	Show only open ports	--open
--geo	Enable geolocation	--geo
--verbose	Verbose output	--verbose

Scan Types

Type	Description	TCP Flags
SYN	TCP SYN scan (stealth)	SYN
NULL	TCP NULL scan	None
FIN	TCP FIN scan	FIN
XMAS	TCP XMAS scan	FIN, PSH, URG
ACK	TCP ACK scan	ACK
UDP	UDP scan (1-second delay between packets to avoid flooding)	N/A

Port Specification

• Default Range: If no --ports option is specified, scans ports 1-1024
• Custom Range: Use --ports 80-443 to scan a range of ports
• Limitations: Maximum of 1024 ports can be scanned in a single run

🎯 Examples

Basic Scans

# Simple SYN scan on default ports (1-1024)
sudo ./ft_nmap --ip scanme.nmap.org --scan SYN
# Equivalent to -> sudo nmap scanme.nmap.org -sS -p 1-1024

# Multi-threaded SYN,XMAS,ACK scan on custom range
sudo ./ft_nmap --ip scanme.nmap.org --speedup 70 --ports 20-90 --scan SYN,ACK,XMAS

# UDP scan on specific ports (with 1-second delay between packets)
sudo ./ft_nmap --ip scanme.nmap.org --ports 60-69 --scan UDP
# Equivalent to -> sudo nmap scanme.nmap.org -p 60-69 -sU

Advanced Features

# Full feature scan with geolocation
sudo ./ft_nmap --ip scanme.nmap.org --scan SYN --ping --trace --rdns --geo --verbose

# Multiple targets from file (single-threaded)
sudo ./ft_nmap --file hosts.txt --scan SYN,ACK,NULL --open

# Multiple targets from file (multi-threaded)
sudo ./ft_nmap --file hosts.txt --scan SYN,ACK,NULL --open --speedup 250 

Input File Format (5 hosts max.)

# hosts.txt
scanme.nmap.org
192.168.1.1
target003.com
target004.com
target005.com

🏗️ Project Structure

ft_nmap/
├── libft/                     # Custom C library with utility functions
├── srcs/                      # Source code
│   ├── ft_nmap.h              # Main header with structures and prototypes
│   ├── main.c                 # Entry point and program flow
│   ├── parser.c               # Command-line argument parsing
│   ├── parser_utils.c         # Parsing utility functions
│   ├── ip_utils.c             # IP address and network utilities
│   ├── scan_single_thread.c   # Single-threaded scanning implementation
│   ├── scan_multi_thread.c    # Multi-threaded scanning implementation
│   ├── pcap.c                 # Packet capture and analysis
│   ├── signals.c              # Signal handling (SIGINT, SIGALRM)
│   ├── bonus.c                # Bonus features (ping, traceroute, geolocation)
│   ├── print_errors.c         # Error handling and usage display
│   ├── print_results.c        # Results formatting and output
├── Makefile                   # Build configuration
└── README.md                  # This documentation

Key Components

• 🔧 Parser Module: Command-line argument processing
• 🌐 Network Module: IP resolution and socket management
• 📡 Scanner Module: Multi-threaded port scanning engine
• 📦 Packet Module: Raw packet crafting with libpcap
• 🎁 Bonus Module: Geolocation, DNS, and traceroute features

🛡️ Security Notes

• Requires root privileges for raw socket access
• Some firewalls may block or detect scanning activity
• Use responsibly and only on networks you own or have permission to test
• Designed for educational purposes

🤝 Contributing and License

This is an educational project for the 42 School curriculum. While not actively maintained for contributions, feel free to:

• Report bugs or issues
• Suggest improvements
• Fork for your own learning

🙏 Acknowledgments

Video Tutorials

• How Nmap really works // And how to catch it // Stealth scan vs TCP scan // Wireshark analysis - Deep dive into how Nmap operates internally, stealth vs TCP scanning techniques, and network traffic analysis using Wireshark
• Nmap Tutorial to find Network Vulnerabilities - Comprehensive tutorial on using Nmap to discover network vulnerabilities and security weaknesses
• Nmap Full Guide - Complete guide covering all aspects of Nmap usage, from basic scans to advanced techniques

Development Resources

• Nmap project - The original network discovery and security auditing utility for reference and inspiration
• Wireshark - Essential network protocol analyzer for debugging packet crafting and understanding network traffic
• tcpdump & libpcap - Official tcpdump and libpcap documentation and resources
• Using libpcap in C - Practical guide to packet capture programming with libpcap

---

Made with ❤️ for the 42 School curriculum