Network Scanner 🔍

A powerful, asynchronous network scanning tool built in Python that supports multiple scanning techniques, OS fingerprinting, and service detection. Built with modern async/await patterns and comprehensive error handling.

✨ Features

• Multiple Scanning Techniques

  • TCP Connect Scan (full handshake)
  • SYN Scan (stealth scanning)
  • UDP Scan (with ICMP handling)

• Advanced Detection

  • OS Fingerprinting
  • Service Version Detection
  • Host Discovery

• Performance & Control

  • Asynchronous Operation
  • Rate Limiting
  • Configurable Timing Templates
  • Concurrent Scanning

• Monitoring & Output

  • PCAP Capture Support
  • Rich Console Output
  • JSON/CSV Export
  • Detailed Logging

🚀 Quick Start

Prerequisites

• Python 3.9 or higher
• libpcap development files
• Root/Administrator privileges (for SYN/UDP scans)

Debian/Ubuntu

sudo apt-get update
sudo apt-get install python3-dev libpcap-dev python3.12-venv

Installation

1. Clone the repository:

git clone https://github.com/berkaysoylu/network_scanner.git
cd network_scanner

2. Create and activate a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On Linux/Mac

3. Install with Poetry:

pip install poetry
poetry install

📖 Usage

# Show help
poetry run python src/network_scanner/main.py -h

Basic Scanning

# Basic TCP scan
poetry run python src/network_scanner/main.py example.com -p 80,443

# Scan multiple ports
poetry run python src/network_scanner/main.py 192.168.1.1 -p 22,80,443,3306

# Scan a CIDR range
poetry run python src/network_scanner/main.py 192.168.1.0/24 -p 80

# Enable verbose output
poetry run python src/network_scanner/  main.py example.com -p 80,443 -v

Advanced Scanning

# SYN scan (requires root/sudo)
sudo poetry run python src/network_scanner/main.py example.com -s syn -p 80,443

# UDP scan
poetry run python src/network_scanner/main.py example.com -s udp -p 53,161

# Aggressive timing
poetry run python src/network_scanner/main.py example.com --timing aggressive -p 1-1000

# Save results
poetry run python src/network_scanner/main.py example.com -p 80,443 -o results.json

# Enable packet capture
poetry run python src/network_scanner/main.py example.com -p 80,443 --pcap ./captures

⚙️ Command Line Options

TARGET
    🎯 Target IP address or hostname

-p, --ports <port-range>
    🔍 Port(s) to scan (e.g., 80,443 or 20-25)
    Default: 1-1024

-t, --type <scan-type>
    🔧 Scan type (tcp/syn/udp)
    Default: tcp

--timing <timing-template>
    ⚡ Timing template
    Options: paranoid/sneaky/polite/normal/aggressive/insane
    Default: normal

-o, --output <file>
    💾 Output file path

--format <format>
    📊 Output format (text/json/csv)
    Default: text

--pcap <directory>
    📦 Enable PCAP capture and specify directory

-v, --verbose
    🔊 Enable verbose output

--debug
    🐛 Enable debug mode

🎯 Timing Templates

Template	Description	Use Case
paranoid	Very slow scanning	IDS Evasion
sneaky	Slow scanning	IDS Evasion
polite	Normal, conservative scanning	Production systems
normal	Default balanced scanning	General use
aggressive	Fast scanning	Lab environments
insane	Fastest scanning	Local network only

Configuration

The scanner can be configured through command-line arguments or environment variables:

# Environment variables
export SCANNER_DEFAULT_TIMEOUT=2.0
export SCANNER_MAX_CONCURRENT_SCANS=100

# Command line options
poetry run python src/network_scanner/main.py example.com \
    -p 80,443 \
    --timing normal \
    --output results.json \
    --pcap ./captures \
    --debug

🐳 Docker Usage

Running with Docker Compose

1. Build the container:

docker-compose build

2. Run a scan:

# Basic TCP scan
docker-compose run --rm network-scanner example.com -p 80,443

# SYN scan (stealth scan)
docker-compose run --rm network-scanner example.com -t syn -p 80,443

# Full scan with PCAP capture
docker-compose run --rm network-scanner example.com -p 1-1000 --pcap /app/pcap

# Save results to JSON
docker-compose run --rm network-scanner example.com -p 80,443 -o /app/results/scan.json

Volumes

• ./results: Scan results are saved here
• ./pcap: PCAP capture files are saved here

Environment Variables

• SCANNER_DEBUG: Enable debug output (true/false)
• SCANNER_VERBOSE: Enable verbose output (true/false)

🛡️ Security Considerations

• Always obtain permission before scanning networks
• Some scan types (SYN, UDP) require root/administrator privileges
• Be aware of local laws and regulations regarding port scanning
• Use appropriate timing templates to avoid detection/blocking

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Scapy library for packet manipulation
• Rich library for console output
• Poetry for dependency management