# kage — changelog

## v1.0.0 — 2026-06-09

First release. `kage` (影, "shadow") is a realtime computer monitoring tool: a
fullscreen TUI dashboard for CPU, memory, disks, network, processes — plus a
live CONNECTIONS pane in orange that blinks for the first 3 s of every new
socket so you can spot a stranger before it gets comfortable. From the TUI,
`b` blocks a remote IP via nftables; `t` trusts it; `K` SIGTERMs the owning
process; `d` does an opt-in reverse-DNS lookup.

Headless mode ships five one-shot subcommands (`snapshot`, `top`, `net`,
`disk`, `connections`) with `-o json` for cron / SSH / pipe use.

### Features
- Fullscreen TUI dashboard with seven panes: host header, CPU (per-core +
  load + 60 s sparkline), MEMORY (used + swap + cache + sparkline), DISK
  (mounts + used/total + r/w rates), NETWORK (interfaces + bandwidth +
  sparkline), CONNECTIONS (orange, blink-on-new, 3 s window), PROCESSES
  (sortable).
- Connection direction inference (inbound / outbound / listen) with
  per-row colouring: orange = new, dim grey = listen, red = blocked, green
  = trusted, REVERSED = blinking new.
- Process-owner column (`ss -tunaHp` joined with /proc/[pid]).
- Per-IP block via `nft` with iptables fallback. Session-only by default;
  `--persist` writes to /etc/nftables.d/kage.nft so blocks survive reboot.
- Trust list + block list at `~/.config/kage/{trust,block}.json`.
- Public-IP lookup via Cloudflare DoH — OFF by default (privacy); `--doh`
  to enable.
- Block / unblock / kill require `--i-am-authorized` (suite consent
  convention, separate from `--full` which is display-only / extended help).
- `kage snapshot` produces text or JSON for SSH / cron / pipe consumers.
- `kage top --by cpu|mem|pid|name -n <N>` focused process table.
- `kage net`, `kage disk`, `kage connections [--filter X]` one-shot panels.
- Signature footer mandatory on every output:
  `[ kage ] ─ an independent project by johlem.net`.
- Zero runtime dependencies (Rust binary, dynamically linked glibc).

### Touches / Produces / Gates
- Touches: read-only /proc, /sys, /etc/passwd, `ip`, `ss -tunaHp`. With
  `--doh`, one HTTPS query to 1.1.1.1.
- Touches (write actions, `--i-am-authorized` only): `nft` rules,
  `/etc/nftables.d/` (with `--persist`), `kill(2)`, `~/.config/kage/`.
- Produces: terminal output, JSON, and persistent trust/block books.
- Gates: `--i-am-authorized` required for block / unblock / kill.
  `--persist` additionally requires root (or CAP_NET_ADMIN) to write
  `/etc/nftables.d/kage.nft`. `--full` is display-only.