K9

A Rails 8 security dashboard for real-time network visibility and packet recording. Stream live traffic (tcpdump or netstat/ss), record sessions as kibbles, and browse saved recordings (reports).

---

Run quickly with Docker

Prerequisites: Docker and Docker Compose.

# Clone and enter the project
git clone git@github.com:danbickford007/K9.git k9 && cd k9

# Start PostgreSQL, Redis, and the app (builds on first run)
docker compose up --build

# In another terminal, create the database if needed (usually done by entrypoint)
docker compose exec web bin/rails db:prepare

• App: http://localhost:3000
• Health: http://localhost:3000/up

Optional: set POSTGRES_PASSWORD (default postgres) via .env or export.

---

What the app can do

Dashboard (home)

• Security Dashboard at / with cards for:
  • Network Sniffer – live packet/connection stream.
  • Threat Intel – placeholder (coming soon).
  • Reports – saved recordings and kibbles (same list as Recordings).

Live network sniffer

• Sniff (nav or /sniff): real-time stream over ActionCable.
• Uses tcpdump when available (e.g. in Docker with tcpdump installed), otherwise netstat / ss for host-only connections.
• Record starts a new recording (a sniff session); every streamed packet is stored as a kibble for that session.
• Stop ends recording; Clear clears the on-screen list only (does not delete stored kibbles).
• Sniffer stops when you leave the page (no more broadcasts), so navigation stays responsive.

Recordings and kibbles (reports)

• Recordings (nav or /sniffs): list of saved sniff sessions.
• Each recording shows created time and kibbles count (counter_culture).
• View opens a recording; Kibbles lists all stored packets (time, proto, local, remote, state, key, raw line).
• Kibbles store: time, key, proto, local, remote, state, line, and sniff_id.

Background jobs

• Sidekiq for background jobs (e.g. future use).
• Sidekiq Web UI: http://localhost:3000/sidekiq In production, set SIDEKIQ_WEB_USER and SIDEKIQ_WEB_PASSWORD for HTTP Basic Auth.

Tech stack

• Rails 8, PostgreSQL, Redis, ActionCable, Turbo, Stimulus.
• counter_culture keeps each sniff’s kibbles_count in sync with its kibbles.
• Dark “cyber” dashboard theme (Tailwind-style CSS).

---

Run without Docker

Prerequisites: Ruby 3.4+, Node 20+ (and Yarn), PostgreSQL 16, Redis.

# Install dependencies
bundle install
yarn install

# Database and assets
bin/rails db:prepare
yarn build
yarn build:css

# Run app (and optionally Sidekiq in another terminal)
bin/dev
# Or: bin/rails server  and  bundle exec sidekiq

Set in .env or environment:

• DATABASE_URL – PostgreSQL URL (or use config/database.yml).
• REDIS_URL – default redis://localhost:6379/0 for Sidekiq and ActionCable if needed.

---

Optional environment

Variable	Purpose
POSTGRES_PASSWORD	DB password (Docker; default postgres).
REDIS_URL	Redis URL for Sidekiq (default redis://localhost:6379/0).
SNIFF_INTERFACE	tcpdump interface (default any; e.g. en0 on macOS).
SIDEKIQ_WEB_USER / SIDEKIQ_WEB_PASSWORD	Protect /sidekiq in production.

---

Routes overview

Path	Description
/	Dashboard home
/sniff	Live sniffer stream
/sniffs	Recordings list
/sniffs/:id	One recording (with kibbles count)
/sniffs/:id/kibbles	Kibbles for that recording
/sidekiq	Sidekiq Web UI
/up	Health check
/cable	ActionCable WebSocket

---

License

See repository license file.