How silfius/auditor-ips works
1. System shape
- Auditor IPs is a self-hosted Python web application for private LAN monitoring.
- The repo is organized as a single backend service that serves both HTML pages and a JSON API, packaged for Docker/Docker Compose deployment.
2. Bootstrap and runtime lifecycle
- app/main.py is the main application entrypoint.
- app/config.py, app/database.py, and app/check_startup.py handle environment-driven configuration, persistence setup, and startup validation.
- app/entrypoint.sh and app/dockerfile define container startup behavior; the app is expected to run inside a managed container rather than as scattered system services.
3. Persistence boundary
- The backend has a central database layer in app/database.py.
- Operational data such as hosts, scans, alerts, service status, quality metrics, and configuration state are stored there.
- The repo also implies a filesystem boundary for exports, reports, logs, and deployment artifacts via docker-compose.yml.example, SNAPSHOT_MANIFEST.json, and the docs around backup/restore.
4. Network discovery and inventory pipeline
- Discovery is a dedicated subsystem: app/scan_discovery.py, app/scan_scheduler.py, and app/routers/discovery.py.
- It appears to periodically discover LAN hosts, then feed results into inventory and status views.
- This is the core data flow: network scan → parsed host facts → persisted inventory → UI/API consumption.
5. Enrichment and classification pipeline
- app/device_enrichment.py, app/scan_enrichment_runners.py, app/fingerprint_utils.py, and app/host_classification.py indicate a second-stage pipeline after discovery.
- Hosts are enriched with device metadata, fingerprinted, and classified into types or roles.
- This likely turns raw scan results into more useful operational views like “known host”, “service host”, or other category labels.
6. Domain API/router structure
- The app/routers/ package splits the backend into domains:
- hosts, scans, services, alerts, quality
- daily_report, export_scheduler, config_api
- system_health, scripts_status, syncthing_control
- auth, router_ssh
- This suggests a modular API boundary where each router owns one functional area rather than a monolithic endpoint layer.
7. Authentication and request protection
- app/auth_middleware.py and app/routers/auth.py form the access-control layer.
- The presence of app/templates/login.html indicates user login is part of the system, not just API tokens.
- Protected API routes and internal dashboards are likely gated by middleware/session logic.
8. Frontend delivery
- Server-rendered templates live in app/templates/, while client behavior is in app/static/js/.
- The UI is split into page-specific scripts for dashboard, hosts, scans, services, alerts, quality, config, auth, Syncthing control, and export configuration.
- app/sw.js suggests a service worker for limited offline/cache behavior or improved loading, but the app is still fundamentally a browser-based admin console.
9. External integrations
- app/routers/syncthing_control.py shows an integration with Syncthing Control in read-only mode.
- app/routers/router_ssh.py suggests SSH-based interaction for controlled remote operations or status checks.
- app/routers/services.py and app/routers/scripts_status.py indicate the app also observes internal automation or service processes, not just network devices.
10. Operational visibility and reporting
- app/routers/system_health.py provides health endpoints, and the README highlights /api/system/healthz plus scripts/smoke_system_health.sh.
- app/routers/daily_report.py and app/routers/export_scheduler.py suggest scheduled reporting and export generation.
- app/routers/alerts.py and app/routers/quality.py represent operational feedback loops: detect issues, store them, and present them in the dashboard.
11. Deployment and support tooling
- Deployment is intended through Docker Compose on Linux with writable data paths.
- scripts/install_auditor.py automates installation and setup, while the docs cover install, configuration, backup/restore, upgrade, and security.
- The architecture is therefore closer to an appliance-like self-hosted service than a library or distributed microservice system.
12. How to draw the architecture
- Put the Python backend container at the center.
- On the left, show persistent storage: database plus filesystem for exports/config/logs.
- On the right, show LAN hosts/devices, Syncthing Control, and any SSH-managed targets as external systems.
- At the top, show the browser UI using templates and static JS.
- At the bottom, show Docker/Compose and host OS as the deployment layer, with schedulers running inside the backend for discovery, enrichment, reports, and health checks.
Main entry points: main.py App entry · database.py Database · device_enrichment.py Device enrichment · syncthing_control.py Sync/SSH control
Components 30
Deployment
Containerized runtime and install/compose layer
- Docker/Compose · Container and compose deployment layer
docker-compose.yml.example - Install script · Automated installation and setup helper
scripts/install_auditor.py
Backend Service
Single Python service that serves UI and API
- App entry · Main application entrypoint
app/main.py - Config · Environment-driven application settings
app/config.py - Startup checks · Preflight validation and readiness checks
app/check_startup.py - Auth middleware · Request protection for UI and API routes
app/auth_middleware.py - Hosts · Host inventory and detail views
app/routers/hosts.py - Scans · Scan history and discovery results
app/routers/scans.py - Services · Service status and operational views
app/routers/services.py - Alerts · Alert storage and dashboard views
app/routers/alerts.py - Quality · Data quality and integrity views
app/routers/quality.py - Reports · Daily reporting and export scheduling
app/routers/daily_report.py - System health · Health and readiness endpoints
app/routers/system_health.py - Sync/SSH control · Syncthing read-only control and SSH-based operations
app/routers/syncthing_control.py - Auth · Login and session access flows
app/routers/auth.py
Discovery Pipeline
Scan, enrichment, and classification flow
- Discovery · LAN host discovery and scan parsing
app/scan_discovery.py - Scan scheduler · Periodic scan orchestration
app/scan_scheduler.py - Enrichment runners · Runs post-scan enrichment tasks
app/scan_enrichment_runners.py - Device enrichment · Adds device metadata to discovered hosts
app/device_enrichment.py - Fingerprinting · Host fingerprint utilities for identification
app/fingerprint_utils.py - Classification · Assigns host type or role labels
app/host_classification.py
External Systems
LAN devices and managed integrations
- Browser admin · Human-facing dashboard and login experience
- LAN devices · Discovered hosts and devices on the local network
- Syncthing · Read-only Syncthing control target
- SSH targets · Systems reached through SSH-based control or checks
Persistence
Database and filesystem-backed operational state
- Database · Central storage for hosts, scans, alerts, quality, and config state
app/database.py - Files and exports · Writable filesystem for reports, exports, logs, and snapshots
SNAPSHOT_MANIFEST.json
Browser UI
Server-rendered pages and client scripts
- Templates · HTML pages rendered by the backend
app/templates/index.html - Client JS · Page-specific browser behavior
app/static/js/app.js - Service worker · Client-side caching and load assistance
app/sw.js
Connections 44
- Docker/Compose → App entry: runs · Compose starts the application container
- Install script → Docker/Compose: sets up · Installer prepares the deployment environment
- App entry → Config: loads · Application bootstraps from environment configuration
- App entry → Startup checks: validates · Performs startup checks before serving traffic
- App entry → Auth middleware: enforces · Installs request protection around routes
- App entry → Database: uses · Connects the app to persistent state
- App entry → Templates: serves · Renders HTML pages for the browser UI
- App entry → Hosts: mounts · Exposes host domain endpoints
- App entry → Scans: mounts · Exposes scan domain endpoints
- App entry → Services: mounts · Exposes service status endpoints
- App entry → Alerts: mounts · Exposes alert endpoints
- App entry → Quality: mounts · Exposes quality endpoints
- App entry → Reports: mounts · Exposes reporting and export scheduling
- App entry → System health: mounts · Exposes health endpoints
- App entry → Sync/SSH control: mounts · Exposes integration control endpoints
- App entry → Auth: mounts · Exposes authentication endpoints
- Scan scheduler → Discovery: triggers · Schedules periodic discovery runs
- Discovery → LAN devices: scans · Discovers hosts on the local network
- Discovery → Database: stores · Persists discovered inventory and scan results
- Enrichment runners → Device enrichment: runs · Executes metadata enrichment jobs
- Device enrichment → Fingerprinting: uses · Derives identity signals for hosts
- Device enrichment → Classification: feeds · Turns fingerprints into host categories
- Device enrichment → Database: updates · Writes enriched host state back to persistence
- Hosts → Database: reads/writes · Serves inventory data from persistence
- Scans → Database: reads · Shows scan history and discovery state
- Services → Database: reads · Reads service status and process state
- Alerts → Database: reads/writes · Stores and presents alert data
- Quality → Database: reads/writes · Tracks data quality metrics
- Reports → Database: reads · Builds reports and exports from stored state
- Reports → Files and exports: writes · Generates reports and export artifacts
- System health → Database: reads · Reports backend health and readiness
- Sync/SSH control → Syncthing: controls · Integrates with Syncthing in read-only mode
- Sync/SSH control → SSH targets: queries · Uses SSH-based access for controlled operations
- Templates → Client JS: loads · Pages are enhanced by browser scripts
- Client JS → Browser admin: runs in · Client-side behavior executes in the browser
- Service worker → Browser admin: caches · Provides browser caching and load assistance
- Browser admin → Auth: logs in · Users authenticate through the login flow
- Browser admin → Hosts: views · Operator dashboard consumes host data
- Browser admin → Scans: views · Operator dashboard consumes scan data
- Browser admin → Alerts: views · Operator dashboard consumes alert data
- Browser admin → Quality: views · Operator dashboard consumes quality data
- Browser admin → System health: checks · Browser or probes can verify health endpoints
- Browser admin → Sync/SSH control: operates · Admin UI can drive integration controls
- Files and exports → Database: backs · Operational files complement persisted state