Sprint 1: Reverse-engineer HMM web API (blocks all Phase 5 work)

[marcos-mendez]

Goal: capture every HMM web API endpoint the Java/Palemoon GUI uses, so we can build a typed Python SDK without guessing.

This is the single blocking dependency for Sprints 2–5 of Phase 5. Until it is done, the SDK and IaC providers cannot be written without reverse-engineering one operation at a time.

Why now

The HMM exposes some operations through Redfish (mostly read-only inventory). The actual menus operators use — Stateless Computing, easyLink, Bulk Upgrade, Alarms, Switch profiles, NIC profiles — are served by a chassis-private JSON-over-HTTPS API that the Palemoon UI consumes. We need to document this API completely.

Method

1. Workstation setup (operator side):

   • Install mitmproxy (uvx mitmproxy) or use Chrome DevTools Network tab in Palemoon.
   • Trust mitmproxy CA in Palemoon if using TLS interception.
   • Set Palemoon proxy to http://127.0.0.1:8080.

2. Operator workflow:

   • Log into HMM web UI.
   • For each operation in the checklist below: do it once with mitmproxy/DevTools recording.
   • Save the resulting flow file (mitmproxy save_flows) or HAR export.

3. Documentation:

   • One markdown doc per HMM menu under docs/hmm-api/ (e.g. chassis-settings.md, stateless.md, easylink.md, upgrade.md).
   • Each endpoint entry must include:
     • Method + path + query params
     • Request headers (auth token format, CSRF)
     • Request body schema (with example values, redacted)
     • Response schema (with example values, redacted)
     • Side effects (does it write? trigger reboot? long-running?)
     • Idempotency notes
   • Output draft OpenAPI spec at docs/hmm-api/openapi.yaml.

Capture checklist (priority order)

Priority 1 — Networking (drives Sprints 3-4)

• List all switches (with model, serial, FW version)
• Get switch detail (Swi2)
• easyLink → Switch Profile — list, create, edit, delete
• easyLink → NIC Profile (vNIC) — list, create, edit, delete
• Stateless Computing → MAC Address Pool — list, create, allocate, release
• Stateless Computing → UUID Resource — list, allocate
• easyLink Network Info → Overview (data source)
• easyLink Network Info → Ethernet Plane Info
• easyLink Network Info → MAC Address Info

Priority 2 — Bulk Firmware (drives Sprint 3)

• System Mgmt → Upgrade → MMs — list current FW, upload image, apply
• System Mgmt → Upgrade → Compute Nodes — list, upload, apply (one blade)
• System Mgmt → Upgrade → Switch Modules — list, upload, apply
• System Mgmt → Upgrade → Fans — list, upload, apply
• Upgrade progress polling endpoint
• Upgrade rollback / cancel endpoint

Priority 3 — Compute / Stateless (drives Sprint 5)

• List all blades with state (power, FW versions, profile assignment)
• Stateless Computing → Profile — list, create, edit, delete, assign-to-blade
• Stateless Computing → Node Resource — query
• Per-blade detail (BIOS settings, boot order, vNIC bindings)
• Power on / off / reset / cycle (per-blade)
• BIOS Boot Device (one-shot + persistent)

Priority 4 — Inventory & monitoring (drives Sprint 2 SDK + audit)

• Chassis Settings → Basic Settings (read + write)
• Chassis → list FC Ports
• PSUs & Fans → Power Meter (data source)
• PSUs & Fans → Power Capping (read + write)
• PSUs & Fans → Power Records
• Alarm Monitoring → list active alarms (with filtering)
• Alarm Monitoring → Alarm Settings (subscriptions)
• System Mgmt → Log Information → System Logs (paged)
• System Mgmt → Log Information → Operation Logs

Priority 5 — Auth & users

• Login flow (CSRF + session cookie or token format)
• System Mgmt → Account → MM Users (CRUD)
• System Mgmt → Account → LDAP config
• System Mgmt → Account → Two-Factor Authentication
• Logout
• Session refresh / heartbeat

Priority 6 — Diagnostics for HMM behaviour

• Chassis Settings → Black Box (event log dump)
• Information Collection (full diagnostic bundle)
• Configuration Restore endpoint

Acceptance criteria

• Every checklist item above either has a documented endpoint in docs/hmm-api/<menu>.md, or is annotated "not exposed via HMM web API — use Redfish/SSH" with the alternative.
• docs/hmm-api/openapi.yaml validates with openapi-spec-validator.
• The captured .mitmproxy or .har flow files are committed (with redacted tokens) under re/captures/hmm-web-api/.

Estimate

1 week of operator-driven capture + 2-3 days of doc cleanup.

Blocks

• Implement hmm-snapshot CLI #4 (hmm-snapshot — needs alarm + log + account endpoints)
• Implement hmm-restore <snapshot> CLI #5 (hmm-restore — needs Configuration Restore endpoint)
• CX310 mgmt SSH access + VRP CLI wrapper #11 / VLAN CRUD with snapshot + watchdog rollback #12 (some VLAN ops may go through HMM rather than direct CX310 SSH)
• All Phase 5 sprints