Skip to content

psandis/wirewatch

BranchesTags

Repository files navigation

wirewatch

npm

Network traffic monitoring CLI with AI-assisted anomaly detection. All data stays local in SQLite. No cloud, no telemetry. Works standalone or as an OpenClaw skill.

wirewatch runs a lightweight background daemon that watches every network connection on your machine. It records what is connecting, where it is going, which process opened it, and how long it stays open. When you want answers, you run ww analyze and an AI model reviews the traffic and flags anything suspicious like unusual ports, unexpected destinations, unknown processes making outbound calls.

What It Does

  • captures live network connections in the background as a daemon
  • stores connection metadata locally in SQLite
  • resolves destination country codes via ip-api.com (free, no key required)
  • runs AI analysis on recent traffic via Anthropic or OpenAI
  • flags suspicious connections with risk level and plain-language summary
  • supports --json on most commands for scripting and automation

Tech Stack

Requirements

  • Node.js 22+
  • pnpm
  • macOS or Linux
  • tcpdump for deep capture mode (requires sudo)

Install

npm install -g wirewatch

Or with pnpm:

pnpm add -g wirewatch

After installation, the ww command is available globally.

From source

git clone https://github.com/psandis/wirewatch.git
cd wirewatch
pnpm install
pnpm build
npm link

Quick Start

Before starting, set your Anthropic or OpenAI API key so ww analyze can run:

ww config set ai.anthropic.apiKey sk-ant-...

Start the background daemon. It begins capturing connections immediately:

ww start

Watch what is connecting in real time:

ww monitor

Ask AI to review recent traffic and flag anything suspicious:

ww analyze

Stop the daemon when you are done:

ww stop

Storage

Default root:

~/.wirewatch/
Path Description
~/.wirewatch/wirewatch.db SQLite database
~/.wirewatch/config.json Configuration file
~/.wirewatch/daemon.log Daemon log

Override the root:

export WIREWATCH_HOME=/path/to/custom/root

CLI

Start and stop the daemon

ww start
Daemon started (PID 89064). Run "ww status" to confirm.

ww stop
Daemon stopped (PID 89064).

Check daemon status

ww status

● wirewatch daemon is running
  Mode         passive
  Started      2026-04-19 19:56:32
  Uptime       6s
  Connections  138

View live connections

ww monitor

Opens an interactive live view. Refreshes from SQLite as the daemon captures. Use ↑ ↓ to scroll, PgUp PgDn to page, q to quit.

List captured connections

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
Flag Description
--protocol tcp|udp Filter by protocol
--dst <ip> Filter by destination IP
--direction inbound|outbound|local Filter by direction
--process <name> Filter by process name
--limit <n> Limit results (default: 100)
--since <unix-ms> Show connections since timestamp

Show connection detail

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

Run AI analysis

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.

Notes:

  • Analyzes only connections since the last run
  • --json outputs the full structured result

List past analyses

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.

Use --limit <n> to control how many results are shown (default: 20).

Database statistics

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

Delete data

Command Description
ww delete <id> Delete a single connection by ID
ww delete --analysis <id> Delete a single analysis by ID
ww delete --prune Prune connections older than retentionDays
ww delete --all Delete all data and remove ~/.wirewatch/ directory

The daemon must be stopped before running ww delete --all.

Configuration

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 <key> <value>

Capture Modes

Mode Root required Description
passive No Asks the OS what connections are open. Uses lsof on macOS and /proc/net on Linux. Polls every N seconds.
deep Yes (sudo) Runs tcpdump and intercepts every packet in real time. Catches short-lived connections and byte counts. 
ww config set capture.mode deep
sudo ww start

Configuration Reference

Key Default Description
ai.provider anthropic AI provider (anthropic or openai)
ai.anthropic.apiKey Anthropic API key
ai.anthropic.model claude-haiku-4-5-20251001 Anthropic model
ai.openai.apiKey OpenAI API key
ai.openai.model gpt-4o-mini OpenAI model
capture.mode passive Capture mode (passive or deep)
capture.interval 2 Poll interval in seconds
capture.lsofTimeout 5000 lsof timeout in milliseconds
storage.retentionDays 30 Days to keep connection records
storage.dbCacheSize -8000 SQLite cache size in kilobytes
geo.enabled true Enable GeoIP resolution
geo.url http://ip-api.com/batch GeoIP API endpoint
geo.batchSize 100 GeoIP batch size (max 100)
geo.timeout 3000 GeoIP request timeout in milliseconds
geo.flushInterval 10000 GeoIP flush interval in milliseconds

Agent Integration

Most commands support --json for structured output:

ww list --json
ww show <id> --json
ww analyze --json
ww analyses --json
ww db stats --json

OpenClaw Skill

Once installed globally (npm install -g wirewatch), add a SKILL.md to your workspace:

---
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 <id> --json`
- To view past analyses: `ww analyses --json`

Project Structure

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

Development

Clone, install, and build:

git clone https://github.com/psandis/wirewatch.git
cd wirewatch
pnpm install
pnpm build
npm link

After npm link, the ww command is available globally. Run ww --help to verify.

pnpm test        # 64 tests across config, db, capture, and ai modules
pnpm typecheck
pnpm lint

Related

  • 🦀 Feedclaw — RSS/Atom feed reader and AI digest builder
  • 🦀 Dustclaw — Find out what is eating your disk space
  • 🦀 Driftclaw — Deployment drift detection across environments
  • 🦀 Dietclaw — Codebase health monitor
  • 🦀 Mymailclaw — Email scanner, categorizer, and cleaner
  • 🦀 OpenClaw — The open source AI assistant

License

See MIT

About

Network traffic monitoring CLI with AI-assisted anomaly detection. Works standalone or as an OpenClaw skill.

Topics

nodejs macos linux cli security typescript ai sqlite network-security anomaly-detection network-monitor openclaw

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

3 tags

Packages

 
 
 

Contributors 1

Languages