Private Network Security Scan

一個可由 AI Agent 執行的完整私有網路安全掃描技能。使用 scan_private_network 腳本作為核心，在 60 分鐘內完成網路發現、逐台主機 11 類風險診斷、以及報告產出。

[!IMPORTANT] 此工作流程會在本機執行 nmap（需要 sudo 才能做 OS detection）以及 traceroute，會產生實際的網路流量。請確認這在你的網路環境中是被允許的。

[!WARNING] Token Limit Fallback 策略：如果主模型觸發 token limit，Agent 會切換至 fallback 模型繼續工作。若兩個模型都耗盡，Agent 會直接依據已收集的資料產出報告，跳過未完成的診斷步驟。

依賴工具 (Required Tools)

報告輸出結構 (Output Structure)

/Users/shuk/projects/security/scan/<YYYYMMDD>-<scan_type>/
├── report.md      # 主報告（依 resources/report_template.md 產出）
└── network.topo   # 拓撲備份

命名規則 (Naming Convention)

範例：scan/20260216-private-network/report.md

工作流程 (Workflow)

flowchart TD
    A["Phase 0: Pre-flight Check<br/>(~2 min)"] --> B["Phase 1: Network Discovery<br/>(~10 min)"]
    B --> C["Phase 2: Per-Host Diagnosis<br/>(~35 min)"]
    C --> D["Phase 3: Report Generation<br/>(~10 min)"]
    D --> E["Phase 4: Delivery<br/>(~3 min)"]

    C -- "token limit error" --> F["Switch to Fallback Model"]
    F --> C
    F -- "both models exhausted" --> D

時間預算 (Time Budget)

共 60 分鐘

Phase 0: Pre-flight Check (~2 min)

// turbo

1. Check that nmap is installed:

which nmap

// turbo 2. Check that traceroute is installed:

which traceroute

// turbo 3. Record the scan start time and set variables:

SCAN_DATE=$(date '+%Y%m%d')
SCAN_START=$(date '+%Y-%m-%d %H:%M:%S')
echo "SCAN_DATE=${SCAN_DATE}" | tee /tmp/scan_meta.env
echo "SCAN_START=${SCAN_START}" >> /tmp/scan_meta.env

// turbo 4. Create the scan output directory and copy report template:

source /tmp/scan_meta.env
SKILL_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$HOME/.agent/skill/private-network-scan")")"
SCAN_DIR="/Users/shuk/projects/security/scan/${SCAN_DATE}-private-network"
echo "SCAN_DIR=${SCAN_DIR}" >> /tmp/scan_meta.env
mkdir -p "${SCAN_DIR}"
cp "${SKILL_DIR}/resources/report_template.md" "${SCAN_DIR}/report.md"

Phase 1: Network Discovery (~10 min)

5. Run the scan_private_network script to build the network topology:

cd /Users/shuk/projects/env_setup && sudo bin/scan_private_network

Wait for completion. The script outputs results to network.topo in the current directory.

// turbo 6. Read the generated topology file:

cat /Users/shuk/projects/env_setup/network.topo

7. Parse the topology output and build a target list of all discovered hosts:
   • Extract every IP address found in the topology
   • Note which ports/services are already identified
   • Prioritize hosts that have open services (they are more interesting for security analysis)
   • Record the network layers/subnets discovered

Phase 2: Per-Host Security Diagnosis (~35 min)

For each host discovered in Phase 1, perform the following checks. Work through hosts in order of priority (hosts with open services first).

Token Limit Fallback Strategy:

• If the PRIMARY model hits a token limit error → switch to the FALLBACK model and continue from where you left off
• If the FALLBACK model also hits a token limit → SKIP remaining hosts and jump to Phase 3 immediately
• In the report, mark hosts as “✅ Diagnosed” or “⏭️ Skipped (token limit)” accordingly

2.1 Port Risk Assessment (風險類別 1: 連接埠暴露)

For each host, categorize open ports by risk level per §1 below:

2.2 Service Version Vulnerability Check (風險類別 2: 軟體版本漏洞)

Compare discovered service versions against known vulnerability patterns per §2 below:

• Boa HTTPd (any version) — EOL project, multiple CVEs → 🔴
• OpenSSH < 9.0 — check for known CVEs → 🟠
• nginx — check version if available → 🟡
• CUPS — check for recent CVEs → 🟡
• Any EOL software → 🔴

2.3 HTTP Service Security Headers (風險類別 3: HTTP 安全標頭)

For hosts with HTTP services (port 80, 443, 8080), check security headers:

// turbo

curl -sI --connect-timeout 5 http://<IP>:<PORT> 2>/dev/null | head -20

Check for presence/absence of:

• X-Frame-Options → missing = 🟡
• Content-Security-Policy → missing = 🟡
• Strict-Transport-Security → missing = 🟡
• X-Content-Type-Options → missing = 🟡
• Server header leaking version → 🟢

2.4 Authentication & Access Control (風險類別 4: 認證與存取控制)

Check for common authentication weaknesses:

• Default credentials on routers/IoT/databases → 🔴
• Anonymous FTP access: nmap --script ftp-anon -p 21 <IP> → 🔴
• Redis/MongoDB without auth: redis-cli -h <IP> ping → 🔴
• SMB null session: nmap --script smb-enum-shares -p 445 <IP> → 🟠
• SNMP default community strings: nmap --script snmp-brute -p 161 <IP> → 🟠

2.5 Encryption & Transport Security (風險類別 5: 加密與傳輸安全)

2.5.1 SSH Configuration Check

For hosts with SSH service (port 22):

// turbo

ssh-keyscan -T 5 <IP> 2>/dev/null

Check:

• Key types offered (RSA, ECDSA, ED25519)
• Whether weak key types are present (DSA, RSA < 2048-bit) → 🟡

2.5.2 TLS/SSL Check

For hosts with HTTPS (port 443):

// turbo

nmap --script ssl-enum-ciphers -p 443 <IP>

Check:

• Weak cipher suites (SSLv3, TLS 1.0/1.1, RC4, DES) → 🟠
• Expired / self-signed certificates → 🟠

2.6 DNS Security Check (風險類別 6: DNS 安全)

For hosts with DNS service (port 53):

// turbo

dig axfr @<IP> 2>/dev/null | head -50

• If zone transfer succeeds → 🔴 Critical
• Check if open resolver: dig @<IP> example.com from non-local → 🟠

2.7 Network-Level Attack Surface (風險類別 7: 網路層攻擊面)

Review the network topology for:

• UPnP / SSDP services (port 1900): nmap --script upnp-info -p 1900 <IP> → 🟡
• IPv6 enabled but unmonitored → 🟡
• ARP / VLAN / LLMNR observations from topology → 🟠

2.8 Web Application Security (風險類別 8: Web 應用安全)

For hosts with HTTP/HTTPS services:

• Check for exposed admin interfaces (/admin, /login, /management) → 🟠
• Check directory listing: curl -s http://<IP>/ → 🟡
• Check WebDAV: nmap --script http-webdav-scan -p 80,443 <IP> → 🟠

2.9 Data Leakage (風險類別 9: 資料洩漏)

• NFS exports: showmount -e <IP> → 🟠 if misconfigured
• SMB shares: smbclient -L <IP> -N → 🟠 if anonymous accessible
• mDNS / Bonjour broadcasting → 🟢

2.10 Lateral Movement (風險類別 10: 橫向移動)

Assess from network topology:

• Flat network / no VLAN segmentation → 🟠
• Shared credentials across hosts → 🟠
• SSH key trust / .rhosts → 🟡

2.11 IoT & Embedded Devices (風險類別 11: IoT / 嵌入式裝置)

For identified IoT/embedded devices:

• Check firmware version against known updates → 🟠
• Scan for hidden debug ports on non-standard ports → 🔴
• UPnP auto-exposing services → 🟡

2.12 Quick Vulnerability Scan (if time permits)

If more than 15 minutes remain in the time budget, run nmap vuln scripts on high-value targets:

nmap --script vulners -sV -p <open_ports> <IP> --host-timeout 60s

Phase 3: Report Generation (~10 min)

8. Read the report template that was copied in Phase 0:

source /tmp/scan_meta.env
cat "${SCAN_DIR}/report.md"

9. Fill in the report template (<!-- --> placeholders) with all findings from Phase 2:

   • Executive Summary: host count, service count, risk distribution
   • Network Topology: embed network.topo content
   • Findings by severity: Critical/High → Medium → Low/Info
   • Per-Host Detail: each host’s full 11-category diagnosis
   • Scan Limitations: skipped hosts, timed-out checks
   • Recommendations: prioritized remediation steps
   • Appendices: raw topology, command log

   Each finding must include:

   • Risk category number (1-11)
   • Severity level (🔴🟠🟡🟢ℹ️)
   • Evidence (raw command output)
   • Remediation steps

10. Write the completed report to ${SCAN_DIR}/report.md.

Phase 4: Delivery (~3 min)

// turbo 11. Copy the topology file as a dated backup:

source /tmp/scan_meta.env
cp /Users/shuk/projects/env_setup/network.topo "${SCAN_DIR}/network.topo"

12. Record scan end time:

source /tmp/scan_meta.env
SCAN_END=$(date '+%Y-%m-%d %H:%M:%S')
echo "Scan started: ${SCAN_START}"
echo "Scan ended:   ${SCAN_END}"

13. Notify the user that the report is complete, include:
    • Path to the report file (${SCAN_DIR}/report.md)
    • Top 3 most critical findings (if any)
    • Number of hosts scanned vs skipped
    • Total scan duration

// turbo 14. Clean up temp files:

rm -f /tmp/scan_meta.env

風險等級定義 (Risk Severity Levels)

風險類別詳細規則 (Risk Category Rules)

§1 連接埠暴露 (Port Exposure)

依開放埠號的協議特性進行風險分級。

§2 軟體版本漏洞 (Service Version Vulnerabilities)

比對服務版本與已知 CVE。

§3 HTTP 安全標頭 (HTTP Security Headers)

針對 HTTP 服務（Port 80/443/8080）檢查防護標頭是否存在。

§4 認證與存取控制 (Authentication & Access Control)

§5 加密與傳輸安全 (Encryption & Transport Security)

§6 DNS 安全 (DNS Security)

§7 網路層攻擊面 (Network-Level Attack Surface)

§8 Web 應用安全 (Web Application Security)

§9 資料洩漏 (Data Leakage)

§10 橫向移動 (Lateral Movement)

§11 IoT / 嵌入式裝置 (IoT & Embedded Devices)