diff --git a/.planning/phases/07-socket-security/07-CONTEXT.md b/.planning/phases/07-socket-security/07-CONTEXT.md new file mode 100644 index 0000000..04b7f7b --- /dev/null +++ b/.planning/phases/07-socket-security/07-CONTEXT.md @@ -0,0 +1,66 @@ +# Phase 7: Socket Security - Context + +**Gathered:** 2026-02-03 +**Status:** Ready for planning + + +## Phase Boundary + +Docker operations flow through a filtered proxy instead of direct socket access. n8n connects to the proxy via TCP, and dangerous Docker APIs are blocked. All existing bot commands continue working through the proxy. + + + + +## Implementation Decisions + +### Proxy Container Setup +- Use existing Unraid Community Apps template "dockersocket" (tecnativa/docker-socket-proxy:latest) +- Container name: `docker-socket-proxy` (predictable name for n8n curl commands) +- Network: Same Docker network as n8n — proxy joins existing network +- Deployment: Installed via Unraid CA, not managed by this project + +### API Filtering Rules +- Allow POST requests to container endpoints (start/stop/restart) +- Allow image pull operations (needed for update command) +- Block dangerous APIs: exec, create, build (proxy defaults) +- No additional blocking beyond defaults — container and image ops only + +### Error Responses +- Blocked API calls show: "This action is blocked by security policy" (clear but not technical) +- Distinguish between "blocked by policy" vs "Docker error: [details]" for debugging +- 403/blocked responses fail immediately — no retry +- No special logging for blocked attempts (proxy handles it) + +### Failover Behavior +- If proxy unavailable: "Docker proxy unavailable — please check server" sent to Telegram +- No fallback to direct socket access +- Short timeout (5 seconds) when calling proxy +- One retry on timeout, then fail with error message +- Proxy container managed by Unraid — we don't configure health checks or auto-restart + +### Claude's Discretion +- Exact curl command format for proxy calls +- Specific env var configuration for tecnativa proxy +- How to update n8n workflow nodes to use proxy endpoint + + + + +## Specific Ideas + +- Use the existing dockersocket Unraid CA template rather than custom deployment +- Keep proxy configuration minimal — it's Unraid's responsibility to manage the container + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 07-socket-security* +*Context gathered: 2026-02-03*