ScanCannon v1.9

A Bash script for efficient credentials-based attack surface enumeration and general reconnaissance of massive external network ranges.

ScanCannon handles the enumeration of extremely large networks (such as The Internet) at high of speeds as the infrastructure can handle, specifically looking for credentials-based attack surfaces and APIs. It uses masscan to quickly identify open ports, then calls nmap to gain detailed information on the systems and services listening on those ports, thus compensating for the lack of acureacy in masscan. Output is a consolidated HTML/CSV report plus flat text files of IPs, hostnames, and interesting services, ready to load into the next tool in your killchain. Runs are organized into projects, and each scan reports what changed since the last one.

Table of Contents

• What is ScanCannon?
• Prerequisites
• Installation
• Quick Start
• Configuration
• Usage Examples
• Progress Tracking
• Understanding Output
• Safety & Legal Considerations
• Troubleshooting
• FAQ
• Known Issues
• License

What is ScanCannon?

Features

• High-speed enumeration — masscan finds open ports, nmap deep-scans only the responsive hosts
• Full ASN-based discovery — resolves A records, queries whois for CIDR + ASN, then pulls every prefix the ASN announces via RADB, with interactive range selection (-d and -c)
• Projects & scan-diff — results are grouped per project and each run reports what changed (new/gone services) versus the previous scan, turning repeat scans into attack-surface monitoring
• Resume — completed CIDRs are checkpointed and skipped on re-run; masscan state is preserved on interrupt
• API detection (-a) — nmap NSE + targeted curl probing, plus TLS-certificate SAN harvesting that feeds new hostnames back into discovery
• CVE hinting (-V) — nmap vulners NSE against detected service versions
• Consolidated report — a self-contained report.html and flat findings.csv per run, alongside the raw per-service text files
• Service categorization for common credential attack vectors (SSH, FTP, HTTP, SMB, etc.) and automatic domain/subdomain discovery
• Fast & resilient — parallel per-host/per-CIDR scanning, whois caching with retry/backoff, completion notifications (-n)
• Cross-platform (Linux, macOS, WSL2), Bash 3.2-compatible

Target Services

ScanCannon focuses on these high-value services for security assessment:

TCP Services:

• 21 - FTP (File Transfer Protocol)
• 22 - SSH (Secure Shell)
• 23 - Telnet
• 53 - DNS (Domain Name System)
• 80 - HTTP (Web servers)
• 135 - MSRPC (Microsoft RPC)
• 139 - NetBIOS Session Service
• 443 - HTTPS (Secure web servers)
• 445 - Microsoft-DS (SMB/CIFS)
• 990 - SFTP (Secure FTP)
• 1701 - L2F (Layer 2 Forwarding)
• 1723 - PPTP (Point-to-Point Tunneling Protocol)

UDP Services (with -u flag):

• 53 - DNS (Domain Name System)
• 161 - SNMP (Simple Network Management Protocol)
• 500 - ISAKMP (Internet Security Association and Key Management Protocol)

This focused approach dramatically reduces scan time while ensuring all high-value attack surface services are discovered.

Prerequisites

• Root/Administrator privileges (required for raw packet manipulation)
• Masscan v1.0.3+ - High-speed port scanner
• Nmap v7.0.1+ - Network discovery and security auditing
• Standard Unix tools: dig, whois, wget, awk, sed
• curl (optional, required for API detection -a and webhook notifications -n)

Quick Start

Command Syntax

sudo ./scancannon.sh [-u] [-a] <-d domain | -c CIDR | -f file> [...]

At least one -d, -c, or -f flag is required. All three flags are repeatable and can be combined.

Options:

• -d domain : Discover all networks for a domain (resolves all A records → whois → ASN → RADB prefix lookup; repeatable; accepts URLs too)
• -c CIDR : Discover all networks related to a CIDR (whois → ASN → RADB prefix lookup; repeatable)
• -f file : Read CIDR ranges from a file (one per line, blank lines and # comments ignored; repeatable). Entries are scanned as-is — ASN discovery is skipped by default so curated lists don't get expanded into parent prefixes or trigger an interactive prompt per line.
• -F : Force ASN-based network discovery on -f file entries (treats each line like -c). Off by default.
• -u : Perform UDP scan on common ports (53, 161, 500) using nmap (significantly slower)
• -a : Perform API endpoint detection on HTTP/HTTPS services (requires curl); also harvests TLS-certificate SANs to discover more hostnames
• -V : CVE hinting — run nmap's vulners NSE against detected service versions
• -n target : Notify on completion — desktop (macOS/notify-send) or a webhook URL (ntfy/Slack-style POST, requires curl)
• -p name : Project name. Results go under ./projects/<name>/ and are diffed against that project's previous scan; skips the interactive project menu (useful for automation)

-d and -c run full ASN-based network discovery and present an interactive selection menu for each input. -f skips that step by default; pass -F to opt in.

Environment tunables: NMAP_MAX_PARALLEL (hosts/CIDR, default 4), DNS_MAX_PARALLEL (default 8), CIDR_MAX_PARALLEL (default 1), WHOIS_CACHE_TTL (seconds, default 86400).

Projects & scan-diff

Every run belongs to a project. On startup (unless -p is given) ScanCannon shows a menu to pick an existing project or create a new one; results are kept separate under ./projects/<name>/results/. Each run is snapshotted to ./projects/<name>/history/, and the report includes a Changes Since Last Scan section — new and disappeared host:port services versus the project's previous scan — so repeated scans become attack-surface monitoring. A consolidated report.html and findings.csv are written per run.

Examples

# Scan a network by CIDR (includes ASN discovery of related networks)
sudo ./scancannon.sh -c 203.0.113.0/24

# Discover all networks for a domain (resolves all IPs → ASN → all announced prefixes)
sudo ./scancannon.sh -d example.com

# Scan networks listed in a file (one CIDR per line)
sudo ./scancannon.sh -f CIDRs.txt

# Combine domain + CIDR + file (all are scanned)
sudo ./scancannon.sh -d example.com -c 10.0.0.0/24 -f CIDRs.txt

# Include UDP scanning (slower but more comprehensive)
sudo ./scancannon.sh -u -d example.com

# Include API endpoint detection
sudo ./scancannon.sh -a -c 203.0.113.0/24

# Combine all flags
sudo ./scancannon.sh -ua -d example.com -c 10.0.0.0/24

Configuration

Basic Configuration

The main configuration is handled through scancannon.conf:

# Key settings you may want to adjust:
rate = 5000.00           # Packets per second (start low!)
excludefile = exclude.txt # Networks to exclude from scanning
# Only scan ports that ScanCannon actually uses - much more efficient!
ports = 21,22,23,53,80,135,139,443,445,990,1701,1723

Exclusion List

Edit exclude.txt to add networks you want to skip:

# Add networks to exclude (one per line)
192.168.0.0/16    # Private networks
10.0.0.0/8        # Private networks
172.16.0.0/12     # Private networks
127.0.0.0/8       # Loopback

Automatic Network Configuration

ScanCannon automatically prompts for network adapter configuration every time you run it. This ensures optimal performance by helping masscan achieve maximum scanning speed. The script will:

1. Detect network interfaces and let you choose which one to use
2. Automatically configure adapter-ip and adapter-mac settings
3. Find your default gateway and configure router-mac settings
4. Update scancannon.conf with the detected settings

# Every time you run ScanCannon:
sudo ./scancannon.sh -c 192.168.1.0/24

# You'll always see:
=== Network Adapter Configuration ===
For optimal performance, ScanCannon can automatically configure your network adapter settings.
This helps masscan achieve maximum scanning speed by bypassing the kernel network stack.

Would you like to automatically configure network adapter settings? [y/N]: y

# If multiple interfaces exist:
Multiple network interfaces found:
  [1] eth0 - IP: 192.168.1.100, MAC: aa:bb:cc:dd:ee:ff
  [2] wlan0 - IP: 10.0.0.50, MAC: 11:22:33:44:55:66
Select interface [1-2]: 1

# Configuration is automatically applied to scancannon.conf
# Answer 'N' if you want to keep existing settings or configure manually

Manual Network Configuration (Advanced)

If you prefer manual configuration or need to customize settings, you can edit scancannon.conf directly:

# Network adapter settings for maximum performance:
adapter-ip = 192.168.1.100    # Your machine's IP address
adapter-mac = aa:bb:cc:dd:ee:ff  # Your network card's MAC address
router-mac = 11:22:33:44:55:66   # Your router's MAC address

Why These Settings Matter:

• adapter-ip: Your machine's IP address on the scanning interface

  • Masscan uses this to craft packets with the correct source IP
  • Must match the IP of the interface you're scanning from

• adapter-mac: Your network card's MAC address

  • Used for raw packet transmission to bypass kernel networking
  • Improves performance by avoiding OS network stack overhead

• router-mac: Your default gateway's MAC address

  • Required for masscan to send packets directly to the router
  • Enables maximum scanning speed by bypassing ARP lookups

When These Settings Help:

• High-speed scans (>10,000 pps) - significantly improves performance
• Large network ranges - reduces packet loss and improves accuracy
• Dedicated scanning systems - maximizes hardware utilization
• Virtual machines - may be required for proper packet transmission

Manual Detection Commands:

# Linux - Get IP, MAC, and gateway:
ip addr show                    # Your IP and MAC
ip route show                   # Default gateway IP
arp -a | grep $(ip route | grep default | awk '{print $3}')  # Gateway MAC

# macOS - Get IP, MAC, and gateway:
ifconfig                        # Your IP and MAC
netstat -rn                     # Default gateway IP
arp -a | grep $(netstat -rn | grep default | awk '{print $2}')  # Gateway MAC

Important: Masscan requires MAC addresses in dash format (aa-bb-cc-dd-ee-ff), not colon format (aa:bb:cc:dd:ee:ff). The automatic configuration handles this conversion, but if configuring manually, ensure you use dashes.

Understanding Output

Each run's output lives under its project (./projects/<name>/):

projects/<name>/
├── results/
│   ├── report.html                    # Consolidated, browsable report
│   ├── findings.csv                    # Flat service,ip,port list
│   ├── 203_0_113_0_24/                 # Per-network results
│   │   ├── masscan_output.bin/.txt     # Raw masscan output
│   │   ├── hosts_and_ports.txt         # Discovered hosts:ports
│   │   ├── nmap_files/ gnmap_files/ nmap_xml_files/
│   │   ├── interesting_servers/        # Categorized services (ssh_, http_,
│   │   │                               #   api_servers.txt, cert_sans.txt, ...)
│   │   ├── resolved_subdomains.txt
│   │   └── resolved_root_domains.csv   # Domain details with WHOIS
│   ├── all_interesting_servers/        # Combined per-service lists
│   ├── all_subdomains.txt  all_cert_sans.txt  all_root_domains.csv
│   └── dead_networks.txt               # Unresponsive networks
└── history/                            # Timestamped snapshots (drives scan-diff)

Safety & Legal Considerations

⚠️ CRITICAL WARNING ⚠️

ScanCannon can easily cause Denial of Service conditions, even from a single source.

Rate Limiting Guidelines

Network Type	Recommended Rate	Notes
Home/SOHO	1,000-5,000 pps	May crash consumer routers
Small Business	5,000-10,000 pps	Monitor for connectivity issues
Enterprise	10,000-20,000 pps	Test incrementally
ISP/Large Scale	20,000+ pps	Can damage infrastructure

Best Practices

1. Start Low: Begin with rate = 1000 and increase gradually
2. Test First: Scan a small subnet before large networks
3. Monitor Impact: Watch for network degradation
4. Legal Compliance: Only scan networks you own or have permission to test
5. Backup Configs: Save working configurations before changes

Troubleshooting

Common Issues

"ERROR: masscan is not installed"

# Install masscan using your package manager
sudo apt install masscan  # Ubuntu/Debian

"ERROR: This script must be run as root"

# Run with sudo
sudo ./scancannon.sh -c 192.168.1.0/24

"No IPs are up; skipping nmap"

• Check if the target network is actually reachable
• Verify your network configuration in scancannon.conf
• Try a lower scan rate
• Check firewall rules

Scan seems to hang or is very slow

• Reduce the rate setting in scancannon.conf
• Check network connectivity
• Verify target networks are responsive

"bad MAC address" error from masscan

• Masscan requires MAC addresses in dash format (aa-bb-cc-dd-ee-ff), not colon format (aa:bb:cc:dd:ee:ff)
• The automatic configuration now handles this conversion automatically
• If configuring manually, convert colons to dashes: aa:bb:cc:dd:ee:ff → aa-bb-cc-dd-ee-ff

FAQ

Don't nmap and masscan do the same thing? Why use both?

Masscan sacrifices accuracy for speed and may miss responses due to its aggressive scanning approach. ScanCannon uses masscan to quickly identify which IP addresses have listening services, then uses nmap's more reliable scanning against only those responsive hosts. This gives you both speed and accuracy.

Doesn't Tool X do all of this and more? Why use this one?

Most enumeration tools try to be comprehensive "one-stop shops" but end up being mediocre at everything. ScanCannon focuses on doing network enumeration exceptionally well and outputs to standard, widely-compatible file formats that work with other specialized tools.

How does API endpoint detection work?

When the -a flag is used, ScanCannon employs a two-tier detection approach:

1. Tier 1 (Passive): During nmap TCP enumeration, lightweight NSE scripts (http-headers, http-title, http-robots.txt, http-server-header) are added for HTTP ports. The resulting XML output is then parsed for API framework fingerprints (Express, Django, Flask, FastAPI, Spring, etc.), API-related response headers (CORS, X-API-Version, JSON content types), and documentation page titles (Swagger UI, GraphQL Playground, etc.).

2. Tier 2 (Active): For each discovered HTTP/HTTPS host, curl probes 14 well-known API paths including /api, /api/v1, /swagger.json, /openapi.json, /graphql, and others. Responses are classified as API endpoints based on JSON content types, known API path patterns, and authentication-required responses (401/403).

Results are written to api_servers.txt (clean endpoint list) and api_details.txt (full detection log with tier indicators).

Why do I need root privileges?

Both masscan and nmap require raw socket access for SYN scanning and OS detection, which requires root privileges on Unix systems.

Can I pause and resume scans?

Yes. Each CIDR is checkpointed on completion, so re-running the same project and choosing Merge skips ranges already finished. If you interrupt a scan (Ctrl-C), masscan's state is saved to paused.conf for a manual masscan --resume.

How do I scan IPv6 networks?

ScanCannon currently focuses on IPv4 networks. For IPv6 scanning, use nmap directly or consider other specialized tools.

Known Issues

• Offline domain extraction: -d runs use the Public Suffix List (fetched automatically, cached ~30 days) for accurate registrable-domain extraction. If it can't be downloaded, ScanCannon falls back to a built-in common-ccTLD table, which may occasionally mis-split an uncommon suffix.
• IPv4 only: IPv6 targets are not scanned.

License

This project is released under the Creative Commons Attribution-NonCommercial 3.0 Unported License.

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material

Under the following terms:

• Attribution — You must give appropriate credit to all contributors, provide a link to the license, and indicate if changes were made
• NonCommercial — You may not use the material for commercial purposes

For the full license text, see LICENSE.

---

ScanCannon v1.9 by J0hnnyXm4s

"Efficient credential attack surface enumeration and general reconnaissance of massive network ranges"