Skip to main content

​
Overview

The Scanner module (modules/scanner.py) provides comprehensive network reconnaissance capabilities using Nmap. It handles TCP/UDP port scanning, operating system fingerprinting, service detection, and version enumeration.

​
Scanner Class

The Scanner class is defined at scanner.py:13 and serves as the main interface for network scanning operations.

​
Initialization

scanner.py:14-24
class Scanner:
    def __init__(self, target):
        """Initialize scanner with target"""
        self.target = target
        self.nm = nmap.PortScanner()
        self.scan_results = {
            'target': target,
            'os_detection': 'Unknown',
            'ports': [],
            'services': [],
            'scan_time': None
        }
​
target
string
required
Target IP address or domain name to scan

​
Key Methods

​
validate_target()

Validates that the target IP or domain is reachable before scanning.
scanner.py:26-35
def validate_target(self):
    """Validate target IP or domain"""
    try:
        import socket
        socket.gethostbyname(self.target)
        return True
    except socket.gaierror:
        print(f"[✗] Invalid target: {self.target}")
        return False

​
detect_os()

Detects the target’s operating system using Nmap’s OS fingerprinting or TTL analysis.
scanner.py:37-79
def detect_os(self):
    """Detect operating system using Nmap"""
    # Run OS detection with Nmap (requires root/sudo)
    self.nm.scan(self.target, arguments='-O -Pn')
    
    # Fallback: Try using TTL values
    # TTL <= 64: Linux/Unix
    # TTL <= 128: Windows
OS detection requires root/sudo privileges for Nmap’s advanced fingerprinting features.
Detection Methods:
  1. Nmap OS Fingerprinting (-O flag): Most accurate, requires sudo
  2. TTL Analysis (fallback): Less accurate but works without elevated privileges

​
scan_all_ports()

Performs comprehensive TCP and UDP port scanning with service version detection.
scanner.py:81-140
def scan_all_ports(self):
    """Perform comprehensive port scan"""
    # Phase 1: Scan top 1000 TCP ports
    self.nm.scan(self.target, arguments='-sS -sV -T4 -Pn --top-ports 1000')
    
    # Phase 2: Scan common UDP ports
    self.nm.scan(self.target, arguments='-sU -Pn --top-ports 20')
Scan Phases:
1

Phase 1: TCP Scanning

Scans top 1000 TCP ports with service version detection using -sS -sV -T4 -Pn --top-ports 1000
2

Phase 2: UDP Scanning

Scans top 20 UDP ports using -sU -Pn --top-ports 20 for faster execution
Port Data Structure: 
port_data = {
    'port': 80,
    'protocol': 'tcp',
    'state': 'open',
    'service': 'http',
    'version': 'Apache 2.4.41',
    'extrainfo': '(Ubuntu)'
}

​
enumerate_services()

Extracts detailed service information from discovered open ports.
scanner.py:142-160
def enumerate_services(self):
    """Extract detailed service information"""
    services = []
    for port_data in self.scan_results['ports']:
        service_info = {
            'port': port_data['port'],
            'protocol': port_data['protocol'],
            'service': port_data['service'],
            'version': port_data['version'],
            'product': port_data.get('product', ''),
            'extrainfo': port_data.get('extrainfo', '')
        }
        services.append(service_info)
    return services

​
run_full_scan()

Orchestrates the complete scanning workflow.
scanner.py:180-195
def run_full_scan(self):
    """Execute complete scanning workflow"""
    # 1. Validate target
    if not self.validate_target():
        return None
    
    # 2. Detect OS
    self.detect_os()
    
    # 3. Scan ports
    self.scan_all_ports()
    
    # 4. Enumerate services
    self.enumerate_services()
    
    return self.scan_results

​
Usage Example

from modules.scanner import Scanner

# Initialize scanner
scanner = Scanner("192.168.1.100")

# Run full scan
results = scanner.run_full_scan()

# Access results
print(f"OS: {results['os_detection']}")
print(f"Open ports: {len(results['ports'])}")
for port in results['ports']:
    print(f"Port {port['port']}/{port['protocol']}: {port['service']} {port['version']}")

​
Nmap Arguments

The Scanner module uses these Nmap arguments:
ArgumentPurpose
-sSTCP SYN scan (stealth)
-sVService version detection
-sUUDP scan
-OOS detection
-PnSkip ping (assume host is up)
-T4Timing template (aggressive)
--top-ports NScan N most common ports

​
Output Format

{
  "target": "192.168.1.100",
  "os_detection": "Linux 3.2 - 4.9 (Accuracy: 95%)",
  "ports": [
    {
      "port": 22,
      "protocol": "tcp",
      "state": "open",
      "service": "ssh",
      "version": "OpenSSH 7.4",
      "extrainfo": "protocol 2.0"
    },
    {
      "port": 80,
      "protocol": "tcp",
      "state": "open",
      "service": "http",
      "version": "Apache 2.4.41",
      "extrainfo": "(Ubuntu)"
    }
  ],
  "services": [...],
  "scan_time": 45.3
}

​
Performance

  • Top 1000 ports: ~30-60 seconds
  • Top 20 UDP ports: ~10-20 seconds
  • Full scan (all 65535 ports): 5-15 minutes
Use -T4 timing for faster scans on reliable networks. For stealthy scans, use -T2 or -T3.

​
Error Handling

The Scanner module handles these common errors:
Returns None if target cannot be resolved or reached. Check network connectivity and DNS resolution.
Nmap requires sudo for SYN scans (-sS) and OS detection (-O). Run with sudo python3 main.py -t <target>.
Increase timeout in config.json or reduce number of ports scanned.

CLI Options

Command-line flags for scanner configuration

Configuration

Scanner settings in config.json

Troubleshooting

Solving permission and Nmap issues

Basic Scan Guide

Step-by-step scanning tutorial

Build docs developers (and LLMs) love

Get started for freeTalk to us