unraid-docker-manager/.planning/phases/07-socket-security/07-02-PLAN.md

---
phase: 07-socket-security
plan: 02
type: execute
wave: 2
depends_on: ["07-01"]
files_modified: [n8n-workflow.json]
autonomous: false

must_haves:
  truths:
    - "All bot commands work through proxy (status, start, stop, restart, update, logs)"
    - "n8n no longer references direct Docker socket in curl commands"
    - "n8n container no longer has docker.sock volume mount"
    - "Dangerous API calls return blocked error message"
  artifacts:
    - path: "n8n-workflow.json"
      provides: "Updated n8n workflow using proxy instead of direct socket"
      contains: "docker-socket-proxy:2375"
  key_links:
    - from: "n8n Execute Command nodes"
      to: "docker-socket-proxy:2375"
      via: "TCP curl calls"
      pattern: "curl.*docker-socket-proxy:2375"
---

<objective>
Migrate all n8n workflow curl commands from direct Docker socket to proxy, then remove direct socket access.

Purpose: Route all Docker API calls through the filtered proxy, removing direct socket access from n8n entirely (both in curl commands and volume mount).
Output: Updated n8n-workflow.json with all curl commands migrated to use proxy endpoint, and n8n container no longer mounting docker.sock.
</objective>

<execution_context>
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
@/home/luc/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/07-socket-security/07-CONTEXT.md
@.planning/phases/07-socket-security/07-RESEARCH.md
@.planning/phases/07-socket-security/07-01-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Update Workflow Curl Commands</name>
  <files>n8n-workflow.json</files>
  <action>
    Replace all Docker socket curl commands with proxy TCP calls.

    **Search and Replace Pattern:**
    FROM: `--unix-socket /var/run/docker.sock 'http://localhost/`
    TO: `--max-time 5 'http://docker-socket-proxy:2375/`

    **Commands to update (all Docker API calls):**
    1. Container list: `curl -s --unix-socket /var/run/docker.sock 'http://localhost/v1.47/containers/json?all=true'`
    2. Container inspect: Uses template `http://localhost/v1.47/containers/${containerId}/json`
    3. Image inspect: Uses template `http://localhost/v1.47/images/${imageName}/json`
    4. Image pull: Uses template with POST to `images/create?fromImage=`
    5. Start/stop/restart: Uses template `containers/${containerId}/${action}`
    6. Container delete: Uses template `containers/${containerId}` with DELETE
    7. Container create: Uses POST with JSON body to `containers/create` (needed for update command)
    8. Container logs: Uses `containers/${containerId}/logs`

    **Also update error handling in JavaScript nodes:**
    - Add handling for HTTP 403 responses: "This action is blocked by security policy"
    - Distinguish between 403 (blocked) and other errors
    - Do NOT retry on 403 - fail immediately

    **Do NOT change:**
    - API version (/v1.47/) - keep as is for compatibility
    - The 600 second timeout on image pull (that's intentional for large images)
    - Any non-Docker-socket curl commands
  </action>
  <verify>
    1. `grep -c 'unix-socket.*docker\.sock' n8n-workflow.json` returns 0
    2. `grep -c 'docker-socket-proxy:2375' n8n-workflow.json` returns 16 (or similar count)
    3. `grep -c 'max-time 5' n8n-workflow.json` shows timeout added (except image pull)
  </verify>
  <done>All Docker socket references replaced with proxy endpoint, timeout added</done>
</task>

<task type="auto">
  <name>Task 2: Push Updated Workflow to n8n</name>
  <files>n8n-workflow.json</files>
  <action>
    Use n8n API to update the live workflow with the modified JSON.

    1. Load .env.n8n-api for API credentials
    2. Read the updated n8n-workflow.json
    3. PUT to /api/v1/workflows/{id} with the updated workflow
    4. Verify the workflow was updated (check updatedAt timestamp)

    **Workflow ID:** HmiXBlJefBRPMS0m4iNYc (from Phase 6 summary)
  </action>
  <verify>
    API PUT request returns 200 with updated workflow, updatedAt timestamp is recent
  </verify>
  <done>n8n workflow updated via API with proxy configuration</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 3: Verify All Bot Commands Work</name>
  <what-built>Updated n8n workflow that routes all Docker API calls through the socket proxy instead of direct socket access</what-built>
  <how-to-verify>
    Test each bot command via Telegram:

    1. **status** - Should list all containers with their states
    2. **start [container]** - Pick a stopped container, verify it starts
    3. **stop [container]** - Stop that container, verify it stops
    4. **restart [container]** - Restart a container, verify success message
    5. **update [container]** - Update a container (or verify "already up to date" message)
    6. **logs [container]** - View logs for a container

    All commands should work identically to before the proxy migration.

    If any command fails, check:
    - Error message (403 = proxy blocking, other = connectivity issue)
    - Proxy container logs in Unraid
    - Network connectivity between n8n and proxy
  </how-to-verify>
  <resume-signal>Type "all commands working" or describe which commands failed</resume-signal>
</task>

<task type="checkpoint:human-action" gate="blocking">
  <name>Task 4: Remove docker.sock Volume Mount from n8n Container</name>
  <action>
    Now that all commands work through the proxy, remove the direct Docker socket access from n8n.

    **Steps:**
    1. Open Unraid web UI > Docker tab
    2. Click on the n8n container
    3. Click "Edit"
    4. Find the volume mapping for `/var/run/docker.sock`
    5. Remove this volume mapping entirely
    6. Click "Apply" to recreate the container

    **Why this is safe:**
    - All curl commands now use the proxy (verified in Task 3)
    - The socket mount is no longer needed
    - Removing it prevents any bypass of the proxy

    **What to expect:**
    - n8n container will restart
    - All bot commands should still work (they use the proxy now)
    - If any command breaks, the socket mount can be re-added temporarily
  </action>
  <verify>
    1. n8n container no longer shows docker.sock in its volume mappings
    2. Test one bot command (e.g., "status") to confirm it still works
  </verify>
  <done>n8n no longer has direct Docker socket access</done>
  <resume-signal>Confirm: "docker.sock mount removed, commands still work" or describe any issues</resume-signal>
</task>

</tasks>

<verification>
1. No unix-socket references remain in n8n-workflow.json
2. All curl commands use docker-socket-proxy:2375
3. Timeouts added to curl commands (except long-running image pull)
4. Error handling includes 403 response handling
5. All 6 bot commands work via Telegram
6. n8n container no longer has docker.sock volume mount
</verification>

<success_criteria>
- Zero unix-socket references in workflow
- All bot commands functional through proxy
- n8n container has no docker.sock volume mapping
- User confirms "all commands working" and "docker.sock mount removed"
</success_criteria>

<output>
After completion, create `.planning/phases/07-socket-security/07-02-SUMMARY.md`
</output>