02 · 入口与 CLI#

parser = argparse.ArgumentParser(add_help=False)
group.add_argument("-h", dest="help", nargs="?", const="flag", default=None, help="帮助")

group.add_argument("-u", metavar="target", nargs="?", const="__flag__", default=None, help="综合扫描")

force_utf8_stdio()                     # Windows ANSI 代码页兜底，避免中文乱码
        ↓
setup_logging(debug=args.debug)        # 默认 WARNING 静默，--debug 开 DEBUG 到 stderr
        ↓
if args.verify_tls: settings.VERIFY_TLS = True   # 写入全局 settings（与 core/session 同一事实来源）
        ↓
print_banner()
        ↓
if args.config:  load_yaml_config → normalize_config_keys → apply_config_to_args
                 （仅在命令行未显式给 -u/-m/-p/-l 时，才用 YAML 的 mode/target 回填）
        ↓
if args.template:  apply_template(args, template)   # D19 扫描模板
        ↓
has_mode = any([...28 个可执行模式...])
        ↓
if args.help is not None or not has_mode:  print_help(); return
        ↓
from cli.dispatcher import dispatch;  dispatch(args)

ok, reason = probe_reachable(target)          # TCP 层：秒级判定端口是否可连
if not ok: return False
ok, reason = probe_http_responsive(target)    # HTTP 层：端口通但服务不回数据

dispatch(args)
│
├─【第一段：纯工具模式（不扫描，立即 return）】
│   --diff-only → --template-list → --plugin-new → --plugin-init → --plugin-check
│   → --plugin-list → --ci-init → --wiki → --oast-server → --cve-sync/--cve-id/--cve-offline
│   → --web-ui → --cache-stats → --cache-clear → --nuclei-validate
│   → --plugin-export → --plugin-manifest → --plugin-update
│   → --ai-validate <path>（sys.exit(返回码)）
│   → --ai-triage 守卫（无扫描模式则报错返回）
│   → --ai
│
├─【第二段：独立进程模式（自己占住终端/端口）】
│   --serve → --chain-list / --chain list → --chain <name> → --passive
│
└─【第三段：标准扫描模式】
    ├─ -f <file>：需配合 -u/-m/-p/-l 开关指定扫描类型 → run_mode_batch()
    ├─ 单目标：按 u → m → p → l 取第一个有效目标
    │           preflight_target() 失败 → sys.exit(EXIT_UNREACHABLE)
    │           成功 → run_mode(k, target, args)
    └─ final_prompt()   # 收尾提示

if args.file:
    mode = None
    for k in ("u", "m", "p", "l"):
        if k in flag_for:      # flag_for 只收 value == "__flag__" 的键
            mode = k
            break
    if not mode:
        print("[-f 批量扫描需配合 -u/-m/-p/-l 指定扫描模式]")
        return

run_mode(mode, target, args, show_cta=True)
│
├─ 1. _build_scan_request(mode, target, args)   # 把 Namespace 收敛成 ScanRequest
│       └─ D26 认证三来源合并（--auth / --auth-file / --auth-login → auto_login）
├─ 2. ScanOrchestrator().run_sync(request)      # ← 进入 core 层（见 03 章）
├─ 3. 报告后处理链（顺序敏感）：
│       report_template（G5 模板渲染）
│       → remediation（G5 整改复测对比）
│       → ai_triage（G3 UNKNOWN 聚类降噪）
│       → save_baseline（D20 存基线）
│       → diff（D20 与历史对比）
│       → notify（D21 通知推送）
│       → ai_report（E8 AI 摘要）
│       → logic_scan / auth_surface / siem_export / ci
└─ 4. print_star_cta()（除非 --no-cta）

MODE_CATEGORIES = {
    "u": ["recon", "vuln", "brute"],   # 综合
    "m": ["recon"],                    # 目录扫描
    "p": ["vuln"],                     # 漏洞检测
    "l": ["brute"],                    # 登录爆破
}

# 从源码（开发）
pip install -e ".[dev]"

# 最小运行（仅 CLI 扫描）
pip install -e .

# 按需装可选依赖组
pip install -e ".[report]"      # pdf/docx/xlsx 报告
pip install -e ".[serve]"       # FastAPI Web 服务
pip install -e ".[distributed]" # Redis 分布式
pip install -e ".[all]"         # 全量

python main.py -u http://target:8080        # 综合（recon + vuln + brute）
python main.py -m http://target:8080        # 目录扫描（recon）
python main.py -p http://target:8080        # 漏洞检测（vuln）
python main.py -l http://target:8080        # 登录爆破（brute）

python main.py -f targets.txt -p            # 批量（必须带模式开关）

# 带报告与并发
python main.py -u http://t:8080 --threads 10 --rate 20 --report ./out --report-format all

# 指定 CMS 跳过指纹识别 + 端口扫描
python main.py -p http://t:8080 --cms ruoyi --portscan --ports 8080,8848,6379

# WAF 场景
python main.py -u http://t:8080 --bypass-waf on

# 认证后深度扫描（G1 越权矩阵）
python main.py -p http://t:8080 --auth-login admin:admin123 \
    --auth-surface --surface-account user:user123 --surface-output assets.json

# CI 集成（退出码驱动）
python main.py -p http://t:8080 --ci --severity-threshold high

# 漏洞利用链
python main.py --chain-list                        # 列出可用链
python main.py --chain ruoyi_sql_to_rce -u http://t:8080   # 执行指定链

# Web API 服务
python main.py --serve --host 0.0.0.0 --port 8000 \
    --api-key "key1:read,key2:scan,key3:admin"

# 定时扫描
python main.py --serve --schedule "0 2 * * *" --schedule-target http://t:8080

# 配置文件驱动
python main.py --config scan.yaml
python main.py --template deep -u http://t:8080

pytest                    # 默认 -q --timeout=30 --timeout-method=thread
ruff check .
mypy                      # common.*/core.* 走 strict；lib.*/api.* 被 ignore