SunsetScan

Network security auditing for humans — powered by nmap, built for everyone.

[]

Website: sunsetscan.com

SunsetScan is a local-network security auditing tool for home network owners and IT staff who want the depth of nmap without learning nmap syntax. Point it at your network and it finds every active device, fingerprints running software, checks against known vulnerability databases and end-of-life records, probes web interfaces for common weaknesses, optionally performs a lockout-safe factory-default credential audit, and produces a clean HTML report with plain-English explanations and numbered steps to fix each finding. It is entirely read-only and non-destructive — nothing on your network is ever modified.

Platform Support

Why Linux? SunsetScan relies on raw sockets (ARP scanning, passive packet capture), Linux-specific APIs (/proc, ip route), and privilege checks (os.geteuid()) that are not available on native Windows. WSL2 provides a full Linux kernel and is the recommended path for Windows users.

Installation

SunsetScan ships with an installer that takes care of system tools (nmap, masscan, git, python3-venv), creates a project-local Python virtual environment, and installs all Python dependencies inside it. You will never be asked to pip install anything as root — that's important on modern Debian/Pi OS, see Why a venv? below.

Tier-1 platforms (fully tested)

Debian, Ubuntu, Raspberry Pi OS (Bookworm and newer), Linux Mint, Pop!_OS.

Tier-2 platforms (best-effort, same script)

Fedora, RHEL, CentOS, Rocky, Alma, Arch, Manjaro, openSUSE, macOS.

Four ways to install — pick one

1. Debian/Ubuntu package

Recommended for Debian, Ubuntu, Raspberry Pi OS, Linux Mint, and Pop!_OS:

curl -LO https://github.com/NoCoderRandom/sunsetscan/releases/download/v2.1.0/sunsetscan_2.1.0-1_all.deb
curl -LO https://github.com/NoCoderRandom/sunsetscan/releases/download/v2.1.0/sunsetscan_2.1.0-1_all.deb.sha256
sha256sum -c sunsetscan_2.1.0-1_all.deb.sha256
sudo apt install ./sunsetscan_2.1.0-1_all.deb
sunsetscan --version

2. One-line bootstrap

Clones the repo into ~/sunsetscan and runs the installer:

curl -fsSL https://raw.githubusercontent.com/NoCoderRandom/sunsetscan/main/bootstrap.sh | bash

Want it somewhere else? Set INSTALL_DIR:

INSTALL_DIR=/opt/sunsetscan curl -fsSL https://raw.githubusercontent.com/NoCoderRandom/sunsetscan/main/bootstrap.sh | bash

A note on curl | bash: it's convenient but it does mean running a script you haven't read. If you'd rather inspect first, use option 3 or 4.

3. Clone and install

git clone https://github.com/NoCoderRandom/sunsetscan.git
cd sunsetscan
./install.sh

4. Manual install (full control, four commands)

sudo apt install -y nmap masscan git python3 python3-venv python3-pip libpcap-dev build-essential avahi-utils
git clone https://github.com/NoCoderRandom/sunsetscan.git && cd sunsetscan
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
./sunsetscan --version

(Substitute your distro's package manager for apt — dnf, pacman, zypper, or brew. The avahi package is avahi-tools on Fedora/RHEL, avahi on Arch, avahi-utils on openSUSE, and not needed on macOS.)

After installing — first run

./sunsetscan --setup                 # download EOL/CVE/credential databases (once)
sudo ./sunsetscan --instant          # ARP-only inventory of your local subnet
sudo ./sunsetscan --full-assessment --target 192.168.1.0/24

The ./sunsetscan launcher auto-activates the venv — you don't need to source venv/bin/activate ever. Use sudo for scans that need raw sockets, but run --setup, --download, and --update-cache as your normal user so cache files stay writable from the TUI.

Installer flags

Re-running ./install.sh is safe and idempotent — it detects existing components and reuses them.

Why a venv?

Modern Debian-based distributions (Debian Bookworm, Raspberry Pi OS Bookworm, Ubuntu 23.04+) ship with PEP 668 enforcement. This makes pip install fail when run as root against the system Python:

error: externally-managed-environment
× This environment is externally managed

Two of SunsetScan's dependencies (pysnmp v6 in particular) need newer versions than the apt repositories ship, so a pure-apt install isn't possible. The installer's solution is the standard one: install system tools (nmap, masscan, libpcap, avahi-utils) via apt, and put SunsetScan's Python dependencies in a project-local ./venv directory. Nothing system-wide is touched, so PEP 668 doesn't apply, and uninstalling SunsetScan is just rm -rf ~/sunsetscan.

Optional: keep SunsetScan running in the background

A full assessment of a /24 subnet on a Raspberry Pi can take 10–30 minutes. Use tmux or screen so the scan survives an SSH disconnect:

sudo apt install -y tmux
tmux new -s sunsetscan
sudo ./sunsetscan --full-assessment --target 192.168.1.0/24
# Ctrl+B then D to detach. "tmux attach -t sunsetscan" to come back later.

Updating SunsetScan

cd ~/sunsetscan
git pull
./install.sh                # idempotent — picks up any new dependencies

Uninstalling

rm -rf ~/sunsetscan
sudo rm -f /usr/local/bin/sunsetscan    # only if you used --symlink

WSL2 on Windows

Windows is not directly supported (SunsetScan needs raw sockets, /proc, and os.geteuid), but WSL2 works fine:

wsl --install -d Ubuntu     # in PowerShell, as Administrator

Restart, open Ubuntu from the Start menu, then follow the standard install above. WSL2 uses a virtual network adapter — pass your real subnet with --target if auto-detection picks the wrong one.

Requirements

Quick Start

# Interactive mode (recommended for first-time users)
sudo python3 sunsetscan.py -i

# Full security assessment with HTML report
sudo python3 sunsetscan.py --full-assessment --target 192.168.1.0/24

# Quick scan of your network
python3 sunsetscan.py --target 192.168.1.0/24

# IoT device scan (cameras, routers, smart devices)
python3 sunsetscan.py --target 192.168.1.0/24 --profile IOT

# Quick device inventory (no security checks)
python3 sunsetscan.py --identify --target 192.168.1.0/24

# Download all data modules for extended detection
python3 sunsetscan.py --download all

Features

Network Discovery

• Discovers all active hosts via fast ping sweep
• Resolves hostnames and detects MAC addresses with vendor/manufacturer lookup
• Flexible target input: CIDR, wildcard, IP range, comma-separated, or hostname
• Optional masscan integration for faster port discovery on large networks
• Hybrid scanning: passive background capture (mDNS/SSDP/DHCP) combined with active scanning

Port and Service Scanning

• Six scan profiles: QUICK, FULL, STEALTH, PING, IOT, SMB
• Full assessments discover active hosts first, then service-scan only those discovered hosts instead of blindly scanning every address in the target CIDR
• Concurrent banner grabbing across all open ports (50-thread pool)
• OS fingerprinting with confidence percentage
• NSE (Nmap Scripting Engine) integration for enhanced device detection
• HTTP fingerprinting to identify routers, cameras, NAS devices, printers, and IoT
• Automatic root-privilege fallback: FULL/STEALTH profiles gracefully degrade when run without sudo
• Safe mode for low-power hosts, Wi-Fi, WSL/NAT, and validation runs: caps workers, skips broad all-port masscan sweeps, bounds nmap port sets, and applies per-command scan timeouts
• Parallel security analysis — all per-host checks (SSL, SSH, FTP, SMB, SNMP, Web) run concurrently across hosts and within each host using thread pools
• Phase 7 security analysis completes in under 10 seconds regardless of network size
• Pre-scan readiness check — warns if nmap is missing, CVE/EOL databases are empty, or default modules are not installed. Runs before every scan, does not block scanning.

Security Checks

SunsetScan runs 12 security checker modules during a full assessment:

Vulnerability Intelligence

• CVE correlation — maps detected service versions to known CVEs using OSV.dev
• Software EOL checking — local cached lifecycle data for 150+ software products
• Hardware lifecycle checking — expanded SunsetScan hardware EOL database with 64,245 lifecycle records, 51,452 model summaries, and 122 represented vendors. It flags routers, switches, NAS, cameras, printers, access points, industrial/OT gear, and service-provider equipment with confirmed unsupported status or vendor lifecycle signals that need review.
• Smart hardware EOL profiles — home users get the smaller hardware-eol-home default profile, while office, enterprise, industrial, service-provider, and full profiles are available for broader scans.
• JA3S TLS fingerprinting — identifies server software from TLS handshake signatures
• Fully offline during scans — no external API calls are made during scanning. Software EOL, CVE, and GitHub module sources are only contacted by --setup, --update-cache, and --download. Scans work without any internet connection as long as caches are populated.
• Weekly CVE refresh, monthly EOL refresh — controlled by you

Device Identification

• 14 evidence extractors fuse MAC OUI, nmap OS, HTTP fingerprinting, TLS certificates, SSH banners, UPnP, SNMP sysDescr, Wappalyzer, mDNS, JA3S TLS fingerprints, FTP banners, port heuristics, and nmap service fields into a unified device identity per host
• Identifies vendor, model, firmware version, and device type with confidence scoring (agreement bonuses when multiple sources confirm)
• Supports 130+ vendor aliases for name normalization
• Results displayed in terminal table and HTML report device inventory
• Quick asset inventory mode: --identify flag skips security checks
• Persistent MAC-to-identity mapping across scans

Modular Data System

SunsetScan includes downloadable data modules and hardware EOL profiles that extend detection capabilities:

The hardware lifecycle database is now split into smart downloadable profiles: hardware-eol-home is the default install, while hardware-eol-full provides complete coverage. The full canonical build currently contains 64,245 records across 122 vendors, but home users only need the smaller home profile.

sunsetscan --modules                  # Show module status
sunsetscan --download all             # Download all modules, using the full hardware EOL smart profile
sunsetscan --download ja3-signatures  # Download one data module
sunsetscan --download hardware-eol-home  # Download a smaller hardware EOL profile
sunsetscan --download hardware-eol-full  # Download every hardware EOL smart pack

Rogue Device Detection

• Save a snapshot of your network as a trusted baseline
• Future scans automatically flag unknown MAC addresses not in the baseline
• Detects known devices on unexpected IP addresses

Risk Scoring

Every device receives a risk score (0-100) based on the severity and count of findings:

Reporting

• Professional HTML report — severity dashboard, per-host sections, finding cards with plain-English explanations, prioritised recommendations
• JSON export — machine-readable structured output
• Reports are fully self-contained — one HTML file, no external dependencies
• Narrow profiles such as SMB still keep discovered hosts visible in the report even when no matching service ports are open
• Network-level checks such as DNS, UPnP, and scan runtime notes are separated from per-device findings; device risk scores are only shown for actual hosts
• All findings colour-coded: Critical, High, Medium, Low, Info

Scan History and Diffing

• Every scan is automatically saved as a gzip-compressed JSON snapshot
• View past scans with --history
• Compare any two scans with --diff to see new hosts, closed ports, new/resolved findings
• Compare against a scan from N days ago with --diff --since N
• History retained for 90 days by default

User Interface

• Guided interactive mode (-i) — multi-level menus for scanning, analysis, export, modules
• Old-style menu — launches when run with no arguments
• Direct CLI mode — scriptable and automation-friendly
• Rich colour terminal output with progress bars, spinners, and summary panels

All CLI Flags

Scan Profiles

Tip: FULL and STEALTH automatically fall back to non-root flags when run without sudo. OS detection will be unavailable but port scanning and service detection still work.

Default Password Audit Safety

Default-password testing is never enabled automatically. In CLI mode, add --check-defaults; in guided -i mode, choose the default password audit when prompted. SunsetScan then applies a conservative policy:

• no generic username/password spraying by default
• only tests credentials that match the detected vendor and model/family
• skips devices with unique label/PIN defaults, such as many HP printers
• caps attempts to 2 per host and 1 per service by default
• waits 2 seconds between credential-bearing attempts
• stops immediately if a device returns lockout or rate-limit signals

The built-in database is intentionally small and source-backed. Downloaded large credential modules are retained as reference data, but the safe audit does not use them unless Settings.auth_allow_module_credentials is explicitly enabled by a developer.

Safe Mode and Validation Runs

Safe mode is automatically recommended on low-power hosts, hosts that look like Pi-hole/gateway appliances, and Wi-Fi egress. It can also be forced with:

python3 sunsetscan.py --full-assessment --target 192.168.1.0/24 --safe-mode

In safe mode SunsetScan:

• discovers live hosts first and scans only those hosts during full assessments
• applies the same safe scanner behavior from CLI, old menu, and guided -i mode
• removes OS fingerprinting from broad scans
• keeps broad STEALTH/FULL scans bounded with fast/top-port limits
• skips all-port masscan sweeps for broad profiles
• lowers worker counts and skips heavy TLS probes
• applies a per-nmap timeout so one profile cannot stall indefinitely

For root-assisted regression testing across all modes, use the validation collector:

sudo bash scripts/sudo_network_validation.sh

By default it tests 192.168.1.0/24 across PING, QUICK, SMB, STEALTH, and FULL, copies generated HTML reports into the validation directory, and writes a compressed archive under reports/. Reports, logs, pcaps, and archives are ignored by git and should not be committed.

Useful overrides:

sudo SUNSETSCAN_TARGETS="192.168.1.0/24" bash scripts/sudo_network_validation.sh
sudo SUNSETSCAN_PROFILES="PING QUICK FULL" bash scripts/sudo_network_validation.sh
sudo SUNSETSCAN_COMMAND_TIMEOUT=1200 bash scripts/sudo_network_validation.sh

Cache Management

SunsetScan never calls external APIs during a scan. All data is read from local cache files in data/cache/.

sunsetscan --cache-status     # See current cache state
sunsetscan --update-cache     # Refresh stale caches

Scans work normally with stale or missing cache — you just may have outdated CVE data.

Rogue Device Detection

# Step 1: Save baseline when all known devices are present
sudo python3 sunsetscan.py --target 192.168.1.0/24 --save-baseline

# Step 2: Future scans automatically compare against baseline
sudo python3 sunsetscan.py --target 192.168.1.0/24

Note: Baseline requires root/sudo for MAC address detection via nmap.

HTML Report

Every --full-assessment produces a self-contained HTML report with:

• Severity dashboard — badge counts (Critical/High/Medium/Low/Info), colour bar, summary statistics
• Risk scores — per-device 0-100 score with risk band label
• All findings table — every finding across all hosts, sorted by severity
• Per-host sections — collapsible section per device with finding cards, open ports table, EOL status
• Finding cards — severity badge, title, "What was found", "What this means" (plain English), "What to do" (numbered steps), evidence, CVE IDs
• Recommendations — prioritised action list

Reports open in any browser with no internet required.

Device Identification

SunsetScan automatically identifies network devices by combining evidence from 14 different sources. Each source contributes a vendor, model, version, or device type with a confidence score. The fusion algorithm sums agreeing sources (with bonuses for multi-source agreement) and penalizes conflicting evidence.

Quick Asset Inventory

To see what's on your network without running security checks:

python3 sunsetscan.py --identify --target 192.168.1.0/24

This runs a port scan with banner grabbing and prints a device identification table. No security analysis, no report — just a fast inventory.

Evidence Sources

Identification results appear in:

• Terminal device inventory table (during scan and via --identify)
• HTML report topology cards and device inventory section
• JSON export device_identities section
• Interactive mode menu option [8] Device Inventory

Severity Levels

Project Structure

sunsetscan/
├── sunsetscan.py                    # Entry point — CLI, scan pipeline, setup wizard
├── requirements.txt               # Python dependencies
├── install.sh                     # Automated installer for Linux/macOS
├── install.bat                    # Automated installer for Windows (basic)
├── README.md                      # This file
│
├── config/
│   └── settings.py                # All constants, timeouts, scan profiles, menu options
│
├── core/
│   ├── scanner.py                 # nmap wrapper (ScanResult, HostInfo, PortInfo)
│   ├── port_scanner.py            # Masscan pipeline + PortScanOrchestrator
│   ├── banner_grabber.py          # Concurrent raw socket banner grabbing
│   ├── http_fingerprinter.py      # HTTP device/firmware fingerprinting
│   ├── nse_scanner.py             # Nmap Scripting Engine integration
│   ├── auth_tester.py             # Default credential testing (HTTP, device-specific)
│   ├── input_parser.py            # Flexible target format parsing
│   ├── network_utils.py           # Subnet detection, IP helpers, WSL detection
│   ├── findings.py                # Finding dataclass, Severity enum, FindingRegistry
│   ├── risk_scorer.py             # Per-device risk scoring (0-100)
│   ├── cache_manager.py           # Unified CVE + EOL cache (data/cache/)
│   ├── cve_checker.py             # CVE lookup + CVECacheBuilder (OSV.dev)
│   ├── ssl_checker.py             # TLS certificate, cipher suite, JA3S fingerprinting
│   ├── ssh_checker.py             # SSH version, algorithms, KEXINIT analysis
│   ├── smb_checker.py             # SMBv1, EternalBlue, shares, NTLM disclosure
│   ├── ftp_checker.py             # Anonymous FTP, STARTTLS
│   ├── snmp_checker.py            # SNMP community strings, sysDescr (pysnmp v4+v7)
│   ├── web_checker.py             # HTTP headers, admin panels, Wappalyzer
│   ├── dns_checker.py             # DNS hijack and rebinding detection
│   ├── upnp_checker.py            # SSDP discovery, UPnP risk assessment
│   ├── mdns_checker.py            # mDNS/Zeroconf device discovery
│   ├── arp_checker.py             # ARP spoofing detection
│   ├── device_identifier.py       # 14-source device identification engine
│   ├── identity_fusion.py         # Multi-source identity fusion and scoring
│   ├── oui_lookup.py              # IEEE OUI MAC vendor resolution
│   ├── device_map.py              # Persistent MAC→identity mapping
│   ├── passive_sniffer.py         # Background mDNS/SSDP/DHCP packet capture
│   ├── packet_parsers.py          # Protocol-specific packet parsing
│   ├── instant_scan.py            # ARP sweep + passive capture quick scan
│   ├── hybrid_scanner.py          # Passive+active scan orchestrator
│   ├── baseline.py                # Rogue device baseline comparison
│   ├── hardware_eol.py            # Downloaded hardware lifecycle database lookup
│   ├── scan_history.py            # Scan snapshot persistence and diffing
│   ├── module_manager.py          # Downloadable data module system
│   └── update_manager.py          # Version check and self-update
│
├── eol/
│   ├── checker.py                 # EOL API queries and version comparison
│   ├── cache.py                   # Per-product JSON cache
│   └── product_map.py             # 150+ software name -> lifecycle cache slug mappings
│
├── ui/
│   ├── menu.py                    # Old-style numbered menu (no-args mode)
│   ├── display.py                 # Rich terminal tables, progress bars, banners
│   ├── export.py                  # JSON and HTML report generation
│   ├── interactive_controller.py  # Interactive mode (-i) with multi-level menus
│   └── templates/
│       └── report.html.j2         # Jinja2 HTML report template
│
└── data/
    ├── default_credentials.json   # Factory-default credentials database
    ├── device_map.json            # Persistent MAC→identity map
    ├── baseline.json              # Saved device baseline (--save-baseline)
    ├── cache/
    │   ├── cve_cache.json         # CVE data keyed by product:version
    │   ├── <product>.json         # EOL data keyed by product slug
    │   ├── hardware_eol/          # Downloaded hardware lifecycle database
    │   └── cache_meta.json        # Cache update timestamps
    ├── history/                   # Gzip scan snapshots (auto-saved)
    └── modules/                   # Downloaded data modules

Troubleshooting

nmap not found

# Debian/Ubuntu
sudo apt install nmap

# Fedora
sudo dnf install nmap

# Arch
sudo pacman -S nmap

# macOS
brew install nmap

Permission denied / OS detection not working

FULL, STEALTH, and SMB profiles require elevated privileges. Without root, these profiles automatically fall back to non-root flags (OS detection and SYN scan disabled, but port/version scanning still works).

# For full capabilities:
sudo python3 sunsetscan.py --target 192.168.1.0/24 --profile FULL

WSL2 suggests wrong network (172.x.x.x)

On WSL2, SunsetScan detects the virtual adapter and falls back to 192.168.1.0/24. If your home network uses a different subnet, specify it with --target:

python3 sunsetscan.py --target 192.168.0.0/24

Cache warnings at scan start

WARNING: CVE data is 12 days old — run: python sunsetscan.py --update-cache

Scans work fine with stale data. Run --update-cache to refresh.

Permission denied while downloading modules

If module downloads fail with Permission denied: .../data/cache/..., the cache was probably created by sudo. Fix the ownership once, then run setup and module downloads as your normal user:

cd ~/sunsetscan
sudo chown -R "$USER:$USER" data/cache
./sunsetscan --download all

SNMP checks not working

SunsetScan supports both pysnmp v4 (synchronous) and v7 (async). If you see import errors, update pysnmp:

pip install --upgrade pysnmp

Disclaimer — Authorised Use Only

SunsetScan is a security auditing tool intended for use on networks and devices that you own or have explicit written permission to test.

Running network scans against systems you do not own or have authorisation to test may be illegal regardless of intent. The authors accept no liability for misuse.

SunsetScan is entirely non-destructive and read-only. It does not exploit vulnerabilities, deliver payloads, or modify any configuration on any scanned device. The --check-defaults credential testing is opt-in, bounded, delayed, exact-model oriented, and stops on lockout/rate-limit signals; it is not a brute-force feature.

License

The SunsetScan repository and application code are licensed under the MIT License — Copyright 2024 SunsetScan Contributors.

Only the SunsetScan hardware EOL database artifacts under data/hardware_eol/ are licensed separately: This database is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0). See data/hardware_eol/LICENSE.md.

Acknowledgements

• nmap — scanning engine
• python-nmap — Python nmap interface
• OSV.dev — vulnerability database
• Rich — terminal formatting
• Jinja2 — HTML report templating
• cryptography — TLS certificate inspection
• scapy — raw packet capture and ARP scanning
• danielmiessler/SecLists — credential and SNMP lists
• ihebski/DefaultCreds-cheat-sheet — vendor credentials
• enthec/webappanalyzer — web technology detection
• salesforce/ja3 — TLS fingerprinting
• many-passwords — camera/DVR credentials