docs: add security audit reports

2026-06-24 09:47:59 +01:00
parent 3a16a14d6e
commit 614f87b8f2
2 changed files with 440 additions and 0 deletions
@@ -0,0 +1,79 @@
+# Functionality and Next Steps Report
+
+## 1. Executive Summary
+
+This fix-mode pass improved VS Code extension robustness by hardening the local bridge and webview CSP handling. The highest-impact next step is runtime validation in a real VS Code host: the source-level tests pass, but the extension panels and long-lived bridge event stream deserve manual smoke coverage after the HTTP timeout and nonce changes.
+
+The codebase already has useful regression coverage for prior security fixes. The main opportunity now is to reduce duplicated webview HTML patterns and add integration tests around the VS Code bridge, because that surface currently depends heavily on static checks.
+
+## 2. Current Functional Risks
+
+- VS Code bridge `/events` uses a long-lived SSE stream. The new server has read/header/idle limits but intentionally no global write timeout, so a real VS Code smoke test should confirm events still flow correctly during SSH/SFTP/VNC/GitHub sessions.
+- VS Code webview HTML is duplicated across many panel classes. CSP, nonce generation, escaping, and message wiring are now correct in reviewed files, but duplication increases future regression risk.
+- The Node extension bridge client reads bridge responses without an explicit response-size cap or request timeout. The bridge is local and trusted, but a stuck bridge can still degrade the extension UX.
+- Frontend/webview coverage is mostly static regression assertions. It catches known bug patterns but does not prove that panels render and handlers fire inside VS Code.
+
+## 3. Code Quality Improvements
+
+- Centralise webview scaffolding in `vscode/nexus/extension.js` and `vscode/leviathan/extension.js`: CSP generation, nonce creation, common style policy, and HTML shell construction should live in one helper per extension or a shared local module.
+- Wrap bridge HTTP requests in a small client helper with timeout, response-size cap, JSON decode error handling, and consistent error messages.
+- Consider replacing large inline template-string webviews with smaller render helpers that build trusted static shell plus escaped dynamic content. The current approach is workable, but it makes security review repetitive.
+- Keep the bridge handler helpers small and testable. `newBridgeHTTPServer` and `decodeLimitedJSON` are a useful pattern for future endpoints.
+
+## 4. Frontend Interaction and Error-Handling Improvements
+
+- Add manual smoke steps for Nexus Connections, terminal, RAW, GitHub, IRC, VNC, Profile Editor, Settings, SFTP, Leviathan Tools, Leviathan Hex, and Leviathan tool panels.
+- Add non-sensitive `console.error` or visible status handling for JSON parse failures in VS Code webview message handlers where currently errors may be silent.
+- Validate that reconnect, resize, SFTP directory actions, GitHub refresh/download, and Leviathan tool execution still fire their expected events after panel reloads.
+- Confirm no webview logs secrets, bearer tokens, passwords, passphrases, private key material, or raw sensitive bridge responses.
+
+## 5. Testing Roadmap
+
+- Unit tests: keep `cmd/vscode-bridge` tests for server settings and body caps; add request method/auth tests for all bridge routes.
+- Integration tests: add socket-level bridge tests for slow headers, oversized headers, and idle connection cleanup.
+- VS Code extension smoke tests: exercise webview creation, command registration, bridge startup, one RPC, and one event frame.
+- Frontend interaction tests: use a browser/DOM harness for key Wails UI flows where practical, especially SFTP upload, profile import, SSH key management, and Leviathan mode switching.
+- Abuse-case tests: retain oversized import/upload/config tests and add edge cases whenever new parsers or bridge endpoints are introduced.
+- Release smoke tests: package VSIX files and assert expected files, CSP strings, media resources, and bridge executable permissions.
+
+## 6. Recommended New Functionality
+
+- Add an in-extension bridge diagnostics command that shows bridge status, version, last RPC error, and whether the event stream is connected, without exposing the bearer token.
+- Add a developer-only test command for the VS Code extension that opens each webview and posts a benign fixture state. This would make manual and automated smoke testing faster.
+- Add a small security status page or command that reports vault state, known-host policy, update-check source, and active local bridge address without sensitive values.
+
+## 7. Next-Level Opportunities
+
+- Create a shared webview rendering module for both Nexus and Leviathan extension panels, with typed helpers for CSP, escaping, buttons, and event wiring.
+- Introduce structured bridge RPC method allow-list metadata rather than reflective method dispatch alone. Reflection is convenient, but a visible allow-list would make the trust boundary easier to review.
+- Add observability around bridge request counts, rejected oversized requests, active event clients, and session lifecycle errors.
+- Add accessibility checks for VS Code webview panels, especially keyboard focus, button labels, and status updates in terminal/disconnected flows.
+
+## 8. Prioritised Action Plan
+
+Immediate:
+
+- Smoke-test the committed fix in a real VS Code host.
+- Confirm `/events` remains stable during session state changes.
+
+Short-term:
+
+- Add bridge client timeout and response-size caps in the Node extension code.
+- Add VS Code extension smoke tests for panel construction and bridge RPC.
+- Consolidate CSP nonce creation and webview HTML policy helpers.
+
+Medium-term:
+
+- Replace static-only regression assertions with executable DOM or VS Code integration tests for high-value panels.
+- Add bridge route coverage for auth failures, method errors, malformed JSON, and event subscription lifecycle.
+
+Long-term:
+
+- Build a release validation pipeline for desktop app, bridge binary, and VSIX packages.
+- Add structured diagnostics and observability for local bridge health and rejected requests.
+
+## 9. Caveats and Validation Needed
+
+- Source and automated tests passed, but VS Code runtime behaviour was not manually exercised in this pass.
+- The CSP nonce change should be behaviour-preserving, but every webview panel should still be opened once in VS Code.
+- The bridge timeout settings are conservative for local RPC; long-running operations should continue reporting progress through events rather than blocking a single HTTP request indefinitely.