infra/modules/nixos/security/README-ai-worker.md

AI Worker Restricted Access

This module provides SSH access for the AI worker (hermes-agent) to run docker commands on the host.

Security Model

Overview

The ai-worker user has no direct docker group access. All docker commands must go through sudo, and only specific subcommands are whitelisted:

• Container lifecycle: docker ps, docker inspect, docker logs, docker images, docker info, docker version, docker stats
• Control: docker start, docker stop, docker restart, docker rm, docker rmi, docker wait
• Image management: docker pull, docker build, docker run, docker compose
• Disk cleanup: docker system
• Network/Volume: docker network ls, docker volume ls (read-only)

EXPLICITLY BLOCKED (not in sudo whitelist)

Command	Risk	Result
docker exec	Execute arbitrary commands inside containers (FILE MODIFICATION)	Blocked by sudo
docker cp	Copy files between containers and host	Blocked by sudo
docker commit	Create images from running containers (data exfil)	Blocked by sudo
docker diff	Inspect filesystem changes	Blocked by sudo
docker export	Export container filesystem	Blocked by sudo
docker import	Import filesystem archives	Blocked by sudo
docker load	Load docker images	Blocked by sudo
docker save	Save docker images to tar	Blocked by sudo
docker attach	Interactive access to containers	Blocked by sudo
docker push	Push images to registries	Blocked by sudo
docker tag	Rename images	Blocked by sudo

Why This Approach?

Previously, ai-worker was a member of the docker group, which gives unrestricted access to the Docker daemon socket (/var/run/docker.sock). Users in the docker group can run ANY docker command, including:

• docker exec -it container bash — full shell access to any container
• docker cp /host/file container:/path — file modification inside containers
• docker run -v /:/host alpine — full host filesystem access

By removing the docker group and using a sudo whitelist instead, we enforce the principle of least privilege.

Filesystem Access

• Home directory: /home/ai-worker (standard user home)
• No bind mounts: Cannot access /home/gortium/infra or other host files
• Cannot access: Any files outside standard system paths

Sudo Access

• Restricted: ai-worker has NOPASSWD access only to whitelisted commands
• Cannot run nh, nixos-rebuild, nixpkgs-fmt, or nix with elevated permissions

Workflow: SSH + Restricted Docker

All docker commands must be prefixed with sudo:

# From Hermes container, SSH to host
ssh -i /path/to/ssh/key ai-worker@host.docker.internal

# Check container status (works)
sudo docker ps

# Restart a container (works)
sudo docker restart ollama

# Run benchmark (works - docker run is allowed)
sudo docker run --rm alpine echo "test"

# ANY of these will FAIL (not in whitelist):
sudo docker exec ollama ollama list          # FAILS - docker exec blocked
sudo docker cp file.txt container:/path/     # FAILS - docker cp blocked
sudo docker commit container new-image       # FAILS - docker commit blocked

# For ollama operations, use the HTTP API instead of docker exec:
curl http://ollama:11434/api/tags

SSH Access

Connect as:

ssh ai-worker@lazyworkhorse

The working directory will be /home/ai-worker. No infra repo access.

Verification

Check ai-worker permissions:

# On the host, as root or gortium:
sudo -u ai-worker sudo -l
# Should show the whitelisted commands only (no docker exec/cp/commit)

# Verify NOT in docker group
groups ai-worker
# Should show: ai-worker (NO docker group)

Troubleshooting

If docker commands fail:

# Check sudo permissions
sudo -u ai-worker sudo -l | grep docker

# Verify group membership
groups ai-worker

# Test allowed command
sudo -u ai-worker sudo docker ps

# Test blocked command (should fail)
sudo -u ai-worker sudo docker exec ollama ollama list
# Expected: "Sorry, user ai-worker is not allowed to execute"

If SSH connection fails:

# Check SSH key is authorized
cat /home/ai-worker/.ssh/authorized_keys

# Check SSH service
systemctl status sshd