{"id":50748054,"url":"https://github.com/mattmorris-dev/netwatch-sec","last_synced_at":"2026-06-10T23:00:33.647Z","repository":{"id":361444610,"uuid":"1254222792","full_name":"Mattmorris-dev/netwatch-sec","owner":"Mattmorris-dev","description":"All-In-One Network Security Dashboard","archived":false,"fork":false,"pushed_at":"2026-06-09T23:02:32.000Z","size":2222,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-09T23:14:03.964Z","etag":null,"topics":["cybersecurity","honeypot","network-security","nmap","osint","pentesting","python","raspberry-pi","security","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mattmorris-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"buy_me_a_coffee":"pr0xy_22"}},"created_at":"2026-05-30T09:44:46.000Z","updated_at":"2026-06-09T23:02:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Mattmorris-dev/netwatch-sec","commit_stats":null,"previous_names":["mattymomo1993/netwatch","mattmorris-dev/netwatch-sec"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Mattmorris-dev/netwatch-sec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattmorris-dev%2Fnetwatch-sec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattmorris-dev%2Fnetwatch-sec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattmorris-dev%2Fnetwatch-sec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattmorris-dev%2Fnetwatch-sec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mattmorris-dev","download_url":"https://codeload.github.com/Mattmorris-dev/netwatch-sec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mattmorris-dev%2Fnetwatch-sec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34174148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cybersecurity","honeypot","network-security","nmap","osint","pentesting","python","raspberry-pi","security","tui"],"created_at":"2026-06-10T23:00:21.320Z","updated_at":"2026-06-10T23:00:33.634Z","avatar_url":"https://github.com/Mattmorris-dev.png","language":"Python","funding_links":["https://buymeacoffee.com/pr0xy_22"],"categories":[],"sub_categories":[],"readme":"![NetWatch](docs/banner.png)\n\n# NetWatch\n\n[![PyPI version](https://img.shields.io/pypi/v/netwatch-sec.svg)](https://pypi.org/project/netwatch-sec/)\n[![Downloads](https://static.pepy.tech/badge/netwatch-sec)](https://pepy.tech/project/netwatch-sec)\n[![Downloads/month](https://static.pepy.tech/badge/netwatch-sec/month)](https://pepy.tech/project/netwatch-sec)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Flask](https://img.shields.io/badge/Flask-2.3+-000000?logo=flask\u0026logoColor=white)](https://flask.palletsprojects.com/)\n[![Raspberry Pi](https://img.shields.io/badge/Raspberry%20Pi-A22846?logo=raspberrypi\u0026logoColor=white)](https://www.raspberrypi.org/)\n[![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black)](https://www.linux.org/)\n[![Parrot OS](https://img.shields.io/badge/Parrot%20OS-15CDCA?logo=parrotsecurity\u0026logoColor=white)](https://www.parrotsec.org/)\n[![Kali](https://img.shields.io/badge/Kali-557C94?logo=kalilinux\u0026logoColor=white)](https://www.kali.org/)\n[![Platform: Debian](https://img.shields.io/badge/platform-debian-A81D33?logo=debian\u0026logoColor=white)](https://www.debian.org/)\n[![Tests](https://img.shields.io/badge/tests-2106-brightgreen.svg)](tests/)\n[![Version](https://img.shields.io/badge/version-1.2.1-blue.svg)](CHANGELOG.md)\n[![Status: Active](https://img.shields.io/badge/status-active-brightgreen.svg)]()\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?logo=buy-me-a-coffee\u0026logoColor=black)](https://buymeacoffee.com/pr0xy_22)\n\n**All-in-one network security dashboard** — deploy honeypots, capture traffic, run OSINT, scan targets, block threats, and forward alerts over mesh radio. One command, one file, real-time.\n\n```\nsudo netwatch\n```\n\nNetWatch turns any Linux box into a full network security sensor. It deploys 4 honeypot services that lure and log attackers, sniffs all traffic on your interface with raw sockets and tshark, auto-enriches every IP with geolocation and threat scoring, and gives you 100+ commands to investigate, track, and block threats — all from a single terminal or browser.\n\nBuilt for Raspberry Pi, Kali, Parrot OS, and any Debian-based Linux. Runs as a single Python file with no microservices, no Docker, no cloud dependency.\n\n---\n\n## How It Works\n\n1. **Launch** — `sudo netwatch` starts everything: 4 honeypots bind their ports, raw socket sniffer attaches to your interface, tshark begins protocol analysis, ARP monitor discovers devices, web dashboard opens on :9090\n2. **Capture** — Every packet is parsed for source/destination IPs, ports, protocols, and DNS queries. Honeypots log credentials, commands, file uploads, and malware download attempts\n3. **Enrich** — Each new IP is automatically scored for threat level based on port behavior, known bad ports, and scan patterns. Run OSINT commands to add geolocation, WHOIS, abuse reports, and ASN data\n4. **Respond** — Block attackers with iptables, tag and watchlist IPs, run deep nmap scans, capture payloads, export reports. Forward critical alerts over LoRa mesh radio for off-grid monitoring\n5. **View** — Full-screen TUI with 11 tabs, or browser dashboard with live charts, clickable IPs, 5 color themes, and CRT scanline effects\n\n---\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                     NETWATCH v1.1.0                          │\n├──────────────────────────────────────────────────────────────┤\n│  TERMINAL UI (TUI)        │  WEB DASHBOARD (:9090)           │\n│  Full-screen ANSI         │  Flask + SSE live updates        │\n│  11 tabs, console mode    │  5 themes, CRT scanlines         │\n│  Tab/number key nav       │  Charts, clickable IPs, API      │\n├──────────────────────────────────────────────────────────────┤\n│  HONEYPOTS                │  TRAFFIC MONITORING              │\n│  HTTP :8080 (NVR panel)   │  Raw socket sniffer              │\n│  Telnet :2323 (DVR)       │  tshark protocol analysis        │\n│  FTP :2121 (bait files)   │  tcpdump PCAP recording          │\n│  RTSP :8554 (camera)      │  ARP device discovery            │\n├──────────────────────────────────────────────────────────────┤\n│  SCANNING \u0026 RECON         │  OSINT (16 tools)                │\n│  nmap integration         │  GeoIP, WHOIS, DNS enum          │\n│  Port scanning            │  SSL/TLS, HTTP headers           │\n│  Service detection        │  Abuse/ASN, cert transparency    │\n│  Stealth (Tor) mode       │  Tech fingerprinting, speedtest  │\n├──────────────────────────────────────────────────────────────┤\n│  DEFENSE                  │  MESH RADIO                      │\n│  iptables blocking        │  Meshtastic LoRa support         │\n│  Threat scoring           │  Alert forwarding                │\n│  Watchlists \u0026 tagging     │  Two-way messaging               │\n└──────────────────────────────────────────────────────────────┘\n```\n\n## Install\n\n**Quick install (from PyPI):**\n```bash\nsudo apt install -y nmap tshark tcpdump traceroute iproute2 iptables \\\n                    openssl curl dnsutils whois psmisc arp-scan tor proxychains4\npipx install netwatch-sec\nsudo netwatch\n```\n\n**From source:**\n```bash\n# System tools (one-shot — covers all commands NetWatch shells out to)\nsudo apt install -y nmap tshark tcpdump traceroute iproute2 iptables \\\n                    openssl curl dnsutils whois psmisc arp-scan \\\n                    tor proxychains4\n\n# Python deps\npip3 install -r requirements.txt\n\n# Optional features\npip3 install graphene flask-graphql    # GraphQL API at :9090/graphql\npip3 install meshtastic                # LoRa mesh radio alerts\nsudo apt install -y speedtest-cli      # `speed` command\n\n# Install launcher system-wide\nchmod +x netwatch-start.sh\nsudo ln -s $(pwd)/netwatch-start.sh /usr/local/bin/netwatch\n```\n\n**Docker (one-liner):**\n```bash\ndocker run -d --name netwatch --restart unless-stopped \\\n  --network host --cap-add NET_ADMIN --cap-add NET_RAW \\\n  -e NETWATCH_TELNET_PORT=23 -e NETWATCH_FTP_PORT=21 \\\n  -e NETWATCH_HTTP_PORT=80 -e NETWATCH_RTSP_PORT=554 \\\n  -v netwatch-logs:/app/logs \\\n  ghcr.io/mattmorris-dev/netwatch-sec:latest eth0\n```\nThis runs headless: honeypots on standard ports (23/21/80/554) + the web dashboard on `:9090`. System tools (nmap, tshark, tcpdump, …) are baked into the image. Multi-arch — works on x86-64 and ARM64 (Raspberry Pi). Swap `eth0` for your capture interface.\n\nOr with Compose:\n```bash\ndocker compose up -d        # uses docker-compose.yml\ndocker compose logs -f      # watch attacks\n```\n\nWatch the attack feed (clean JSON, one line per hit):\n```bash\ndocker exec netwatch tail -f /app/logs/all_events.json\n```\n\n\u003e `--network host` and the `NET_ADMIN`/`NET_RAW` caps let NetWatch bind privileged ports and capture traffic. Host networking is Linux-only; on macOS/Windows drop `--network host` and publish ports with `-p` instead (capture features are limited there).\n\n## Quick Start\n\n```bash\n# Random token each launch (default — more secure)\nsudo netwatch\n\n# Persistent token across restarts (requires NETWATCH_FIXED_TOKEN env var)\nexport NETWATCH_FIXED_TOKEN=$(openssl rand -hex 24)\nsudo -E netwatch --fixed-token\n\n# Specific interface\nsudo netwatch eth0\n```\n\nOn launch a redacted token preview is printed (`ABCDEF…WXYZ`) and the full token is written to `~/.config/netwatch/token` (mode 0600). Use it to log into the web dashboard at `http://\u003cyour-ip\u003e:9090`.\n\nBoth TUI and web UI launch together — one command runs everything.\n\n### Key \u0026 token rotation\n\nFrom the TUI prompt:\n\n| Command | Effect |\n|---------|--------|\n| `rotate-key` | Generate a new Fernet key — invalidates all active web sessions. Persisted to `~/.config/netwatch/web.key`. |\n| `rotate-token` | Generate a new auth token — invalidates all sessions. Re-written to `~/.config/netwatch/token` (0600). |\n\n### Honeypot ports\n\nDefaults bind to high ports so root isn't required: HTTP `:8080`, Telnet `:2323`, FTP `:2121`, RTSP `:8554`. Override via env to move to standard ports (needs `CAP_NET_BIND_SERVICE` or root):\n\n```bash\nNETWATCH_HTTP_PORT=80 \\\nNETWATCH_TELNET_PORT=23 \\\nNETWATCH_FTP_PORT=21 \\\nNETWATCH_RTSP_PORT=554 \\\nsudo -E netwatch\n```\n\nPersist by adding to `/etc/netwatch.env` and referencing in the systemd unit's `EnvironmentFile=`. Internet-facing scanners hit the standard ports — non-standard ports stay invisible to most drive-by traffic.\n\n### Replay tunables\n\nSame-IP telnet attempts roll up into one aggregated session (`all_\u003cip\u003e`) so a scanner banging your honeypot all day shows as one entry instead of fifty. Inside the timeline, `── ATTEMPT N (timestamp UTC) ──` markers separate bursts. Tune the burst threshold with:\n\n```bash\nNETWATCH_TELNET_GAP_SEC=86400 sudo -E netwatch   # one marker per day (default: 300 = 5 min)\n```\n\nIndividual per-attempt sessions remain loadable via their original `\u003cip\u003e_HHMMSS` id for drill-down.\n\n### CrowdSec auto-ban (optional)\n\nIf [`cscli`](https://docs.crowdsec.net/) is installed on the host, every honeypot capture (`credential`, `telnet`, `ftp`, `rtsp`, `malware_attempt`, `ftp_upload`, `telnet_cmd`) automatically calls `cscli decisions add` with a 4h ban. The CrowdSec firewall bouncer enforces the drop via ipset, so the rule count never blows up. Same-IP events within 60s are deduped. Set `NETWATCH_AUTODEFEND=0` to disable. With no CrowdSec installed, the hook silently no-ops.\n\nInstall on Debian:\n\n```bash\ncurl -s https://install.crowdsec.net | sudo sh\nsudo apt install -y crowdsec crowdsec-firewall-bouncer-iptables\nsudo systemctl enable --now crowdsec crowdsec-firewall-bouncer\n```\n\nWhitelist your operator IP so you don't ban yourself — add `/etc/crowdsec/parsers/s02-enrich/whitelists.yaml`:\n\n```yaml\nname: netwatch/operator-whitelist\nwhitelist:\n  reason: \"operator home\"\n  ip: [\"\u003cyour-public-ip\u003e\"]\n```\n\n## Session Replay\n\n```bash\nsudo netwatch                                          # capture starts immediately\npython tools/synth_ftp_session.py 198.51.100.42        # optional — fake an attacker\n# open http://localhost:9090 and click the REPLAY tab\n```\n\nEvery captured session (FTP, Telnet, HTTP probes) is recorded as a scrubbable timeline. The web player auto-lists sessions; pick one and step through the keystrokes frame by frame. In the TUI, `replay list` shows recent sessions and `replay \u003cidx\u003e` drops into the player.\n\nPlayer keys: `space` play/pause · `←/→` step · `\u003c/\u003e` jump session · `+/-` speed · `Home/End` ends. Full architecture in [`docs/DROP4_TUI_REPLAY_PLAN.md`](docs/DROP4_TUI_REPLAY_PLAN.md).\n\n## Remote Access\n\nWhen `cloudflared` is available, NetWatch starts a quick tunnel automatically at launch. The public `*.trycloudflare.com` URL is printed at startup and pinned to the top of the **all** tab on the dashboard so you can copy it without scrolling through alerts.\n\nConsole commands (type into the prompt):\n\n| Command | Purpose |\n|---------|---------|\n| `tunnel` | Reprint the current trycloudflare URL + full web token |\n| `restart-tunnel` | Kill cloudflared, spawn a fresh tunnel (new URL) |\n| `token` | Reprint the full web token + on-disk path |\n\n```bash\n# Manual fallback if cloudflared isn't on $PATH\ncloudflared tunnel --url http://localhost:9090\n\n# Or point NetWatch at a non-default cloudflared binary\nNETWATCH_CLOUDFLARED_BIN=/opt/cf/cloudflared sudo -E netwatch\n```\n\n### Public-IP access (no tunnel)\n\nThe web dashboard's IP allowlist defaults to **loopback + RFC1918 + Tailscale (100.64/10)** so a fresh install can't be reached from the open internet by accident. To allow your home/office IP, set `NETWATCH_WEB_ALLOW` to one or more CIDRs:\n\n```bash\n# Single host\nNETWATCH_WEB_ALLOW=203.0.113.42/32 sudo -E netwatch\n\n# Multiple ranges (comma-separated)\nNETWATCH_WEB_ALLOW=\"203.0.113.42/32,198.51.100.0/24\" sudo -E netwatch\n```\n\nInvalid CIDRs are skipped with a warning at startup. Token auth still applies — adding an IP only lets the login page render. Pair with `ufw`/`iptables` for defense in depth.\n\n## Termux / non-root (passive mode)\n\nNetWatch runs on Termux (Android) and any non-root environment in **passive mode** — honeypots, OSINT, web dashboard, and nmap connect-scan still work. Features that need raw sockets or kernel access are auto-disabled:\n\n| Feature | Root | Termux / non-root |\n|---------|------|-------------------|\n| Honeypots (HTTP/Telnet/FTP/RTSP) | ✓ | ✓ |\n| Web dashboard + OSINT | ✓ | ✓ |\n| nmap (connect / `-sV`) | ✓ | ✓ |\n| Raw-socket sniffer / `traffic` | ✓ | — |\n| `tshark` / `tcpdump` capture | ✓ | — |\n| ARP monitor | ✓ | — |\n| `block` / `unblock` (iptables) | ✓ | — |\n| nmap SYN scan (`-sS`) | ✓ | — |\n\n```bash\n# Termux quick start\npkg install python nmap whois tor\npip install netwatch-sec\nnetwatch                    # passive mode — no sudo needed\n```\n\n## Terminal UI\n\nThree screens, hotkey-toggled. Switching screens keeps your tab and scroll position.\n\n| Screen | Hotkey | Purpose |\n|--------|--------|---------|\n| **Dashboard** | `F1` | 11 tabs, live host/protocol/honeypot view |\n| **Command Line** | `F2` | Full-screen prompt + command output |\n| **Console** | `F3` | Full-screen log of tool output |\n\n```\nF1 / F2 / F3       Switch screens\n1-9, 0             Jump to tab\nType anything      Open command prompt\nUp/Down            History recall\nPgUp / PgDn        Scrollback\nHome / End         Top / bottom\nESC                Close help overlay\nclear              Wipe console buffer\n```\n\n### Tabs\n\n`all` · `hosts` · `proto` · `dns` · `honeypot` · `nmap` · `arp` · `alerts` · `osint` · `proxy` · `mesh`\n\n## Web Dashboard\n\nBrowser UI on `:9090` with live SSE updates, 5 themes, and CRT scanline effects.\n\n- **Themes**: Terminal Classic, Matrix Green, Midnight Blue, Cyberpunk, Light Mode\n- **CRT Scanlines**: Off, Soft, Heavy — retro terminal aesthetic\n- **Charts**: Live traffic timeline, protocol distribution, threat breakdown\n- **Click any IP** for context menu — scan, geo, whois, traceroute, full recon\n- **Resizable output panel** with drag handle\n- **Host detail modal** with ports, tags, OSINT results, honeypot activity\n- **Keyboard shortcuts**: 1-0 for tabs, `/` to focus command bar, ESC to dismiss\n\n### Security\n\n- Token auth required (auto-generated or `--token \u003cval\u003e` or env var `NETWATCH_TOKEN`)\n- Fernet-encrypted session cookies, key persisted at `~/.config/netwatch/web.key`\n- Private network access by default (127/10/192.168/100.64); add public CIDRs via `NETWATCH_WEB_ALLOW=cidr,cidr,...`\n- CSRF origin validation on all POST endpoints\n- Destructive commands disabled via web\n- SSRF protection on outbound OSINT (fails closed, private IP rejection)\n- Rate limiting: 20 cmd/min, 3 expensive/min per IP\n- CIDR max /20 on web scan commands\n- Nmap target validation at function entry (regex + flag allowlist)\n\n## Commands\n\n### OSINT (16 tools)\n\n| Command | Description |\n|---------|-------------|\n| `geo \u003cip\u003e` | IP geolocation |\n| `whois \u003cip/domain\u003e` | WHOIS lookup |\n| `dnsinfo \u003cdomain\u003e` | DNS enumeration (A/AAAA/MX/NS/TXT/SOA/CNAME/SRV) |\n| `rdns \u003cip\u003e` | Reverse DNS |\n| `ssl \u003chost\u003e [port]` | TLS certificate inspection |\n| `secheaders \u003curl\u003e` | Security header audit + grade |\n| `techstack \u003curl\u003e` | Web technology fingerprinting |\n| `ping \u003cip\u003e [count]` | Jitter analysis + TTL OS guess |\n| `health \u003ctarget\u003e` | Full profile (ping + SSL + headers + tech + geo + DNS) |\n| `etrace \u003ctarget\u003e` | Enriched traceroute with per-hop GeoIP |\n| `portscan \u003cip\u003e` | Socket-based top 1000 port scan |\n| `subnet [cidr]` | Threaded ping sweep |\n| `crt \u003cdomain\u003e` | Certificate transparency search |\n| `headers \u003curl\u003e` | HTTP response headers |\n| `asn \u003cip\u003e` | ASN/BGP info |\n| `abuse \u003cip\u003e` | IP reputation check |\n| `speed` | Network speed test (download/upload/ping) |\n| `ifinfo` | Local interface info + routing table |\n\n### Scanning\n\n| Command | Description |\n|---------|-------------|\n| `scan \u003cip\u003e [preset]` | Nmap scan (quick/syn/udp/ping/full) |\n| `deep \u003cip\u003e` | All ports + vuln scripts |\n| `stealth \u003cip\u003e` | SYN scan through Tor |\n| `recon \u003cip\u003e` | Full OSINT profile |\n| `fullrecon \u003cip\u003e` | 7-phase recon chain |\n| `sweep [cidr]` | ARP + ping + port scan |\n| `banner \u003cip\u003e \u003cport\u003e` | Service banner grab |\n| `trace \u003cip\u003e` | Traceroute |\n\n### Tracking \u0026 Capture\n\nRequires root. Disabled automatically in passive mode.\n\n| Command | Description |\n|---------|-------------|\n| `track \u003cip\u003e [secs]` | Live packet tail (tshark) |\n| `conns \u003cip\u003e` | TCP conversation capture |\n| `sniff \u003cip\u003e [secs]` | Raw payload capture |\n| `trackdns \u003cip\u003e` | DNS query capture |\n| `pcap start/stop` | PCAP recording |\n\n### Defense\n\n| Command | Description |\n|---------|-------------|\n| `block \u003cip\u003e` | iptables DROP (root only) |\n| `unblock \u003cip\u003e` | Remove block (root only) |\n| `blockall attackers` | Block all honeypot IPs (root only) |\n| `diffarp` | ARP table change detection |\n\n### System\n\n| Command | Description |\n|---------|-------------|\n| `status` | Service info + uptime |\n| `dashboard` / `d` | Return to dashboard screen |\n| `clear` | Wipe console buffer |\n| `help` | Show full reference overlay |\n| `rotate-key` | New Fernet key (invalidates web sessions) |\n| `rotate-token` | New web auth token (invalidates sessions) |\n\n### Smart Filters\n\n| Command | Description |\n|---------|-------------|\n| `top [n]` | Top N talkers |\n| `sus` | Suspicious hosts (threat \u003e 0) |\n| `new [mins]` | Recently appeared |\n| `loud` | Most ports touched |\n| `find \u003cpattern\u003e` | Search all data |\n| `ports \u003cport\u003e` | Hosts using port |\n| `country \u003cCC\u003e` | Filter by country |\n\n### Batch Operations\n\n```\nscanall [list]     reconall [list]     geoall [list]     whoisall [list]\n```\n\nLists: `hosts` · `attackers` · `arp` · `nmap` · `watchlist` · `tracked` · `blocked`\n\nUse `@N` to reference IPs by index: `scan @3` scans the 3rd IP in the current list.\n\n### Proxy / Tor\n\n```\nproxy add socks5 127.0.0.1:9050    proxy list\nproxy test                         proxy rotate\nproxy start                        proxy stop\n```\n\n### Mesh Radio\n\n```\nmesh send \u003ctext\u003e     mesh status     mesh nodes     mesh alert on/off\n```\n\n## Honeypots\n\n| Service | Port | Captures |\n|---------|------|----------|\n| **HTTP NVR Panel** | 8080 | Credentials, session tokens, API probes |\n| **Telnet DVR** | 2323 | Login attempts, shell commands, malware downloads |\n| **FTP Bait Server** | 2121 | Credentials, keystroke logs, file uploads (max 10MB) |\n| **RTSP Camera** | 8554 | Auth probes, stream requests |\n\nAll events logged to JSON with ANSI-stripped, sanitized data. Connection limits per service (50 max). FTP has path traversal protection and filename sanitization.\n\n### Session replay → GIF\n\nTurn any FTP session log into a watchable asciinema cast and GIF:\n\n```bash\npython3 tools/replay_to_gif.py logs/ftp_session_\u003cip\u003e_\u003cts\u003e.log demo.gif\n```\n\nReal attacker cadence preserved, idle stalls compressed. Requires [`agg`](https://github.com/asciinema/agg) for the GIF step.\n\n## GraphQL API\n\nAvailable at `:9090/graphql` when `graphene` is installed.\n\n```graphql\n{ hosts(minThreat: 10, limit: 20) { ip hostname threatScore tags } }\n{ honeypotEvents(service: \"telnet\") { time ip summary } }\nmutation { runCommand(cmd: \"geo 8.8.8.8\") { output } }\n```\n\n## Testing\n\n```bash\npython3 -m pytest tests/ -q\n# 1900 tests, ~30s on a Pi 5\n```\n\nLint (CI threshold `--fail-under=9.0`):\n\n```bash\npylint $(git ls-files '*.py') --fail-under=9.0\n```\n\n## Security Model\n\n- All subprocess calls use argument lists, never `shell=True`\n- Nmap target regex validation at function entry + flag allowlist\n- ANSI escape stripping on all logged data (log injection prevention)\n- FTP upload path traversal blocked via `os.path.realpath` checks\n- FTP data connection synchronized with `threading.Event`\n- Session stores bounded with TTL eviction\n- Log rotation at 50MB\n- SSRF protection: private IP rejection on outbound OSINT, fails closed on DNS errors\n- PTR records never trusted for security decisions\n- Flask secret keys randomized per startup\n- Fernet-encrypted web cookies — no plaintext fallback\n- Thread-safe rendering with RLock synchronization\n- GraphQL query complexity limited (depth 7, aliases 10, length 4000)\n- Web API rate limiting: 20 cmd/min, 3 expensive/min per IP\n- CIDR max /20 on web scan commands\n\n## Requirements\n\n| Component | Details |\n|-----------|---------|\n| **OS** | Linux (Debian, Ubuntu, Raspbian, Parrot, Kali) — also runs on Termux (Android) in passive mode |\n| **Python** | 3.9+ |\n| **Root** | Recommended (raw sockets, iptables, sub-1024 binding). Non-root and Termux run in passive mode (honeypots, OSINT, web, nmap connect-scan). |\n| **System** | nmap, tshark, tcpdump, traceroute |\n| **Python** | flask, requests, python-whois, dnspython, markupsafe, cryptography |\n| **Optional** | graphene, flask-graphql, meshtastic, speedtest-cli |\n\nTested on Raspberry Pi 5, Parrot OS, and Termux (Android, passive mode).\n\n## Deploy\n\n```bash\ngit clone https://github.com/Mattmorris-dev/netwatch-sec.git \u0026\u0026 cd netwatch-sec\nsudo apt install nmap tshark tcpdump traceroute\npip3 install -r requirements.txt\n\n# System-wide install\nsudo ln -s $(pwd)/netwatch-start.sh /usr/local/bin/netwatch\n\n# Start on boot (optional)\nsudo cp netwatch.service /etc/systemd/system/\nsudo systemctl enable --now netwatch\n```\n\n\u003ca href=\"https://www.digitalocean.com/?refcode=acc36004569d\u0026utm_campaign=Referral_Invite\u0026utm_medium=Referral_Program\u0026utm_source=badge\"\u003e\u003cimg src=\"https://web-platforms.sfo2.cdn.digitaloceanspaces.com/WWW/Badge%203.svg\" alt=\"DigitalOcean Referral Badge\" /\u003e\u003c/a\u003e\n\n## Headless Mode\n\nNo TTY detected (SSH pipe, systemd, Docker) = headless mode. Web dashboard only on `:9090`. All honeypots and traffic monitoring still active.\n\n## Support\n\nNetWatch is built and maintained solo. If it saves you time or protects your network, consider tipping — it keeps the lights on and pays for the tools that go into the next release.\n\n[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?logo=buy-me-a-coffee\u0026logoColor=black\u0026style=for-the-badge)](https://buymeacoffee.com/pr0xy_22)\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmorris-dev%2Fnetwatch-sec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattmorris-dev%2Fnetwatch-sec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmorris-dev%2Fnetwatch-sec/lists"}