init commit
This commit is contained in:
245
README.md
Normal file
245
README.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 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
|
||||
|
||||
1. Create or modify a configuration file in `configs/`:
|
||||
|
||||
```yaml
|
||||
title: "My Infrastructure Scan"
|
||||
sites:
|
||||
- name: "Web Servers"
|
||||
ips:
|
||||
- address: "192.168.1.10"
|
||||
expected:
|
||||
ping: true
|
||||
tcp_ports: [22, 80, 443]
|
||||
udp_ports: []
|
||||
```
|
||||
|
||||
2. Build and run:
|
||||
|
||||
```bash
|
||||
docker-compose build
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
3. Check results in the `output/` directory
|
||||
|
||||
## Scan Performance
|
||||
|
||||
SneakyScanner uses a five-phase approach for comprehensive scanning:
|
||||
|
||||
1. **Ping Scan** (masscan): ICMP echo detection - ~1-2 seconds
|
||||
2. **TCP Port Discovery** (masscan): Scans all 65535 TCP ports at 10,000 packets/second - ~13 seconds per 2 IPs
|
||||
3. **UDP Port Discovery** (masscan): Scans all 65535 UDP ports at 10,000 packets/second - ~13 seconds per 2 IPs
|
||||
4. **Service Detection** (nmap): Identifies services on discovered TCP ports - ~20-60 seconds per IP with open ports
|
||||
5. **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
|
||||
|
||||
1. Build the image:
|
||||
|
||||
```bash
|
||||
docker build -t sneakyscanner .
|
||||
```
|
||||
|
||||
2. Run a scan:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
- `--privileged` flag or `CAP_NET_RAW` capability for masscan and nmap raw socket access
|
||||
- `--network host` for 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
|
||||
Reference in New Issue
Block a user