Homelab Runbook

Scan and document all running services on this machine — Docker containers, system services (launchd/systemd), and open listening ports. Generates a human-re...

Security Scan

The skill does what it says — local inventory of containers, system services, and listening ports — and the scripts and instructions are proportionate to that purpose.

Purpose & Capability

Name/description match the implementation: provided Python scanners call docker, launchctl/systemctl, ss/netstat/lsof to build an inventory and a generator creates a Markdown runbook. External binaries used are the ones needed to inspect containers, services, and ports.

Instruction Scope

SKILL.md instructs the agent to run the included scanner scripts, summarize the generated runbook, and optionally save the file to the workspace or offer to persist to an Obsidian vault. The instructions do not ask the agent to read unrelated files or secrets, but the scans intentionally enumerate potentially sensitive local information (container mounts/host paths, process names/PIDs, service descriptions).

Install Mechanism

No install spec; this is instruction + included code only. The scripts run with the system Python and call local binaries. Nothing is downloaded or written to system locations by an installer.

Credentials

The skill requests no environment variables or external credentials. However, it legitimately reads local system state (processes, mount points, Docker container metadata) which can expose sensitive host paths and process ownership. Full port visibility may require elevated privileges (the code notes permission errors and suggests sudo).

Persistence & Privilege

always is false and the skill does not modify other skills or system-wide agent settings. It writes runbook output only to a user-specified file or stdout. Autonomous invocation is allowed (platform default) but not combined with other concerning privileges.

Assessment

This skill is internally consistent and does what it advertises: it inventories Docker containers, system services, and listening ports and writes a Markdown runbook. Before installing or running it, consider: (1) the scans reveal potentially sensitive local information (container mounts/host paths, process names and PIDs, service descriptions) — don't share the raw runbook without review; (2) port scanning may require sudo to see all listeners; (3) the skill itself does not exfiltrate data, but an agent with network/send privileges could forward results elsewhere — only run it on machines you trust and inspect the generated runbook before persisting or sharing; (4) if you want to hide specific services/paths, use the provided customization examples before running. If you want extra assurance, review the included scripts locally (they are short and call standard system tools) or run them manually once to confirm their output.

Scan the host machine and generate a Markdown runbook documenting all running services.

Scripts

All scripts are in scripts/. Run with python3 <script>. All output JSON to stdout.

Script	Purpose
scan_docker.py	Running containers: name, image, ports, mounts, status
scan_services.py	System services via launchd (macOS) or systemd (Linux)
scan_ports.py	Open TCP listening ports with process and PID
generate_runbook.py	Combine all scans → formatted Markdown runbook

Generating a Runbook

Quickest — run all scanners inline and print to stdout:

python3 scripts/generate_runbook.py

Save to a file:

python3 scripts/generate_runbook.py --output ~/homelab-runbook.md

Save to workspace:

python3 scripts/generate_runbook.py --output /Users/openclaw/.openclaw/workspace/homelab-runbook.md

Pre-collect then generate (useful for cron or piping):

python3 scripts/scan_docker.py > /tmp/docker.json
python3 scripts/scan_services.py > /tmp/services.json
python3 scripts/scan_ports.py > /tmp/ports.json
python3 scripts/generate_runbook.py --docker /tmp/docker.json --services /tmp/services.json --ports /tmp/ports.json --output ~/homelab-runbook.md

Agent Workflow

When the user asks for a homelab runbook or service inventory:

1. Run generate_runbook.py (all scanners inline, save to workspace file).
2. Read the output file and summarize key findings:
   • How many Docker containers are running and what they are
   • Notable open ports and the processes owning them
   • Any errors or warnings (Docker not found, permission denied, etc.)
3. Offer to save to Obsidian vault if the user wants it persisted.

Use the --output flag to write to the workspace. Do not dump the full raw Markdown at the user — summarize it and offer the file path.

Edge Cases

• Docker not installed: scan_docker.py returns {"error": "Docker not installed or not running", "containers": []} — runbook shows a warning, continues.
• No containers running: Returns empty list, runbook shows "No running containers."
• Port scan permission denied: scan_ports.py returns an error — runbook shows warning. Tell the user to re-run with sudo if full port visibility is needed.
• Linux without systemd: scan_services.py will return an error — acceptable, runbook notes it.

Customization

See references/customization.md for:

• Excluding specific services/containers/ports
• Adding manual service notes (URLs, config paths, restart commands)
• Scheduling with cron
• Modifying output format