monoadmin/the-other-dude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
655f1eadaeac9a42d52736a14ee7b8a642033258
the-other-dude/.planning/REQUIREMENTS.md
Jason Staack 655f1eadae feat(20-02): add parse-mib and test-profile API endpoints 
- POST /snmp-profiles/parse-mib: upload MIB file, subprocess-call tod-mib-parser, return OID tree JSON
- POST /snmp-profiles/{id}/test: test profile connectivity via NATS discovery probe to poller
- New snmp_proxy service module following routeros_proxy.py lazy NATS pattern
- Pydantic schemas: MIBParseResponse, ProfileTestRequest, ProfileTestResponse, ProfileTestOIDResult
- MIB_PARSER_PATH config setting with /app/tod-mib-parser default
- MIB parse errors return 422, not 500; temp file cleanup in finally block

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-21 20:21:08 -05:00

8.3 KiB
Raw Blame History

Requirements: TOD v9.8 — SNMP Device Integration

Defined: 2026-03-21 Core Value: Operators can monitor their entire network fleet — MikroTik and SNMP devices side by side — from a single pane of glass Design Spec: docs/superpowers/specs/2026-03-21-v98-snmp-integration-design.md

v9.8 Requirements

Foundation

  • FOUND-01: Device model supports a device_type discriminator (routeros vs snmp) with backward-compatible defaults
  • FOUND-02: Database schema includes snmp_profiles table with system-shipped profiles and tenant-custom profiles
  • FOUND-03: Database schema includes unified credential_profiles table supporting routeros, snmp_v2c, and snmp_v3 credential types
  • FOUND-04: Database schema includes snmp_metrics hypertable for custom OID time-series data with 90-day retention
  • FOUND-05: Poller Collector interface abstracts device-type-specific collection (RouterOS and SNMP implementations)
  • FOUND-06: Existing PollDevice logic refactored into RouterOSCollector without behavior changes

Credential Management

  • CRED-01: Operator can create a credential profile (RouterOS or SNMP) with encrypted storage via OpenBao Transit
  • CRED-02: Operator can assign a credential profile to one or many devices instead of per-device credentials
  • CRED-03: Updating a credential profile propagates new credentials to all linked devices on next poll cycle
  • CRED-04: Poller resolves credentials via fallback: per-device credentials first, then credential profile
  • CRED-05: CredentialCache refactored to GetRawCredentials with type-specific parsers (RouterOS, SNMPv2c, SNMPv3)

SNMP Polling

  • POLL-01: Poller can poll SNMP devices using gosnmp with SNMPv1, v2c, and v3 support
  • POLL-02: SNMP collection is profile-driven — device profile defines which OIDs to collect per poll group
  • POLL-03: Standard SNMP metrics (ifXTable, hrStorageTable, hrProcessorLoad) map to existing hypertables (interface_metrics, health_metrics)
  • POLL-04: Custom OID data publishes as SNMPMetricsEvent and inserts into snmp_metrics hypertable
  • POLL-05: Counter32/Counter64 delta computation with Redis cache, including wraparound detection and sanity threshold
  • POLL-06: Profile cache refreshes from database periodically without per-device DB queries
  • POLL-07: SNMP devices use same scheduler, circuit breaker, Redis locks, and NATS pipeline as RouterOS devices

Device Profiles

  • PROF-01: TOD ships 6 system default profiles (generic-snmp, network-switch, network-router, wireless-ap, ups-device, mikrotik-snmp)
  • PROF-02: Auto-detection probes sysObjectID via NATS request-reply and suggests matching profile
  • PROF-03: Operator can create custom SNMP profiles with arbitrary OID collections grouped by poll group
  • PROF-04: Operator can upload vendor MIB files and browse parsed OID tree to select collection targets
  • PROF-05: Operator can test a profile against a live device before saving

Device Management

  • MGMT-01: Operator can add a single SNMP device with IP, SNMP version, credential (profile or manual), and device profile
  • MGMT-02: Operator can bulk-add RouterOS devices using a credential profile + IP list (one per line, CIDR, or range)
  • MGMT-03: Operator can bulk-add SNMP devices using a credential profile + IP list with auto-detected profiles
  • MGMT-04: Subnet scan discovers both RouterOS and SNMP devices with protocol-specific credential profiles
  • MGMT-05: Bulk add returns per-device results (success/failure with reason) and supports partial success

Fleet UI

  • UI-01: Fleet table shows SNMP devices alongside MikroTik devices with type icon, status, CPU, memory, uptime
  • UI-02: Fleet table supports filtering by device type (All / RouterOS / SNMP)
  • UI-03: Device detail page conditionally renders sections based on device_type (no RouterOS-only sections for SNMP devices)
  • UI-04: SNMP device detail shows system info, interface metrics, health metrics, and custom OID charts
  • UI-05: Add Device dialog has tabs for RouterOS, SNMP, and VPN with credential profile selectors
  • UI-06: Credential profile management page lists, creates, edits, deletes profiles for both types
  • UI-07: SNMP profile editor with OID tree browser, MIB upload, poll group configuration

Metrics & Data

  • DATA-01: SNMP interface metrics (rx_bytes, tx_bytes, rx_bps, tx_bps) stored in existing interface_metrics hypertable
  • DATA-02: SNMP health metrics (CPU, memory, disk) stored in existing health_metrics hypertable
  • DATA-03: Custom SNMP metrics stored in snmp_metrics hypertable with metric_name, metric_group, oid, and value
  • DATA-04: SNMP metrics API returns time-bucketed data in same format as existing metrics endpoints
  • DATA-05: Frontend charts for interface traffic and health work identically for SNMP and RouterOS devices

Backward Compatibility

  • COMPAT-01: All existing RouterOS device functionality works unchanged after v9.8 migration
  • COMPAT-02: Existing API responses maintain shape (new fields are additive only)
  • COMPAT-03: Existing NATS event types and subjects are unchanged
  • COMPAT-04: 500+ mixed MikroTik/SNMP devices can be polled without performance degradation

Future Requirements (v9.9+)

SNMP Traps

  • TRAP-01: TOD receives and processes SNMP traps/informs
  • TRAP-02: Trap events surface in the UI alongside polled metrics
  • TRAP-03: Trap deduplication and rate limiting per device

Extended Monitoring

  • EXT-01: SNMP SET operations for device configuration
  • EXT-02: sFlow/NetFlow/IPFIX collection
  • EXT-03: Multi-protocol devices (RouterOS API + SNMP on same device)

Extensibility

  • EXTENS-01: External check executor (run scripts, parse output)
  • EXTENS-02: Nagios plugin output format support
  • EXTENS-03: Telegraf input plugin execution

Out of Scope

Feature Reason
SNMP SET operations Read-only monitoring for v9.8; write operations are vendor-specific
SNMP trap/inform reception Requires listening server, firewall changes — deferred to v9.9
SNMP device config backup No standard SNMP mechanism exists
Nagios plugin execution Trivially simple but not core to SNMP milestone — v10 extensibility
sFlow/NetFlow/IPFIX Separate monitoring domain, v10+
Multi-protocol devices One device_type per device for v9.8 simplicity
SNMP device firmware management No standard mechanism, vendor-specific

Traceability

Requirement Phase Status
FOUND-01 Phase 16 Complete
FOUND-02 Phase 16 Complete
FOUND-03 Phase 16 Complete
FOUND-04 Phase 16 Complete
FOUND-05 Phase 16 Complete
FOUND-06 Phase 16 Complete
CRED-01 Phase 17 Complete
CRED-02 Phase 17 Complete
CRED-03 Phase 17 Complete
CRED-04 Phase 16 Complete
CRED-05 Phase 16 Complete
POLL-01 Phase 18 Complete
POLL-02 Phase 18 Complete
POLL-03 Phase 18 Complete
POLL-04 Phase 18 Complete
POLL-05 Phase 18 Complete
POLL-06 Phase 18 Complete
POLL-07 Phase 18 Complete
PROF-01 Phase 18 Complete
PROF-02 Phase 18 Complete
PROF-03 Phase 20 Pending
PROF-04 Phase 20 Pending
PROF-05 Phase 20 Pending
MGMT-01 Phase 19 Complete
MGMT-02 Phase 19 Complete
MGMT-03 Phase 19 Complete
MGMT-04 Phase 19 Complete
MGMT-05 Phase 19 Complete
UI-01 Phase 19 Complete
UI-02 Phase 19 Complete
UI-03 Phase 19 Complete
UI-04 Phase 19 Complete
UI-05 Phase 19 Complete
UI-06 Phase 19 Complete
UI-07 Phase 20 Pending
DATA-01 Phase 18 Complete
DATA-02 Phase 18 Complete
DATA-03 Phase 18 Complete
DATA-04 Phase 17 Complete
DATA-05 Phase 19 Complete
COMPAT-01 Phase 16 Complete
COMPAT-02 Phase 16 Complete
COMPAT-03 Phase 16 Complete
COMPAT-04 Phase 18 Complete

Coverage:

  • v9.8 requirements: 44 total
  • Mapped to phases: 44
  • Unmapped: 0

Requirements defined: 2026-03-21 Last updated: 2026-03-21 after roadmap creation

Reference in New Issue View Git Blame Copy Permalink