psandis/wirewatch

# wirewatch [](https://www.npmjs.com/package/wirewatch) 网络流量监控 CLI 工具，具备 AI 辅助异常检测功能。所有数据本地存储在 SQLite 中。无云端，无遥测。可独立运行或作为 [OpenClaw](https://github.com/openclaw/openclaw) 技能使用。 wirewatch 会在后台运行一个轻量级守护进程，监控本机所有网络连接。它记录连接的目标、端口、发起进程及连接持续时间。当需要分析时，运行 `ww analyze`，AI 模型会检查流量并标记可疑行为，例如非常规端口、意外目的地或未知进程发起的出站调用。 ## 功能 - 以守护进程形式后台捕获实时网络连接 - 将连接元数据本地存储在 SQLite 中 - 通过 ip-api.com 解析目标国家代码（免费，无需密钥） - 通过 Anthropic 或 OpenAI 对近期流量进行 AI 分析 - 标记可疑连接并给出风险等级和自然语言摘要 - 大多数命令支持 `--json` 输出，便于脚本和自动化 ## 技术栈 - [TypeScript](https://www.typescriptlang.org/) 在 Node.js 22+ 上运行 - [SQLite](https://www.sqlite.org/) 通过 [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) 实现本地存储 - [Commander](https://github.com/tj/commander.js) 用于 CLI 解析 - [chalk](https://github.com/chalk/chalk) 用于终端颜色 - [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-node) 和 [OpenAI SDK](https://github.com/openai/openai-node) 用于 AI 分析 - [ip-api.com](http://ip-api.com) 用于 GeoIP 国家码解析（免费，无需密钥） - `lsof`（macOS）和 `/proc/net`（Linux）用于被动连接捕获 - `tcpdump` 用于深度数据包捕获模式 - [Vitest](https://vitest.dev/) 用于测试 - [Biome](https://biomejs.dev/) 用于代码检查和格式化 - [tsup](https://tsup.egoist.dev/) 用于构建 ## 系统要求 - Node.js 22+ - pnpm - macOS 或 Linux - `tcpdump` 用于深度捕获模式（需要 sudo） ## 安装 ``` npm install -g wirewatch ``` 或使用 pnpm： ``` pnpm add -g wirewatch ``` 安装完成后，`ww` 命令全局可用。 ### 从源码安装 ``` git clone https://github.com/psandis/wirewatch.git cd wirewatch pnpm install pnpm build npm link ``` ## 快速开始 开始前，请设置 Anthropic 或 OpenAI API 密钥，以便 `ww analyze` 可以运行： ``` ww config set ai.anthropic.apiKey sk-ant-... ``` 启动后台守护进程。它会立即开始捕获连接： ``` ww start ``` 实时查看正在连接的网络： ``` ww monitor ``` 请求 AI 检查近期流量并标记可疑项： ``` ww analyze ``` 完成时停止守护进程： ``` ww stop ``` ## 存储 默认根目录： ``` ~/.wirewatch/ ``` | 路径 | 描述 | |------|------| | `~/.wirewatch/wirewatch.db` | SQLite 数据库 | | `~/.wirewatch/config.json` | 配置文件 | | `~/.wirewatch/daemon.log` | 守护进程日志 | 覆盖根目录： ``` export WIREWATCH_HOME=/path/to/custom/root ``` ## CLI ### 启动和停止守护进程 ``` ww start ``` ``` Daemon started (PID 89064). Run "ww status" to confirm. ``` ``` ww stop ``` ``` Daemon stopped (PID 89064). ``` ### 检查守护进程状态 ``` ww status ● wirewatch daemon is running Mode passive Started 2026-04-19 19:56:32 Uptime 6s Connections 138 ``` ### 查看实时连接 ``` ww monitor ``` 打开交互式实时视图。守护进程捕获的新数据会实时从 SQLite 刷新。使用 `↑` `↓` 滚动，`PgUp` `PgDn` 翻页，`q` 退出。 ### 列出捕获的连接 ``` ww list ID PROTO SOURCE DESTINATION DIR STATE PROCESS CC LAST SEEN 257 TCP 192.168.1.5:52758 8.8.8.8:443 out ESTABLISHED node US 2026-04-19 19:56:38 256 TCP 192.168.1.5:52740 1.1.1.1:443 out ESTABLISHED Chrome US 2026-04-19 19:56:34 255 TCP 192.168.1.5:52741 140.82.114.4:443 out ESTABLISHED node US 2026-04-19 19:56:34 158 TCP 192.168.1.5:52189 93.184.216.34:443 out ESTABLISHED curl US 2026-04-19 19:56:32 124 TCP 192.168.1.5:50756 142.250.185.46:993 out ESTABLISHED Mail US 2026-04-19 19:56:32 ``` | 参数 | 描述 | |------|------| | `--protocol tcp\|udp` | 按协议过滤 | | `--dst ` | 按目标 IP 过滤 | | `--direction inbound\|outbound\|local` | 按方向过滤 | | `--process ` | 按进程名过滤 | | `--limit ` | 限制返回结果数（默认：100） | | `--since ` | 显示指定时间戳之后的连接 | ### 显示连接详情 ``` ww show 257 Connection #257 Protocol TCP Direction out Source 192.168.1.5:52758 Destination 8.8.8.8:443 Hostname dns.google Country US State ESTABLISHED Process node (PID 8821) Capture passive Bytes sent - Bytes recv - Interface en0 First seen 2026-04-19 19:56:38 Last seen 2026-04-19 19:56:58 Duration 20s ``` ### 运行 AI 分析 ``` ww analyze Analysis #1 ● low 2026-04-19 19:57:10 anthropic/claude-haiku-4-5-20251001 162 connections Traffic appears normal. Outbound connections are predominantly HTTPS to known services including Google, GitHub, and Cloudflare. DNS queries are directed to 1.1.1.1 and 8.8.8.8. No unusual ports or unexpected destinations detected. ``` 说明： - 仅分析上次运行以来的连接 - `--json` 输出完整结构化结果 ### 列出历史分析 ``` ww analyses Analysis #1 ● low 2026-04-19 19:57:10 anthropic/claude-haiku-4-5-20251001 162 connections Traffic appears normal. Outbound connections are predominantly HTTPS to known services including Google, GitHub, and Cloudflare. No unusual ports or unexpected destinations detected. ``` 使用 `--limit ` 控制显示数量（默认：20）。 ### 数据库统计 ``` ww db stats Database Statistics Connections 162 Analyses 1 Sessions 2 Oldest record 2026-04-19 19:48:24 DB size 76.0KB By protocol: TCP 160 UDP 2 By direction: outbound 155 inbound 6 local 1 Top destinations: 8.8.8.8 18 1.1.1.1 14 140.82.114.4 6 93.184.216.34 5 142.250.185.46 4 ``` ### 删除数据 | 命令 | 描述 | |------|------| | `ww delete ` | 按 ID 删除单个连接 | | `ww delete --analysis ` | 按 ID 删除单个分析记录 | | `ww delete --prune` | 删除早于 `retentionDays` 的连接 | | `ww delete --all` | 删除所有数据并移除 `~/.wirewatch/` 目录 | 在运行 `ww delete --all` 前必须先停止守护进程。 ### 配置 ``` ww config show Configuration AI provider anthropic anthropic.key set anthropic.model claude-haiku-4-5-20251001 openai.key not set openai.model gpt-4o-mini Capture mode passive interval 2s interfaces all Storage retentionDays 30 dbCacheSize -8000 GeoIP enabled true url http://ip-api.com/batch batchSize 100 timeout 3000ms flushInterval 10000ms ``` ``` ww config set ``` ## 捕获模式 | 模式 | 是否需要 root | 描述 | |------|--------------|------| | `passive` | 否 | 查询操作系统当前打开的连接。使用 macOS 的 `lsof` 和 Linux 的 `/proc/net`。按 N 秒轮询。 | | `deep` | 是（需 sudo） | 运行 `tcpdump` 并实时拦截每个数据包。可捕获短连接和字节统计。 | ``` ww config set capture.mode deep sudo ww start ``` ## 配置参考 | 键 | 默认值 | 描述 | |----|--------|------| | `ai.provider` | `anthropic` | AI 提供者（`anthropic` 或 `openai`） | | `ai.anthropic.apiKey` | | Anthropic API 密钥 | | `ai.anthropic.model` | `claude-haiku-4-5-20251001` | Anthropic 模型 | | `ai.openai.apiKey` | | OpenAI API 密钥 | | `ai.openai.model` | `gpt-4o-mini` | OpenAI 模型 | | `capture.mode` | `passive` | 捕获模式（`passive` 或 `deep`） | | `capture.interval` | `2` | 轮询间隔（秒） | | `capture.lsofTimeout` | `5000` | lsof 超时（毫秒） | | `storage.retentionDays` | `30` | 保留连接记录的天数 | | `storage.dbCacheSize` | `-8000` | SQLite 缓存大小（KB） | | `geo.enabled` | `true` | 启用 GeoIP 解析 | | `geo.url` | `http://ip-api.com/batch` | GeoIP API 端点 | | `geo.batchSize` | `100` | GeoIP 批量大小（最大 100） | | `geo.timeout` | `3000` | GeoIP 请求超时（毫秒） | | `geo.flushInterval` | `10000` | GeoIP 刷新间隔（毫秒） | ## 代理集成 大多数命令支持 `--json` 输出结构化数据： ``` ww list --json ww show --json ww analyze --json ww analyses --json ww db stats --json ``` ### OpenClaw 技能 全局安装后（`npm install -g wirewatch`），在项目工作区添加 `SKILL.md`： ``` --- name: wirewatch description: Monitor network connections and detect suspicious activity with AI analysis version: 1.0.0 requires_binaries: - ww --- When the user asks about network traffic, connections, or security anomalies, use the `ww` CLI: - To list recent connections: `ww list --json` - To run AI analysis: `ww analyze --json` - To check daemon status: `ww status` - To show connection detail: `ww show --json` - To view past analyses: `ww analyses --json` ``` ## 项目结构 ``` src/ cli.ts entry point for the ww command daemon.ts background capture process types.ts shared TypeScript types lib/ ai.ts AI analysis via Anthropic or OpenAI config.ts configuration load, save, and validation db.ts SQLite database layer format.ts terminal output formatting geo.ts GeoIP enrichment queue capture/ index.ts capture orchestration and diff logic passive.ts passive capture via lsof and /proc deep.ts deep capture via tcpdump tui/ index.tsx live connection monitor view tests/ ai.test.ts capture.test.ts config.test.ts db.test.ts ``` ## 开发 克隆、安装并构建： ``` git clone https://github.com/psandis/wirewatch.git cd wirewatch pnpm install pnpm build npm link ``` 执行 `npm link` 后，`ww` 命令全局可用。运行 `ww --help` 验证。 ``` pnpm test # 64 tests across config, db, capture, and ai modules pnpm typecheck pnpm lint ``` ## 相关项目 - 🦀 [Feedclaw](https://github.com/psandis/feedclaw) — RSS/Atom 订阅源阅读器和 AI 摘要生成器 - 🦀 [Dustclaw](https://github.com/psandis/dustclaw — 查找占用磁盘空间的文件 - 🦀 [Driftclaw](https://github.com/psandis/driftclaw) — 跨环境部署漂移检测 - 🦀 [Dietclaw](https://github.com/psandis/dietclaw) — 代码库健康度监控 - 🦀 [Mymailclaw](https://github.com/psandis/mymailclaw) — 邮件扫描、分类和清理 - 🦀 [OpenClaw](https://github.com/openclaw/openclaw) — 开源 AI 助手 ## 许可证 参见 [MIT](LICENSE)

标签：AI辅助分析, Anthropic, API安全, better-sqlite3, CIS基准, Commander.js, GNU通用公共许可证, IP地理定位, JSON输出, lsof, MITM代理, Node.js, OpenAI, OpenClaw技能, SEO: AI异常检测, SEO: 本地流量分析, SEO: 网络流量监控, SQLite, TypeScript, 内存规避, 后台监控, 守护进程, 安全插件, 开源安全工具, 异常检测, 数字取证, 本地数据库, 自动化攻击, 自动化脚本, 逆向工程平台