Get up and running

Requirements

• Docker 24 or newer (with the daemon running)
• Docker Compose v2 (the docker compose plugin)
• curl and openssl (used by the installer to download the compose file and generate secure keys)
• A Linux host on the network you want to monitor — x86-64 or ARM64 (Raspberry Pi 3/4/5, 64-bit)
• A flat Layer-2 LAN for full ARP discovery and blocking

Installation (recommended)

The fastest way to install InSpectre is the one-line installer. It simply downloads and runs inspectre-install.sh — there is no need to clone the repository or build anything. The script pulls the pre-built images straight from Docker Hub.

curl -fsSL https://raw.githubusercontent.com/thefunkygibbon/InSpectre/main/inspectre-install.sh | bash

The installer will:

• Verify all prerequisites (Docker, Docker Compose v2, curl, openssl) and that the Docker daemon is running
• Detect your CPU architecture and ask whether to install x64 or Raspberry Pi images (pulling the latest or raspi image tags accordingly)
• Prompt for an install directory and download docker-compose.deploy.yml
• Generate a strong database password and a JWT secret key automatically
• Optionally let you set IP_RANGE and INTERFACE (otherwise auto-detected)
• Write a .env file and start the whole stack with docker compose up -d

When it finishes, open http://localhost:3000 (or the host's IP) and complete the first-run setup wizard.

Manual deployment (advanced)

If you'd rather not use the installer, you can deploy the pre-built Docker Hub images by hand. Set INSPECTRE_TAG=raspi on a Raspberry Pi / ARM64 host, or leave it as latest for x86-64.

# 1. Download the deploy compose file
curl -O https://raw.githubusercontent.com/thefunkygibbon/InSpectre/main/docker-compose.deploy.yml

# 2. Edit — change POSTGRES_PASSWORD and SECRET_KEY
#    Generate a key: openssl rand -hex 32

# 3. (Raspberry Pi only) select the ARM64 images
#    echo "INSPECTRE_TAG=raspi" >> .env

# 4. Start
docker compose -f docker-compose.deploy.yml up -d

Updating

docker compose -f docker-compose.deploy.yml pull
docker compose -f docker-compose.deploy.yml up -d

Building from source (developers)

Only needed if you want to modify and rebuild the images yourself. Clone the repository and use the bundled helper script:

git clone https://github.com/thefunkygibbon/InSpectre.git
cd InSpectre
./inspectre.sh up

First run & setup wizard

On first launch InSpectre walks you through a guided wizard — no file editing required. You'll configure:

• An admin username and password (JWT-backed login, with an optional 30-day "remember me")
• Network settings — scan range and DNS (auto-detected from the host's routing table)
• Vulnerability scanning behaviour and the nightly scan window
• Notifications — channels and profiles
• Container hosts (Docker / Proxmox) and Fingerbank device identification

Helper commands

Device discovery

The privileged probe container discovers devices two ways at once:

• Active ARP sweeps across your subnet on a configurable interval (default: every 60 s)
• Passive packet sniffing that catches devices the moment they talk on the wire — no wait for the next cycle

New devices surface within seconds and float to the top of the dashboard with a NEW badge until you acknowledge them. Devices sharing a hostname are automatically grouped as one physical device with multiple interfaces — and any group you create or edit by hand is protected from the automatic grouping passes.

For each discovered device, the probe attempts hostname resolution via reverse DNS, mDNS/Bonjour, NetBIOS, and DHCP Option 12.

Device management

The main dashboard offers three layout views: Grid, List, and Category (devices grouped by automatically detected type). Your preference is saved across sessions.

Click any device to open its drawer with tabs for Overview, Actions, Vulnerabilities, Traffic, Timeline, and Admin. From here you can:

• Set a custom name, device type, vendor, location, tags, and zone
• Star devices as Watched for elevated offline alerts
• Ignore benign devices to hide them from the main view
• Add free-text Notes
• View full IP history and event timeline
• Manage device grouping and group membership

The Device Presence page shows multi-device uptime history bars over 7 days, 1 month, or 1 year. The Network Events page shows a chronological log of all online/offline transitions across every device.

Person presence

The Person Presence page groups a household member's devices under one named person:

• Add a person, upload a photo, and attach their devices via autocomplete
• Star one device as the primary presence indicator
• See a clear, colour-coded At Home / Away state plus a presence-history timeline
• Block all of a person's devices in one action, or attach recurring per-person block schedules
• Route arrived-home, left-home, blocked and unblocked events to notifications

Fingerprinting & identity

InSpectre classifies devices using a layered fingerprinting approach:

• OUI lookup — MAC vendor resolution from the IEEE OUI database
• DHCP passive capture — hostname (Option 12), vendor class ID (Option 60), and parameter request list (Option 55) from DHCP broadcasts
• Local DHCP classification — known vendor class patterns matched locally without sending data anywhere
• Port pattern matching — device type inferred from open port signature
• Fingerbank cloud lookup — optional; sends DHCP fingerprint data to fingerbank.org for deeper identification (free, 600 lookups/hour)

Port scanning & baseline tracking

• Port scanning — nmap TCP sweeps with OS detection and service fingerprinting, on demand or scheduled
• Baseline drift — InSpectre alerts when a device's open ports change from its known baseline
• Configure nmap arguments, scan interval, and scheduled scan window from Settings → Scanner

Vulnerability scanning

• Nuclei + nmap CVE scanning — nmap -sV fingerprints services, then Nuclei templates are routed per service; findings surface by severity (Critical / High / Medium / Low)
• Scheduled scans — configurable nightly window or manual trigger per device
• Security dashboard — network-wide view of findings grouped by severity, including container image CVEs from Trivy

Device blocking & schedules

InSpectre blocks devices using ARP MITM — no inline gateway required on a typical home network.

• Per-device — block/unblock from the device card or its Actions tab
• Network pause — cut every device off at once from the toolbar
• Block schedules — recurring time windows (e.g. 22:00–07:00) per device or per person

Traffic monitor

The Traffic Monitor uses ARP MITM to intercept and analyse traffic for a specific device — packets are forwarded to their destination, only observed. Open the device drawer → Traffic tab → Start monitoring.

Speed test

The Speed Test panel (Traffic page → Speed Test section) runs the Ookla Speedtest CLI from the probe and reports download/upload speeds and ping. Results reflect the speed available to the InSpectre host.

• Server selector — optionally pick a specific test server; closest servers are shown first
• Scheduled auto-runs — every 30 min, hourly, every 6 h, or daily — set via the gear icon (⚙)
• History — all results stored and displayed with timestamp, server, ping, download, and upload; included in full JSON backups

Container monitoring

InSpectre can monitor Docker hosts and Proxmox VE nodes alongside your network devices. Configure hosts at Settings → Container Hosts.

• Multi-host support — local Docker socket, remote TCP, and Proxmox VE nodes simultaneously
• Container management — view running/stopped containers, start/stop/restart with one click
• Log streaming — live container log tailing directly from the UI
• Image vulnerability scanning — Trivy-based CVE scanner; findings grouped by severity with CVSS scores and NVD links
• Host filter — filter the container list by configured host

Network tools

The Network Tools page provides 25 diagnostic utilities that run from the probe container — giving you the perspective of a device on your LAN.

Notifications

Notifications use a profiles model: a channel is a reusable connection (service type + credentials); a notification profile maps event types to one or more channels.

Supported channel types (16): ntfy, Gotify, Pushbullet, Pushover, Slack, Telegram, Discord, Email (SMTP), Matrix, Microsoft Teams, Signal, WhatsApp, MQTT, IFTTT, Webhook, and Home Assistant.

Event types include new device, device online/offline, watched-device offline, port drift, vulnerability found, device blocked/unblocked, and the person-presence events (arrived home, left home). Each channel has a one-click Test button.

InSpectre can also publish entities to Home Assistant via MQTT auto-discovery — a system device plus per-client presence, new-device, IP, open-port and vulnerability sensors.

Settings reference

Almost everything is configured from the Settings panel at runtime — no restarts needed. The probe re-reads scan settings each cycle.

Backup & restore

Export a full JSON backup covering devices, events, vuln reports, speed-test history, settings, users, fingerprints, block schedules and saved views. Backups can be AES-256-GCM encrypted with a password, and restored from either the setup wizard or the Settings panel.

• Go to Settings → Data → Backup to download a backup
• Go to Settings → Data → Restore or use the setup wizard to import a backup
• Speed test history and person presence data are included in the backup

Plugins

InSpectre supports a declarative plugin system for extending functionality beyond the built-in feature set. Manage plugins at Settings → Plugins.

• Built-in plugins — ship with InSpectre; maintained by the project; can be enabled/disabled but not removed (AdGuard Home, Pi-hole, TP-Link Omada, Home Assistant, OPNsense, pfSense)
• Community plugins — third-party manifests; upload via Settings → Plugins → Upload Plugin

Configuration overrides

Almost everything is configured at runtime via the Settings panel. If interface auto-detection picks the wrong NIC, override it in docker-compose.yml (or docker-compose.deploy.yml):

# Uncomment to override auto-detection
IP_RANGE: "192.168.1.0/24"
INTERFACE: "eth0"
LAN_DNS_SERVER: "192.168.1.1"

The UI updates live over a Server-Sent Events stream (backed by polling), so most changes appear without a full-page refresh.

Architecture

InSpectre runs as four coordinated containers:

Nothing leaves your LAN unless you enable an outbound integration (e.g. Fingerbank or a notification channel).