Tech Debt & Limitations
Relevant source files
The following files were used as context for generating this wiki page:
Honmoon is an early-stage project that explicitly documents its limitations and technical debt to maintain transparency—a core requirement for a security-focused tool. While the policy engine and basic egress proxy are functional, several critical components remain in a "scaffold" or "advisory" state as the project moves through its phased roadmap.
The project tracks technical debt using a formalized numbering system (TD-001 through TD-006), identifying items that impact maintainability, isolation strength, and feature completeness. Understanding these limitations is essential for contributors and users evaluating the system's current production readiness.
Sources: wiki/deep-dive/roadmap-open-core.md, .please/docs/tracks/tech-debt-tracker.md:1-15
Core Technical Debt Items
The project maintains a central tracker for architectural and implementation debt. These items represent planned refactors or missing integrations that are necessary for long-term stability.
| ID | Title | Priority | Impact |
|---|---|---|---|
| TD-001 | Dual Policy Model Sync | Medium | Risk of drift between Rust and TypeScript policy implementations. |
| TD-002 | Deprecated YAML Library | Low | serde_yaml is deprecated; requires migration to serde_yml. |
| TD-003 | Lack of Network Isolation | High | honmoon run isolation is advisory (env-vars) rather than enforced (netns). |
| TD-004 | CONNECT Proxy Visibility | Medium | Limited to host-level rules; path/body rules require TLS termination. |
| TD-006 | Live Protocol Relay | High | Parsers exist but are not yet driven by live socket traffic. |
Sources: .please/docs/tracks/tech-debt-tracker.md:9-14, wiki/deep-dive/roadmap-open-core.md
TD-001: Dual Model Synchronization
Currently, the policy model is defined twice—once in Rust (honmoon-core) and once in TypeScript (@honmoon/policy). Changes to the policy structure require manual updates in both languages to prevent silent divergence. The planned resolution is to generate both models from the central JSON Schema.
Sources: ARCHITECTURE.md:95-97, wiki/deep-dive/architecture.md, wiki/onboarding/contributor-guide.md
TD-006: Protocol Parsing Integration
While Honmoon features robust wire-level parsers for PostgreSQL and Kubernetes, these are currently "engine-complete" but not "traffic-driven." They are verified via extensive unit tests but are not yet connected to a live inline TCP relay.
Sources: wiki/deep-dive/protocol-parsing.md, wiki/onboarding/staff-engineer-guide.md
The diagram shows that the connection between live sockets and the protocol parsers is currently a missing link (TD-006).
Sources: wiki/deep-dive/protocol-parsing.md, wiki/onboarding/staff-engineer-guide.md
Implementation Limitations
Advisory Isolation (TD-003)
The honmoon run command currently operates in an "advisory" capacity. It functions by setting standard proxy environment variables (e.g., HTTPS_PROXY) for the child process.
- Risk: A process that is hardcoded to ignore environment variables or uses custom networking libraries can bypass the gateway entirely.
- Resolution: True enforcement via network namespaces (Linux
netns) or macOS NetworkExtensions is a Phase 5 goal.
Sources: wiki/getting-started/overview.md, wiki/onboarding/executive-guide.md, .please/docs/tracks/tech-debt-tracker.md:11
Visibility Constraints (TD-004)
The current Phase 1 implementation uses a standard HTTP CONNECT proxy. This design has inherent visibility limitations:
- Encrypted Payloads: The proxy sees the initial
CONNECT host:portrequest but cannot inspect the subsequent encrypted TLS stream. - Rule Impact: Protocol rules requiring inspection of HTTP paths, methods, or bodies (e.g.,
http.method == 'POST') do not fire over CONNECT tunnels. Only host-level egress rules are functional for HTTPS.
Sources: wiki/onboarding/staff-engineer-guide.md, wiki/deep-dive/roadmap-open-core.md, .please/docs/tracks/tech-debt-tracker.md:12
Architectural Status Map
The project explicitly categorizes modules based on their stability and completeness to guide contributors.
| Stable & Well-Tested | Fragile or Incomplete |
|---|---|
Policy Model & decide() | honmoon run Isolation (TD-003) |
| SQL/K8s Parsers (Logic) | honmoon join (Stub/Bail) |
| CONNECT Proxy & Approvals | Live Protocol Relay (TD-006) |
| Audit Log & Dashboard | honmoonctl validate (Stub) |
Sources: ARCHITECTURE.md:123-131, wiki/deep-dive/architecture.md
This diagram illustrates the functional path (Egress) vs the incomplete path (Protocol Parsing) for live traffic.
Sources: wiki/deep-dive/architecture.md, wiki/onboarding/staff-engineer-guide.md
Conclusion
The technical debt in Honmoon is a byproduct of its phased development approach. While the core decision engine and egress filtering are high-quality and production-ready for basic use cases, the project's more advanced "protocol-aware" features are currently restricted by the lack of a live socket relay (TD-006) and hardened process isolation (TD-003). Developers should treat the system as an advisory guardrail until Phase 5 isolation is implemented.
Sources: wiki/onboarding/executive-guide.md, wiki/deep-dive/roadmap-open-core.md