kiroro123/netshapper

# NetShaper NetShaper 是一个模块化的、授权的网络测试工具包，用于受控实验室和客户端网络分析。它将网络发现、数据包捕获、DNS 处理、流量整形和 MITM 风格的拦截结合在一个 Python CLI 中。 **请仅在您拥有或获得明确书面测试许可的网络和设备上使用。** ## 架构 NetShaper 被组织为可独立审计的组件： ``` ┌─────────────────────────────────────────────────────────────────┐ │ CLI Entry Point │ │ (src/netshaper/ui/cli.py) │ └─────────────────────┬───────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ │ │ │ ▼ ▼ ▼ ┌────────┐ ┌────────────┐ ┌──────────┐ │Discovery│ │Authorization│ │Firewall │ │ │ │ Policy │ │Manager │ │ ARP/NDP │ │ │ │ │ │ sweep │ │ CIDR checks │ │ iptables │ │ hostname│ │ │ │ nat/mgle │ └────────┘ └────────────┘ └──────────┘ │ │ │ └───────────────┼───────────────┘ │ ┌───────────────┼───────────────┬──────────────┐ │ │ │ │ ▼ ▼ ▼ ▼ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Traffic│ │ Packet │ │ mitmproxy│ │ Stale │ │ Shaper│ │ Sniffer │ │ Manager │ │ Recovery │ │(tc HTB)│ │ │ │ │ │ Manager │ │ │ │ .pcap │ │ HTTPS │ │ │ │ │ │ capture │ │ intercept│ │ Cleanup │ └────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ └───────────────┼───────────────┴──────────────┘ │ ▼ ┌─────────────────────────────┐ │ State Persistence Layer │ │ /run/netshaper/state.json │ └─────────────────────────────┘ ``` ## 组件职责 | 模块 | 用途 | 审计面 | |--------|---------|---| | **AuthorizationPolicy** | 根据授权的 CIDR 允许列表验证目标 IP | IP 验证、边界检查 | | **FirewallManager** | 管理用于转发和针对特定目标拦截的 iptables/ip6tables 规则 | 防火墙规则构建、清理 | | **MitmProxyManager** | 以透明模式启动、监控并终止 mitmproxy | 进程生命周期、端口绑定 | | **RecoveryManager** | 检测并清理崩溃会话遗留的孤立规则 | 失效会话检测、原子清理 | | **TargetSession** | 针对特定目标的拦截（ARP 欺骗、DNS 重定向、防火墙规则） | 单目标规则作用域、隔离 | | **TrafficShaper** | 基于 Linux `tc` 的 HTB qdisc 带宽限速 | Qdisc 生命周期、速率限制 | | **PacketSniffer** | 使用 libpcap 捕获数据包至 .pcap | 数据包捕获、滚动文件 | | **NetworkDiscovery** | ARP 扫描和主机名解析 | 网络扫描、主机枚举 | ## 工作流程：DNS 重定向 + 强制门户 + HTTPS 检查 测试目标设备的典型流程： ``` 1. DISCOVERY PHASE ├─ NetShaper discovers targets on subnet via ARP sweep ├─ Resolves hostnames (reverse DNS) └─ Validates targets are in authorized CIDR 2. SETUP PHASE (per-target) ├─ AuthorizationPolicy checks target IP ├─ FirewallManager applies per-target iptables rules ├─ Setup ARP/NDP spoofing (TargetSession) │ └─ Device now sends traffic to NetShaper IP ├─ Setup DNS interception (iptables redirect 53 → fake_server3) ├─ Setup HTTP captive portal redirect └─ Setup HTTPS inspection (mitmproxy transparent mode) 3. ACTIVE SESSION ├─ fake_server3 captures DNS queries │ ├─ Responds with spoofed A/AAAA records │ └─ Serves captive portal redirect ├─ Device visits http://..., gets 302 to captive portal ├─ Captive portal serves mitmproxy root CA download ├─ Device installs CA and retries HTTPS ├─ HTTPS traffic flows through mitmproxy (transparent proxy) ├─ Traffic shaping applies bandwidth limits (tc HTB) ├─ Packet sniffer captures all traffic to .pcap └─ State persisted to /run/netshaper//state.json 4. SHUTDOWN PHASE ├─ Signal all subsystems to halt ├─ TargetSession cleanup (remove ARP spoofing, iptables rules) ├─ FirewallManager cleanup (remove global forwarding rules) ├─ MitmProxyManager cleanup (terminate mitmproxy) ├─ RecoveryManager verifies no stale rules remain ├─ Sysctl settings restored to pre-session state └─ State file cleaned up 5. RECOVERY (if process crashes) ├─ Next NetShaper startup detects stale /run/netshaper/state.json ├─ RecoveryManager checks process ownership (PID + start time) ├─ Orphaned rules detected and removed │ ├─ Firewall rules cleaned │ ├─ Traffic shaper qdisc removed │ ├─ Sysctl settings restored │ └─ State file deleted └─ Recovery logged to /var/log/netshaper.log ``` ## 功能 - 双栈 ARP + NDP 欺骗（IPv4 和 IPv6 MITM） - 针对特定目标的 DNS 重定向和强制门户 (HTTP) - 通过 Linux `tc` HTB 进行带宽限速 - 带有可选滚动 `.pcap` 文件的数据包捕获 - 通过 mitmproxy 进行透明 HTTPS 检查 - 原子状态持久化和自动失效会话恢复 - 完整的 `--dry-run` 模式 —— 仅打印命令，不修改系统 - 模块化、可独立审计的组件 ## 要求 - Linux，Python ≥ 3.10 - Root (`sudo`) - 位于 PATH 中的 `iptables` / `ip6tables`、`tc`、`sysctl` - `scapy`、`psutil`（自动安装） ## 安装说明 ``` python -m pip install -e . ``` 开发附加包（pytest、mypy、bandit、ruff、coverage）： ``` python -m pip install -e ".[dev]" ``` ## 快速入门 ``` sudo env PYTHONPATH="$PWD/src" python -m netshaper -i \ --allow-cidr ``` Dry-run 预览（不改变系统）： ``` sudo env PYTHONPATH="$PWD/src" python -m netshaper -i \ --allow-cidr --targets --dry-run ``` 可选的 DNS/HTTP 强制门户辅助工具（在单独的终端中）： ``` sudo env PYTHONPATH="$PWD/src" python -m netshaper.fake_server3 --smart-spoof-all --host-ip ``` ## 用户指南 请参阅 [USER_GUIDE.md](USER_GUIDE.md) 了解完整的工作流程、shell 别名、伪服务器模式、发现行为、dry-run 用法和故障排除。 ## 安全与风险 请参阅 [SECURITY.md](SECURITY.md) 了解： - 已知风险（未经身份验证的 `/cert` endpoint、root 权限要求） - 缓解策略 - 推荐的审计程序 - 失效会话恢复行为 ## 测试 单元测试（模拟）： ``` python -m pytest tests/ -v --cov=src/netshaper --cov-report=term ``` 仅限 Root 的端到端 namespace 检查（需要网络 namespace）： ``` sudo env PYTHONPATH="$PWD/src:$PWD" python -m pytest tests/test_netns_integration.py -v ``` 代码质量检查： ``` ruff check src/netshaper/ mypy src/netshaper/ bandit -r src/netshaper/ -ll ``` 发布前检查清单（合并到 `main` 之前）： - [ ] 所有单元测试通过 (`pytest tests/`) - [ ] 覆盖率 ≥ 80% (`coverage report`) - [ ] 类型检查通过 (`mypy src/netshaper/`) - [ ] 风格和 lint 通过 (`ruff check`) - [ ] 安全检查通过 (`bandit`) - [ ] 特权测试在自托管 runner 上通过 (`sudo pytest tests/test_netns_integration.py`) ## 发布规范 不要分发工作树的 ZIP 压缩包。请从干净的检出中使用 `python -m build` 或 `git archive` 构建发布，以便排除 `.git`、虚拟环境、数据包捕获、日志、缓存、参考工件和状态文件。 将 Git 历史记录和数据包捕获视为敏感材料。 ## 日志和调试 在正常运行（非 `--dry-run`）时，NetShaper 会写入 `/var/log/netshaper.log`。 启动后，CLI 会打印一个已验证的证据块： - Session ID、时间戳、接口 - 目标、状态文件路径 - 监控线程状态、嗅探器状态、数据包捕获文件 - mitmproxy 进程 ID 和日志路径 - 检测到的任何 runtime 错误 在活动会话期间，NetShaper 会持续监控： - 带宽监控线程（更新 TX/RX 计数器） - 数据包嗅探器（运行中或已停止） - mitmproxy 进程（运行中或已崩溃） - 本地重定向端口（可达或不可达） 如果任何健康检查失败，它将被报告为错误并触发正常清理。 ## 操作说明 - 会话状态存储在 `/run/netshaper/` 下（root 所有，模式 0700），并在退出时清理 - 同一时间只能运行一个 NetShaper 实例（通过 `/run/netshaper/netshaper.lock` 强制执行） - `fake_server3` 是用于强制门户和 DNS 实验场景的可选辅助工具；ARP 欺骗或流量整形不需要它 - 在运行实时会话之前，请广泛使用 `--dry-run` - 在会话期间和之后监控 `/var/log/netshaper.log` - 防火墙规则使用 `netshaper::global` 标记，以便于识别 ## 故障排除 请参阅 [USER_GUIDE.md](USER_GUIDE.md) 获取详细的故障排除步骤，包括： - 设备未被欺骗 - DNS 未重定向 - 流量整形未应用 - mitmproxy 未启动 - 失效会话恢复

标签：Python CLI, Wildcard支持, 中间人攻击, 情报分析, 授权测试, 流量 shaping, 系统分析, 网络分析, 网络测试, 网络诊断, 逆向工具, 防御绕过