Secure legacy command API and centralize health catalogue

Problem Statement

The legacy /api/command endpoint accepts caller-supplied command strings and executes them through the legacy execution path. Validation rejects selected shell composition, but the endpoint is still enabled without authentication and could become an unauthenticated shell boundary if the service is exposed beyond the local host.

The health route also retains a route-local tool catalogue while using the extracted ToolRegistry, creating two sources of truth for tool totals and availability.

Solution

Make the legacy Command API an explicitly enabled, authenticated, loopback-only compatibility capability. Preserve existing execution, cache, timeout, telemetry and response behavior for valid authorized requests while denying access safely by default.

Make ToolRegistry the sole owner of the canonical tool catalogue and availability snapshot. The health route must consume one coherent registry snapshot and preserve the existing JSON response shape while deriving counts from that snapshot.

User Stories

1. As an infrastructure operator, I want the legacy Command API disabled by default, so that a fresh deployment does not expose command execution.
2. As an infrastructure operator, I want to enable the legacy Command API explicitly, so that existing local integrations can continue during migration.
3. As an infrastructure operator, I want enabling the API without a configured token to fail safely, so that the service never runs an unauthenticated command boundary.
4. As an infrastructure operator, I want the enabled API restricted to loopback exposure, so that it cannot be exposed to a LAN or remote node accidentally.
5. As an authorized local client, I want to authenticate with a dedicated command token, so that only approved callers can use the compatibility endpoint.
6. As an unauthorized client, I want a stable authentication error, so that rejected credentials are distinguishable from malformed commands.
7. As an operator, I want a disabled endpoint not to advertise its operational existence, so that default deployments disclose less management surface.
8. As an authorized client, I want valid legacy command requests to preserve the existing result contract, so that migration does not break current consumers.
9. As an operator, I want shell composition to remain rejected after authentication, so that authentication does not make arbitrary shell syntax acceptable.
10. As an operator, I want timeout, cache, telemetry and legacy process behavior preserved, so that the boundary does not remove operational safeguards.
11. As an operator, I want request identifiers and outcomes audited without secrets, so that command API use can be investigated safely.
12. As an infrastructure operator, I want one canonical tool catalogue, so that health data has a single source of truth.
13. As an operator, I want health totals and category counts from the same availability snapshot, so that one response cannot combine different probes.
14. As an operator, I want an individual tool probe failure represented as that tool being unavailable with diagnostic context, so that one broken executable does not fail the whole health endpoint.
15. As an operator, I want the legacy health JSON shape preserved, so that existing monitoring clients continue to parse it.
16. As a developer, I want unit, HTTP and ARM64 tests for the security and registry contracts, so that deployment-specific regressions are visible.

Implementation Decisions

• Use the existing application configuration seam for command API enablement and its dedicated token.
• Treat a missing or empty token as absent; provide no file, default or anonymous fallback.
• If enablement is requested without a token, fail safely during configuration/bootstrap.
• Permit enablement only when the configured server host is loopback (127.0.0.1 or localhost). Non-loopback enablement is a configuration error in this phase.
• Use X-HexStrike-Command-Token and constant-time comparison. Never log the token.
• Return 404 when disabled, 401 for a missing/invalid token and 400 for malformed input or rejected shell composition.
• Preserve the current authorized execution path and its cache, timeout, telemetry, process registration and result behavior.
• Retain rejection of shell composition including separators, pipelines, redirections, substitutions and newlines.
• Audit request identifier, timestamp, outcome, rejection reason where applicable, duration and HTTP status. Do not log the raw token or complete command; a non-reversible command hash may be used.
• Make ToolRegistry the sole owner of the canonical catalogue and remove route-local lists and duplicate count calculations.
• Use one registry availability snapshot for total tools, available tools, essential status and category statistics.
• Isolate probe failures to the affected tool as unavailable with structured diagnostic information.
• Preserve legacy health field names and JSON shape.
• Do not introduce a new microservice or HTTP layer; use the existing application boundary, compatibility route and extracted health registry.
• Respect ADR 0001.

Testing Decisions

Tests must exercise externally observable behavior through the highest existing seams and avoid private implementation assertions.

• Test configuration defaults, enablement, token presence and loopback validation.
• Test disabled (404), missing/invalid token (401), valid token, malformed input (400) and shell rejection (400).
• Verify rejected requests do not invoke execution.
• Verify an authorized valid request preserves compatibility behavior.
• Verify audit entries contain request identifiers and outcomes but no raw token or full command.
• Test coherent health snapshots, canonical counts, category counts and isolated probe failures.
• Add a regression check that the route has no independent catalogue.
• Run python3 -m unittest discover -v, compilation checks, docker compose config -q and ARM64 container verification.

Out of Scope

• Replacing the legacy command endpoint with the future structured tool API.
• LAN, VPN, public or remote command execution; TLS; external identity; RBAC; token rotation.
• Changing the legacy execution engine beyond boundary integration.
• Adding tools or changing catalogue contents.
• Management API versioning, CLI, dashboard, AI orchestration, local LLM, remote Kali and results ingestion.
• Penetration testing or unauthorized target execution.

Further Notes

The host Python environment may lack Flask; route verification should use the ARM64 container. After implementation update project state and roadmap, run wiki validation if available, and perform a two-axis review against the pre-change baseline.