SneakyScanner
A dockerized network scanning tool that uses masscan for fast port discovery and nmap for service detection to perform comprehensive infrastructure audits. SneakyScanner accepts YAML-based configuration files to define sites, IPs, and expected network behavior, then generates machine-readable JSON reports with detailed service information.
Features
- YAML-based configuration for defining scan targets and expectations
- Comprehensive scanning using masscan:
- Ping/ICMP echo detection
- TCP port scanning (all 65535 ports)
- UDP port scanning (all 65535 ports)
- Service detection using nmap:
- Identifies services running on discovered TCP ports
- Extracts product names and versions
- Provides detailed service information
- HTTP/HTTPS analysis and SSL/TLS security assessment:
- Detects HTTP vs HTTPS on web services
- Extracts SSL certificate details (subject, issuer, expiration, SANs)
- Calculates days until certificate expiration
- Tests TLS version support (TLS 1.0, 1.1, 1.2, 1.3)
- Lists accepted cipher suites for each TLS version
- JSON output format for easy post-processing
- Dockerized for consistent execution environment and root privilege isolation
- Compare actual vs. expected network behavior
Requirements
- Docker
- Docker Compose (optional, for easier usage)
Quick Start
Using Docker Compose
- Create or modify a configuration file in
configs/:
title: "My Infrastructure Scan"
sites:
- name: "Web Servers"
ips:
- address: "192.168.1.10"
expected:
ping: true
tcp_ports: [22, 80, 443]
udp_ports: []
- Build and run:
docker-compose build
docker-compose up
- Check results in the
output/directory
Scan Performance
SneakyScanner uses a five-phase approach for comprehensive scanning:
- Ping Scan (masscan): ICMP echo detection - ~1-2 seconds
- TCP Port Discovery (masscan): Scans all 65535 TCP ports at 10,000 packets/second - ~13 seconds per 2 IPs
- UDP Port Discovery (masscan): Scans all 65535 UDP ports at 10,000 packets/second - ~13 seconds per 2 IPs
- Service Detection (nmap): Identifies services on discovered TCP ports - ~20-60 seconds per IP with open ports
- HTTP/HTTPS Analysis (SSL/TLS): Detects web protocols and analyzes certificates - ~5-10 seconds per web service
Example: Scanning 2 IPs with 10 open ports each (including 2-3 web services) typically takes 1.5-2.5 minutes total.
Using Docker Directly
- Build the image:
docker build -t sneakyscanner .
- Run a scan:
docker run --rm --privileged --network host \
-v $(pwd)/configs:/app/configs:ro \
-v $(pwd)/output:/app/output \
sneakyscanner /app/configs/your-config.yaml
Configuration File Format
The YAML configuration file defines the scan parameters:
title: "Scan Title" # Required: Report title
sites: # Required: List of sites to scan
- name: "Site Name"
ips:
- address: "192.168.1.10"
expected:
ping: true # Expected ping response
tcp_ports: [22, 80] # Expected TCP ports
udp_ports: [53] # Expected UDP ports
See configs/example-site.yaml for a complete example.
Output Format
Scan results are saved as JSON files in the output/ directory with timestamps. The report includes the total scan duration (in seconds) covering all phases: ping scan, TCP/UDP port discovery, and service detection.
{
"title": "Sneaky Infra Scan",
"scan_time": "2024-01-15T10:30:00Z",
"scan_duration": 95.3,
"config_file": "/app/configs/example-site.yaml",
"sites": [
{
"name": "Production Web Servers",
"ips": [
{
"address": "192.168.1.10",
"expected": {
"ping": true,
"tcp_ports": [22, 80, 443],
"udp_ports": [53]
},
"actual": {
"ping": true,
"tcp_ports": [22, 80, 443, 3000],
"udp_ports": [53],
"services": [
{
"port": 22,
"protocol": "tcp",
"service": "ssh",
"product": "OpenSSH",
"version": "8.2p1"
},
{
"port": 80,
"protocol": "tcp",
"service": "http",
"product": "nginx",
"version": "1.18.0",
"http_info": {
"protocol": "http"
}
},
{
"port": 443,
"protocol": "tcp",
"service": "https",
"product": "nginx",
"http_info": {
"protocol": "https",
"ssl_tls": {
"certificate": {
"subject": "CN=example.com",
"issuer": "CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US",
"serial_number": "123456789012345678901234567890",
"not_valid_before": "2025-01-01T00:00:00+00:00",
"not_valid_after": "2025-04-01T23:59:59+00:00",
"days_until_expiry": 89,
"sans": ["example.com", "www.example.com"]
},
"tls_versions": {
"TLS 1.0": {
"supported": false,
"cipher_suites": []
},
"TLS 1.1": {
"supported": false,
"cipher_suites": []
},
"TLS 1.2": {
"supported": true,
"cipher_suites": [
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
]
},
"TLS 1.3": {
"supported": true,
"cipher_suites": [
"TLS_AES_256_GCM_SHA384",
"TLS_AES_128_GCM_SHA256"
]
}
}
}
}
},
{
"port": 3000,
"protocol": "tcp",
"service": "http",
"product": "Node.js",
"http_info": {
"protocol": "http"
}
}
]
}
}
]
}
]
}
Project Structure
SneakyScanner/
├── src/
│ └── scanner.py # Main scanner application
├── configs/
│ └── example-site.yaml # Example configuration
├── output/ # Scan results (JSON files)
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md
Security Notice
This tool requires:
--privilegedflag orCAP_NET_RAWcapability for masscan and nmap raw socket access--network hostfor direct network access
Only use this tool on networks you own or have explicit authorization to scan. Unauthorized network scanning may be illegal in your jurisdiction.
Future Enhancements
- Webpage Screenshots: Capture screenshots of discovered web services for visual verification
- HTML Report Generation: Build comprehensive HTML reports from JSON output with:
- Service details and SSL/TLS information
- Visual comparison of expected vs. actual results
- Certificate expiration warnings
- TLS version compliance reports
- Embedded webpage screenshots
- Comparison Reports: Generate diff reports showing changes between scans
- Email Notifications: Alert on unexpected changes or certificate expirations
- Scheduled Scanning: Automated periodic scans with cron integration
- Vulnerability Detection: Integration with CVE databases for known vulnerabilities