#### 2. 一行引导

将仓库克隆到 `~/sunsetscan` 并运行安装程序：```bash
curl -fsSL https://raw.githubusercontent.com/NoCoderRandom/sunsetscan/main/bootstrap.sh | bash

> **关于 `curl | bash` 的说明**：它很方便，但确实意味着你正在运行一个你没有读过的脚本。如果你想先检查一下，请使用选项3或4。

#### 3. 克隆并安装```bash
git clone https://github.com/NoCoderRandom/sunsetscan.git
cd sunsetscan
./install.sh

(用你的发行版的包管理器替换 `apt` —— `dnf`、`pacman`、`zypper` 或 `brew`。Avahi 包在 Fedora/RHEL 上是 `avahi-tools`，在 Arch 上是 `avahi`，在 openSUSE 上是 `avahi-utils`，在 macOS 上则不需要。)

### 安装后 — 首次运行```bash
./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

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`.

### 可选：让 SunsetScan 在后台持续运行

在 Raspberry Pi 上对 /24 子网进行全面评估可能需要 10–30 分钟。使用 `tmux` 或 `screen` 以确保扫描在 SSH 断开后继续运行：```bash
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.

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

重启，从“开始”菜单打开 **Ubuntu**，然后按照上面的标准安装步骤操作。WSL2 使用虚拟网络适配器 —— 如果自动检测选择了错误的子网，请使用 `--target` 传递您的真实子网。

---

## 要求

| 要求 | 最低版本 | 备注 |
|---|---|---|
| **Python** | 3.9+ | 推荐 3.12 |
| **nmap** | 任意较新版本 | 必须在系统 PATH 中 |
| **OS** | Linux（原生或 WSL2） | 请参阅 [平台支持](#platform-support) |
| **masscan** | 任意版本 | 可选 — 更快的端口发现 |
| **avahi-utils** | 任意版本 | 可选 — 提供 `avahi-browse`，用于可靠地发现 Apple / Bonjour / Sleep-Proxy 设备的 mDNS。若不存在，则回退到 Python 的 `zeroconf`。 |
| **git** | 任意版本 | 可选 — 用于 `--setup` 和 `--update` |
| **权限** | 普通用户 | FULL、STEALTH、SMB 配置文件、ARP 检测和被动捕获需要 root/sudo |

---

## 快速开始```bash
# 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

### 未授权设备检测
- 保存网络快照作为可信基线
- 后续扫描自动标记不在基线中的未知 MAC 地址
- 检测到已知设备出现在意外 IP 地址上

### 风险评分
每台设备根据发现项的严重程度和数量获得一个风险分数（0-100）：

| 分数 | 等级 |
|---|---|
| 0-10 | 最低风险 |
| 11-30 | 低风险 |
| 31-60 | 中等风险 |
| 61-80 | 高风险 |
| 81-100 | 严重风险 |

### 报告
- **专业 HTML 报告** — 严重程度仪表盘、每个主机分区、带有通俗解释的发现卡片、按优先级排序的建议
- **JSON 导出** — 机器可读的结构化输出
- 报告完全自包含 — 单个 HTML 文件，无需外部依赖
- 即使没有匹配的服务端口开放，像 SMB 这样的窄配置文件仍会在报告中保持已发现主机的可见性
- 网络级别检查（如 DNS、UPnP 和扫描运行时备注）与每台设备的发现项分开；设备风险评分仅针对实际主机显示
- 所有发现项按颜色区分：严重、高、中、低、信息

### 扫描历史与差异对比
- 每次扫描自动保存为 gzip 压缩的 JSON 快照
- 使用 `--history` 查看过去的扫描
- 使用 `--diff` 比较任意两次扫描，查看新增主机、关闭端口、新增/已解决的发现项
- 使用 `--diff --since N` 与 N 天前的扫描进行比较
- 默认保留 90 天的历史记录

### 用户界面
- 引导式**交互模式**（`-i`） — 用于扫描、分析、导出、模块的多级菜单
- **旧式菜单** — 无参数运行时启动
- 直接 CLI 模式 — 可脚本化，适合自动化
- 丰富的彩色终端输出，带有进度条、旋转器和摘要面板

---

## 所有 CLI 标志

| 标志 | 描述 | 需要 Root |
|---|---|---|
| `--target TARGET` | IP、CIDR 范围、主机名或要扫描的范围 | 否 |
| `--profile PROFILE` | 扫描配置文件：QUICK、FULL、STEALTH、PING、IOT、SMB（默认：QUICK） | 视情况而定 |
| `-i`, `--interactive` | 启动引导式交互模式 | 否 |
| `--full-assessment` | 完整评估 + 自动 HTML 导出；凭据审计保持选择加入 | 否 |
| `--identify` | 仅运行设备识别（跳过安全检查） | 否 |
| `--nse` | 启用 Nmap 脚本引擎以增强检测 | 否 |
| `--check-defaults` | 选择加入锁定安全的出厂默认凭据审计（仅限自有设备） | 否 |
| `--save-baseline` | 将扫描保存为用于未授权设备检测的可信设备基线 | 否 |
| `--setup` | 首次设置向导（依赖项 + 缓存下载） | 否 |
| `--update-cache` | 手动刷新 CVE 和 EOL 数据缓存 | 否 |
| `--cache-status` | 显示缓存时间和条目数量，然后退出 | 否 |
| `--modules` | 显示所有可下载数据模块的状态 | 否 |
| `--download MODULE` | 下载一个数据模块（或 "all"） | 否 |
| `--db SIZE` | `--setup` 的 EOL 数据库大小：mini、normal、large（默认：normal） | 否 |
| `--history` | 显示扫描历史表格并退出 | 否 |
| `--diff` | 差异对比最近两次保存的扫描并退出 | 否 |
| `--since DAYS` | 与 `--diff` 结合：与至少 N 天前的扫描进行比较 | 否 |
| `--check-version` | 检查 GitHub 上更新的 SunsetScan 版本 | 否 |
| `--update` | 从 GitHub 拉取最新代码并重新安装依赖 | 否 |
| `--verbose` | 启用调试日志 | 否 |
| `--no-color` | 禁用彩色输出（适用于日志文件） | 否 |
| `--quiet` | 抑制进度条（仍显示发现项） | 否 |
| `--safe-mode` | 强制更温和的扫描：限制 nmap、降低 masscan 使用、更少 worker、跳过重探测 | 否 |
| `--no-safe-mode` | 禁用自动安全模式 | 否 |
| `--version` | 显示版本号并退出 | 否 |

---

## 扫描配置文件

| 配置文件 | nmap 标志 | 速度 | 需要 Root | 最佳用途 |
|---|---|---|---|---|
| **PING** | `-sn` | ~30秒 | 否 | 快速发现活动设备 |
| **QUICK** | `-T4 -F -sV --version-intensity 2` | 1-3分钟 | 否 | 快速查看网络（带轻量版本检测） |
| **FULL** | `-T4 -A -sV -O --osscan-guess` | 5-15分钟 | 是 | 深入分析特定主机 |
| **STEALTH** | `-sS -T2 -sV` | 10-30分钟 | 是 | 低噪声扫描 |
| **IOT** | `-T4 -sV -p 23,80,443,8080,8443,554,1900,5000,5001,7547,49152 --open` | 1-3分钟 | 否 | 摄像头、路由器、智能设备 |
| **SMB** | `-T4 -sV -p 135,139,445,137,138 --script smb-security-mode,smb2-security-mode,smb-vuln-ms17-010 --open` | 1-3分钟 | 是 | Windows 共享、EternalBlue 检查 |

> **提示：** 未使用 sudo 运行时，FULL 和 STEALTH 会自动回退到非 root 标志。操作系统检测将不可用，但端口扫描和服务检测仍然有效。

### 默认密码审计安全

默认密码测试永远不会自动启用。在 CLI 模式下，添加 `--check-defaults`；在引导式 `-i` 模式下，在提示时选择默认密码审计。SunsetScan 随后应用保守策略：

- 默认不进行通用用户名/密码喷洒
- 仅测试与检测到的厂商和型号/系列匹配的凭据
- 跳过具有唯一标签/PIN 默认值的设备，例如许多 HP 打印机
- 默认限制每个主机 2 次尝试，每个服务 1 次尝试
- 在凭据尝试之间等待 2 秒
- 如果设备返回锁定或速率限制信号，则立即停止

内置数据库故意较小且基于源文件。下载的大型凭据模块作为参考数据保留，但安全审计不会使用它们，除非开发者显式启用 `Settings.auth_allow_module_credentials`。

### 安全模式与验证运行

安全模式会自动推荐给低功耗主机、看起来像 Pi-hole/网关设备的主机以及 Wi-Fi 出口主机。也可以使用以下命令强制启用：```bash
python3 sunsetscan.py --full-assessment --target 192.168.1.0/24 --safe-mode

默认情况下，它对 `192.168.1.0/24` 进行 PING、QUICK、SMB、STEALTH 和 FULL 扫描，将生成的 HTML 报告复制到验证目录中，并将压缩归档写入 `reports/` 下。报告、日志、pcap 文件和归档被 git 忽略，不应被提交。

有用的覆盖项：```bash
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

扫描在缓存过期或缺失时仍可正常运行——只是CVE数据可能已过时。

---

## 流氓设备检测```bash
# 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

这会执行端口扫描并抓取横幅，打印设备识别表。无需安全分析，无需报告——仅快速盘点。

### 证据来源

| 来源 | 读取内容 | 置信度 |
|--------|--------------|------------|
| MAC OUI | 来自 MAC 地址的 IEEE 厂商前缀 | 0.40-0.45 |
| nmap OS | OS 指纹猜测 | 不固定 |
| HTTP 指纹 | 来自 Web UI 的设备类型、型号、固件 | 0.50+ |
| HTTP 头 | Server、X-Powered-By 响应头 | 0.20-0.50 |
| TLS 证书 | CN、颁发者、组织字段 | 0.35 |
| SSH 横幅 | SSH 守护进程识别字符串 | 0.10-0.70 |
| UPnP | SSDP 制造商、型号、设备类型 | 0.75 |
| SNMP sysDescr | 来自 SNMP MIB 的系统描述 | 0.85 |
| Wappalyzer | CPE 字符串和技术类别 | 0.30-0.45 |
| mDNS/Zeroconf | 服务类型广播 | 0.55 |
| JA3S | TLS 握手指纹数据库 | 0.50 |
| FTP 横幅 | FTP 服务器软件识别 | 0.25-0.35 |
| 端口启发式 | 开放端口组合模式 | 0.10-0.70 |
| nmap 服务 | 服务产品和版本字段 | 0.45 |

识别结果出现在：
- 终端设备清单表（扫描期间及通过 `--identify`）
- HTML 报告拓扑卡及设备清单部分
- JSON 导出中的 `device_identities` 部分
- 交互模式菜单选项 [8] 设备清单

---

## 严重性等级

| 等级 | 颜色 | CVSS 范围 | 含义 | 行动时机 |
|---|---|---|---|---|
| **严重** | 红色 | >= 9.0 | 默认凭据、可被利用的 CVE、SSL 2.0 | 今日 |
| **高** | 橙色 | 7.0-8.9 | Telnet/FTP 开放、证书过期、TLS 1.0、软件终止支持 | 本周内 |
| **中** | 黄色 | 4.0-6.9 | 自签名证书、UPnP 暴露、流氓设备、缺少 HSTS | 安排修复 |
| **低** | 蓝色 | < 4.0 | 即将停止支持、缺少 X-Frame-Options、设备 IP 变更 | 跟踪并规划 |
| **信息** | 灰色 | - | 设备已识别、证书详情、DNS 检查通过 | 无需操作 |

---

## 项目结构```
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

**权限被拒绝 / 操作系统检测无法工作**

FULL、STEALTH 和 SMB 配置文件需要提升的权限。没有 root 权限，这些配置文件会自动回退到非 root 标志（禁用操作系统检测和 SYN 扫描，但端口/版本扫描仍然有效）。```bash
# For full capabilities:
sudo python3 sunsetscan.py --target 192.168.1.0/24 --profile FULL

**扫描开始时的缓存警告**```
WARNING: CVE data is 12 days old — run: python sunsetscan.py --update-cache

**SNMP检查不工作**

SunsetScan 同时支持 pysnmp v4（同步）和 v7（异步）。如果你看到导入错误，请更新 pysnmp：```bash
pip install --upgrade pysnmp