OrbitWard/docs/progress.md

OrbitWard Progress

Last updated: 2026-05-26

Current State

OrbitWard has a working Docker Compose development stack with PostgreSQL, Redis, FastAPI backend, Python worker, and React/Vite frontend.

Implemented foundation:

• Monorepo layout, README, MIT license, Dockerfiles, Compose files, helper scripts, and initial docs.
• FastAPI backend with health endpoint, JWT login, local initial owner bootstrap, and role checks.
• SQLAlchemy models and Alembic initial migration for users, assets, credentials, monitors, check results, metrics, alert rules, incidents, notification channels, and audit events.
• React frontend with login, authenticated shell, dashboard, assets, websites, alerts, notifications, and placeholder admin/discovery/graphs/credentials pages.
• Worker process that polls HTTP website monitors, records check results, updates monitor/asset status, opens incidents, resolves incidents on recovery, and sends webhook notifications.

Implemented website-monitor slice:

• Create, edit, delete website monitors from the UI.
• HTTP status and expected-text checks.
• Optional TLS certificate expiry checks for HTTPS monitors.
• Monitor status and recent incident visibility on dashboard.
• Basic alert rules created with website monitors.
• Incidents can be acknowledged and silenced from the UI.
• Deleting a monitor resolves any open incidents tied to that monitor.

Implemented network-monitor slice:

• Create, edit, delete ping and TCP port monitors from the UI.
• Worker performs ICMP ping checks and TCP connection checks.
• Ping and TCP monitors use the same alert rule, incident, recovery, and notification flow as website monitors.
• Dashboard monitor status includes website, ping, and TCP monitors.

Implemented notification slice:

• Create, edit, test, and delete notification channels from the UI.
• Generic webhook, Mattermost, and Zoom Team Chat channel types.
• Webhook URLs encrypted at rest using ORBITWARD_SECRET_KEY.
• Saved webhook URLs are not returned to the UI.
• Configurable post username per notification channel.
• Worker sends incident open and recovery notifications.
• Notification state/history is stored in incident details to avoid duplicate sends.

Implemented alerting management slice:

• Alerts page lists alert rules separately from incidents.
• Alert rules can be enabled, disabled, and edited from the UI.
• Editable alert rule fields include friendly name, severity, failure threshold, and cooldown.
• HTTPS website alert rules expose TLS certificate expiry check and warning-day controls.
• Existing simple alert conditions are shown in friendly language instead of raw condition data.
• Worker honors alert rule cooldown before opening a new incident for a recently-triggered rule.

Implemented monitor and notification test coverage:

• Test fixtures isolate API tests with an in-memory database and authenticated owner override.
• Website monitor tests cover asset creation, default alert rule creation, TLS config persistence, and disabled default alerts.
• Notification channel tests verify saved webhook URLs are encrypted and are not returned by create, list, or update responses.
• Worker scheduler tests cover alert threshold incident opening, recovery resolution, notification history deduplication, and alert cooldown behavior.

Implemented SNMP credential profile slice:

• Backend API supports reusable SNMP credential profiles at /credentials/snmp.
• Initial profile support is SNMPv2c community credentials with port, timeout, and retry settings.
• Community strings are encrypted at rest and are not returned by create, list, or update responses.
• Credentials page can create, edit, rotate, and delete SNMP profiles.
• Backend tests cover SNMP profile secret masking, encryption, update preservation, rotation, listing, and deletion.

Implemented SNMP device discovery API slice:

• Backend API supports SNMP device discovery at /discovery/snmp.
• Discovery uses a saved SNMPv2c credential profile and decrypts the community string only server-side.
• Discovery returns friendly device details, interfaces, and monitorable items without raw OIDs.
• Initial monitorable items include device uptime, interface status, interface traffic, and interface errors/discards.
• Backend tests cover successful discovery, missing profiles, unusable secrets, probe failures, secret masking, and raw OID avoidance.

Implemented guided SNMP discovery UI slice:

• Discovery page can run SNMP discovery against a host using a saved SNMP profile.
• UI shows friendly device summary details and discovered interfaces.
• UI displays friendly monitorable item groups and supports selecting items for the next monitor-creation step.
• Normal discovery UI avoids raw SNMP OIDs and saved secret values.

Implemented asset-based monitor setup slice:

• Assets page can create a new asset or select an existing asset before configuring monitors.
• Assets page can delete assets, with confirmation that attached monitors are also removed.
• Asset setup supports choosing ping, TCP, website, and SNMP monitoring in any combination.
• Website, ping, and TCP monitor APIs can attach new monitors to an existing asset without creating duplicate assets.
• Asset setup creates monitors without automatically creating alert rules; alerting remains managed separately.
• SNMP setup can run guided discovery from the asset flow and save selected friendly items as SNMP monitors attached to the asset.
• SNMP monitor creation stores friendly discovery metadata and avoids raw OIDs in normal UI/API responses.

Implemented initial SNMP collection slice:

• Worker includes configured SNMP monitors in the scheduled collection loop.
• Worker loads saved SNMP credential profiles server-side and decrypts community strings only for the collection request.
• SNMP device uptime checks update monitor status and store uptime metrics.
• SNMP interface status checks update monitor status and store admin/operational status metrics.
• SNMP interface traffic checks collect inbound/outbound octet counters and store metrics.
• SNMP interface error checks collect inbound/outbound errors and discards and store metrics.

Implemented SNMP profile mapping slice:

• SNMP discovery selects an internal friendly profile such as Generic SNMP, Linux Server, Proxmox VE Server, Cisco IOS SNMP, or MikroTik RouterOS SNMP from system identity details.
• Discovery reports capability flags for system identity, interfaces, CPU, memory, storage, and sensors.
• Standard HOST-RESOURCES CPU load, memory usage, and disk/storage usage are exposed as friendly monitorable items when supported.
• Standard ENTITY-SENSOR environmental readings are exposed as friendly monitorable items when supported.
• Worker collection supports CPU load, memory usage, storage usage, and sensor value/status monitors created from discovery.
• Raw SNMP implementation details remain internal to profiles and are not returned in the normal discovery UI/API response.

Known Gaps

• General credential vault workflows beyond SNMP profiles are not complete.
• Audit logging tables exist, but events are not consistently written yet.
• User management UI is not implemented.
• Role management is basic and needs full admin flows.
• Richer alert condition editing is not implemented yet.
• SNMP collection now covers uptime, interface status, traffic counters, errors, discards, CPU load, memory usage, storage usage, and standard sensor value/status data. Vendor-private profile mappings beyond common standard MIBs are not implemented yet.
• Notification routing/policies are not implemented; all enabled webhook channels receive incident notifications.
• Email/SMTP notifications are not implemented yet.
• Graphing exists only as placeholders; metric visualization is not implemented.
• Worker scheduling is simple polling, not a Redis queue yet.
• Tests still need frontend coverage and broader edge-case coverage across monitor types.
• Production deployment hardening is not done.

Recommended Next Work

1. Add notification policy/routing controls.
2. Add email/SMTP notification channel.
3. Add audit event writes for auth, monitor, credential, notification, and incident actions.
4. Build general credential vault workflows with masked secret handling.
5. Add user administration UI.
6. Add graphs for website response time and monitor status history.
7. Add richer alert condition editing.
8. Add vendor-private SNMP profile mappings for specific common devices after real device examples are available.
9. Add frontend coverage for monitor, alert, and notification workflows.

Operational Notes

Development URLs:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• API docs: http://localhost:8000/docs

Default local login comes from .env:

• INITIAL_ADMIN_EMAIL=admin@example.com
• INITIAL_ADMIN_PASSWORD=change-me

Change these values before using OrbitWard outside local development.