ScanCannon - A script for credentials-based attack surface enum

项目说明

ScanCannon v1.9

!scancannon

A Bash script for efficient credentials-based attack surface enumeration and general reconnaissance of massi 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/CS 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 responsi

Full ASN-based discovery — resolves A records, queries whois for CIDR + ASN, then pulls every prefix the ASN announces via RADB, with interacti selection (-d and -c)

Projects & scan-diff — results are grouped per project and each run reports what changed (new/gone services) 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 har that feeds new hostnames back into discovery

C (-V) — nmap NSE against detected service

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 (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 pri (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

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 interacti 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 : C — run nmap's NSE against detected service

-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 interacti menu (useful for automation)

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

En 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 the project's previous scan — so repeated scans become attack-surface monitoring. A consolidated report.html and findings.csv are written per run.

Examples

Configuration

Basic Configuration

The main configuration is handled through scancannon.conf:

Exclusion List

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

Automatic Network Configuration

ScanCannon automatically prompts for network adapter configuration every time you run it. This ensures optimal performance by helping masscan achie 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

Manual Network Configuration (Ad)

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

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
- Impro by a OS network stack o

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 impro

Large network ranges - reduces packet loss and impro

Dedicated scanning systems - maximizes hardware utilization

machines - may be required for proper packet transmission

Manual Detection Commands:

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 con, but if configuring manually, ensure you use dashes.

Understanding Output

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

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 ha to test
5. Backup Configs: Sa configurations before changes

Troubleshooting

Common Issues

"ERROR: masscan is not installed"

"ERROR: This script must be run as root"

"No IPs are up; skipping nmap"

Check if the target network is actually reachable

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

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 con 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 aggressi approach. ScanCannon uses masscan to quickly identify which IP addresses ha services, then uses nmap's more reliable scanning against only those responsi. 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 e. 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-ser) 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-, 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 pri?

Both masscan and nmap require raw socket access for SYN scanning and OS detection, which requires root pri 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 Creati Attribution-NonCommercial 3.0 Unported License.

!CC BY-NC

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 gi 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 massi ranges"*

项目信息

开发语言：Shell

Star 数：481

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A script for credentials-based attack surface enumeration and general reconnaissance of massive external networks展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。