roustabout

Structured documentation, security auditing, and compose generation for Docker environments.

Roustabout connects to the Docker API, inspects every running container, and produces:

• Markdown snapshots — complete inventory of images, ports, volumes, networks, env vars, labels
• Security audits — 18 checks covering socket exposure, secrets in env vars, sensitive ports, missing healthchecks, root containers, and more
• Compose generation — reconstructs docker-compose.yml from running containers
• Snapshot diffs — compare two JSON snapshots to see what changed

All output passes through a secret redactor. Environment variables matching configurable patterns are replaced with [REDACTED] before reaching your screen or AI model.

Install

pip install roustabout

# With MCP server support
pip install "roustabout[mcp]"

Docker

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e ROUSTABOUT_API_KEY=changeme \
  -p 8077:8077 \
  ghcr.io/featurecreep-cron/roustabout:latest

Then use the CLI remotely: roustabout --url http://server:8077 --api-key changeme snapshot

Quick start

roustabout snapshot                    # document your Docker environment
roustabout audit                       # run security checks
roustabout generate                    # reconstruct a compose file
roustabout diff old.json new.json      # compare snapshots

Remote mode

Connect to a running roustabout server instead of the local Docker socket:

# Save connection (prompts for API key)
roustabout connect http://server:8077

# All commands now use the saved server
roustabout snapshot
roustabout audit

# Or pass credentials explicitly
roustabout --url http://server:8077 --api-key mykey snapshot

# Remove saved connection
roustabout disconnect

Connection details are saved to ~/.config/roustabout/config.toml.

# Snapshot options
roustabout snapshot --show-env --output snapshot.md
roustabout snapshot --format json --output snapshot.json
roustabout snapshot --project mystack

# Audit options
roustabout audit --output audit.md --hide-accepted
roustabout audit --format json
roustabout audit --project mystack

# Generate options
roustabout generate --redact --output docker-compose.yml

# Finding management
roustabout accept docker-socket-watchtower "Watchtower needs socket access"
roustabout false-positive secrets-env-nginx "NGINX_HOST is not a secret"
roustabout resolve stale-image-redis "Updated to redis:7.2"

$ roustabout audit

# Security Audit

**212 findings:** **5 critical**, **40 warning**, **167 info**

| Severity | Check | Count | Containers |
|----------|-------|-------|------------|
| Critical | privileged-mode | 1 | cadvisor |
| Critical | docker-socket | 4 | cronbox, homeassistant, portainer, watchtower |
| Warning | secrets-in-env | 38 | authentik_server, grafana, mariadb, +14 more |
| Warning | host-pid | 1 | node_exporter |
| Info | no-healthcheck | 35 | adguard, bazarr, freshrss, +30 more |
| Info | running-as-root | 29 | adguard, cadvisor, plex, +24 more |

roustabout-mcp  # run standalone

{
  "mcpServers": {
    "roustabout": {
      "command": "roustabout-mcp"
    }
  }
}

show_env = false
show_labels = true
output = "docker-snapshot.md"
docker_host = "tcp://myhost:2375"
redact_patterns = ["my_custom_secret", "internal_token"]

[severity_overrides]
"docker-socket" = "info"
"secrets-env" = "critical"

Requirements

• Python 3.12+
• Access to a Docker socket (local or remote)

Upgrading

# CLI
pip install --upgrade roustabout

# Server (if running the Docker image)
docker pull ghcr.io/featurecreep-cron/roustabout:latest
docker compose up -d  # or restart your container

Both the CLI and server should be on the same version. The CLI warns if the server is outdated.

Contributing

Bug reports and pull requests welcome. See CONTRIBUTING.md.

Support

If you find roustabout useful, consider buying us a coffee.

License

MIT