Managing Docker containers via docker-socket-proxy

Manage Docker containers securely via docker-socket-proxy: check status, logs, resource usage, and safely restart only whitelisted containers with cooldown.

Security Scan

The skill's purpose (safe, whitelist-driven Docker operations) is plausible, but there are multiple inconsistencies between the runtime instructions and the files/metadata (undeclared required env vars and binaries, incomplete implementation of promised sanitization and restart safeguards) that you should resolve before trusting it.

Purpose & Capability

The skill claims to manage Docker via a docker-socket-proxy and therefore legitimately needs access to DOCKER_HOST and the whitelist. However, the registry metadata lists no required environment variables or binaries, while SKILL.md and scripts clearly require DOCKER_HOST, SYSCTL_WHITELIST_PATH and binaries such as docker, jq, timeout, grep (with -P). This mismatch between declared requirements and actual needs is an incoherence the maintainer should fix.

Instruction Scope

SKILL.md scopes actions tightly (allowed/forbidden docker commands, whitelist checks, restart cooldown, audit log, sanitization). The included script enforces whitelist membership and period capping, but it does not implement promised log sanitization, and there is no restart implementation or cooldown/audit in code — those are expected to be enforced by the agent using the instructions. SKILL.md also inconsistently references both a workspace 'whitelist.yml' and SYSCTL_WHITELIST_PATH as required sources. The instructions to never pass user input to shell are good, but some operational details are ambiguous (where to obtain user_id for audit log).

Install Mechanism

There is no install spec (instruction-only with a small helper script). That is low risk from install-supply-chain perspective.

Credentials

The environment variables the skill requires in practice (DOCKER_HOST and SYSCTL_WHITELIST_PATH) are appropriate for its purpose — they control access to the docker-socket-proxy and to the whitelist. The metadata, though, declares none; that's a bookkeeping issue. There are no unrelated secret env vars requested. Note: DOCKER_HOST points to the socket-proxy and confers the privileges the proxy allows; ensure the proxy itself is correctly restricted.

Persistence & Privilege

The skill does not request persistent or global privileges (always: false). It does not modify other skills or system-wide settings in the files provided.

What to consider before installing

This skill generally does what it says (read-only-ish Docker queries + controlled restarts), but I found several inconsistencies you should address before installing: - Metadata vs reality: The skill's metadata declares no required environment variables or binaries, but the instructions and script require DOCKER_HOST, SYSCTL_WHITELIST_PATH, docker, jq, timeout and a grep implementation that supports -P. Ask the author to declare these in the registry metadata so you can enforce them at install time. - Whitelist enforcement: The script enforces name membership but the repo lacks an implementation of the restart/cooldown/audit steps described in SKILL.md. Confirm that your agent will enforce those restart safeguards (including checking can_restart in the whitelist and enforcing cooldown/audit) before allowing restarts. - Log sanitization: SKILL.md promises masking of tokens, DB connection strings, etc., but scripts provided do not perform redaction — logs may contain secrets. Either require the maintainer to implement robust redaction or ensure the agent performs sanitization before displaying logs. - Binaries availability: The script uses timeout and grep -P; these are not guaranteed present in all environments. Verify these binaries exist in the runtime or update the script to avoid -P usage (which may be unsupported) and to fail more explicitly if required tools are missing. - Configuration clarity: SKILL.md inconsistently references 'whitelist.yml in workspace root' and SYSCTL_WHITELIST_PATH. Decide on one canonical mechanism (prefer SYSCTL_WHITELIST_PATH) and document it clearly. - Risk note: DOCKER_HOST points to a socket-proxy; if that proxy is misconfigured it could expose broader Docker control. Only use this skill if you trust the docker-socket-proxy configuration and the whitelist file contents. If you cannot validate the above (metadata corrections, sanitization implementation, restart protections, and the proxy configuration), treat installation as higher-risk. If you decide to proceed, require the author to fix metadata and implement log redaction and explicit restart/cooldown code (or ensure your agent enforces those rules).

docker-ops

Manage Docker containers: status reports, log analysis, and restarts via docker-socket-proxy.

Prerequisites

• docker CLI available in PATH
• jq available in PATH
• DOCKER_HOST environment variable is pre-configured (do NOT override it manually)
• whitelist.yml in the agent workspace root

Whitelist

Before any Docker command, check the SYSCTL_WHITELIST_PATH environment variable.

If SYSCTL_WHITELIST_PATH is NOT set or empty:

• Do NOT run any Docker commands
• Reply: "⚠️ SYSCTL_WHITELIST_PATH is not configured. Set this environment variable in the container to point to the whitelist YAML file."
• This applies to ALL requests without exception

If set, read the whitelist file from that path. There is no fallback file.

Structure:

containers:
  - name: container_name
    description: "Human description"
    can_restart: true|false

Rules:

• NEVER run Docker commands against containers not in the whitelist
• NEVER restart containers where can_restart: false
• If a requested container is not in the whitelist, respond: "Container <name> is not in the whitelist. Available: <list>"

Allowed Commands

You may ONLY use these Docker commands:

Command	When
docker ps --format json	List running containers
docker ps -a --format json	List all containers (including stopped)
docker inspect <name>	Get container details (status, uptime, restart count)
docker stats --no-stream --format json <name>	Get resource usage (CPU, RAM, NET, BLOCK)
docker logs --since <period> --tail 500 <name>	Read container logs
docker restart <name>	Restart a container (explicit request only!)

Forbidden Commands

NEVER execute: docker rm, docker stop, docker kill, docker exec, docker run, docker pull, docker build, docker push, docker network, docker volume, docker image, docker system, docker compose.

Report Procedure

When asked for a status report:

Step 1: Parse the period

Convert user text to --since parameter:

• "за последний час" / "last hour" → 1h
• "за сегодня" / "today" → 24h
• "за 30 минут" / "30 minutes" → 30m
• "за неделю" / "last week" → 168h
• No period specified → default 1h
• Maximum: 168h (7 days). If user requests more — cap at 168h and inform them.

Step 2: Collect data

All docker commands must be wrapped with timeout 30 to prevent hanging.

# Status + uptime + restart count
timeout 30 docker inspect <name> | jq '.[0] | {Status: .State.Status, StartedAt: .State.StartedAt, RestartCount: .RestartCount, Health: .State.Health.Status}'

# Resource usage
timeout 30 docker stats --no-stream --format '{{json .}}' <name>

# Fetch logs once, then count errors and warnings locally
LOG_OUTPUT=$(timeout 30 docker logs --since <period> --tail 5000 <name> 2>&1)

# Error/warning count (quick stats)
echo "${LOG_OUTPUT}" | grep -ci 'error\|exception\|fatal\|traceback'
echo "${LOG_OUTPUT}" | grep -ci 'warn'

# Last errors (up to 10 unique)
echo "${LOG_OUTPUT}" | grep -i 'error\|exception\|fatal\|traceback' | sort -u | tail -10

Step 3: Sanitize output

Before displaying log fragments to users, mask sensitive patterns:

• Tokens, API keys, Bearer headers
• Database connection strings with credentials
• Passwords, secrets in environment variable dumps

Replace with [REDACTED] where detected.

Step 4: Format response

Use this template (adapt to language of request):

<status_emoji> **<container_name>**

**Status:** `running` (uptime: 2d 5h 13m)
**Restarts:** 0
**CPU:** 2.3% | **RAM:** 145MiB / 512MiB (28%)
**NET I/O:** 1.2MB / 340KB | **BLOCK I/O:** 12MB / 5MB

**Logs at last hour:**
- 🔴 Errors: 3
- ⚠️ Warnings: 12

**Last errors:**
• `ConnectionRefusedError: connect to postgres:5432`
• `TimeoutError: request took >30s`

**Recommendation:** Check access to PostgreSQL

Status emoji rules:

• ✅ — running, 0 errors, low resource usage
• ⚠️ — running but has warnings/errors, or high resource usage (>80% CPU/RAM)
• 🔴 — stopped/restarting/exited, or critical errors

Restart Procedure

When asked to restart a container:

1. Verify container is in whitelist AND can_restart: true
2. Confirm the request is explicit (user said "restart", "перезапусти", "рестартни")
3. Cooldown check: do not restart the same container more than once per 5 minutes. If repeated — warn and ask to confirm.
4. Audit log: before executing, output:

   [AUDIT] <ISO-timestamp> restart <container_name> requested_by=<user_id_if_available>
   

5. Execute: timeout 30 docker restart <name>
6. Wait and verify with retries:

   for i in 1 2 3; do
     sleep 10
     STATUS=$(timeout 30 docker inspect <name> | jq -r '.[0].State.Status')
     if [ "${STATUS}" = "running" ]; then break; fi
   done
   

7. If running → report success with new status
8. If not running after 30s → report failure with last 20 log lines: timeout 30 docker logs --tail 20 <name> 2>&1

Log Viewing

When asked to show logs:

1. Verify container is in whitelist
2. Apply --tail 500 limit always
3. If user asks for filtered logs (errors only, etc.) — use grep
4. For large output — summarize, don't dump raw
5. Sanitize sensitive data before displaying (see Step 3 in Report Procedure)

Safety Notes

• NEVER pass user input directly into shell commands as container names — only use exact matches from whitelist
• Always use 2>&1 when piping docker logs (stderr contains the actual logs)
• If DOCKER_HOST is not set, do NOT guess the address — report to user: "DOCKER_HOST is not configured. Set this environment variable to point to the docker-socket-proxy endpoint."
• If docker command fails with connection error — report to user that docker-socket-proxy may be down