|
1 | 1 | # doCODEmentation |
2 | 2 |
|
| 3 | +doCODEmentation is an open-source Python CLI that builds a **living inventory** of Docker Compose–based homelabs and self-hosted stacks. |
| 4 | + |
| 5 | +**Goal:** Documentation should match the real state of your infrastructure with minimal friction—one scan, Git-friendly outputs. |
| 6 | + |
| 7 | +## Why it exists |
| 8 | + |
| 9 | +Manual docs drift. This tool reads your Compose files and emits structured, diffable artifacts you can track in version control. |
| 10 | + |
| 11 | +Principles: |
| 12 | + |
| 13 | +- **Config as source of truth** — not hand-maintained diagrams only |
| 14 | +- **Not tied to one reverse proxy** — Traefik labels are optional; fallbacks use ports and other fields |
| 15 | +- **Human + machine readable** — YAML, JSON, and Markdown |
| 16 | +- **Low friction** — `scan` (and optional `watch`) as the main workflow |
| 17 | + |
| 18 | +## Requirements |
| 19 | + |
| 20 | +- Python **3.11+** |
| 21 | + |
| 22 | +## Installation |
| 23 | + |
| 24 | +```bash |
| 25 | +pip install -r requirements.txt |
| 26 | +``` |
| 27 | + |
| 28 | +Run the CLI either as: |
| 29 | + |
| 30 | +```bash |
| 31 | +python docomentation.py --help |
| 32 | +``` |
| 33 | + |
| 34 | +or via the included wrapper (executable after `chmod +x dcm`): |
| 35 | + |
| 36 | +```bash |
| 37 | +./dcm --help |
| 38 | +``` |
| 39 | + |
| 40 | +## Quick start |
| 41 | + |
| 42 | +Scan a directory of Compose files and write outputs under `./docs`: |
| 43 | + |
| 44 | +```bash |
| 45 | +./dcm scan --dir ./path/to/compose --output ./docs |
| 46 | +``` |
| 47 | + |
| 48 | +Example with the optional `test-data` tree (if present locally): |
| 49 | + |
| 50 | +```bash |
| 51 | +./dcm scan --dir ./test-data --output ./docs |
| 52 | +``` |
| 53 | + |
| 54 | +Outputs: |
| 55 | + |
| 56 | +- `docs/inventory.yaml` — primary, diff-friendly |
| 57 | +- `docs/inventory.json` — integrations / APIs |
| 58 | +- `docs/inventory.md` — human-readable report |
| 59 | + |
| 60 | +## CLI commands |
| 61 | + |
| 62 | +| Command | Purpose | |
| 63 | +|--------|---------| |
| 64 | +| `scan` | Scan Compose files and regenerate inventory | |
| 65 | +| `watch` | Watch for Compose file changes and rescan | |
| 66 | +| `diff` | Compare current vs previous inventory snapshot | |
| 67 | +| `add` | Add/update a row in `manual_overrides.yaml` | |
| 68 | +| `summary` | Print a terminal summary table (Rich) | |
| 69 | +| `audit` | Baseline hardening checks + optional secret hints | |
| 70 | + |
| 71 | +Examples: |
| 72 | + |
| 73 | +```bash |
| 74 | +# Scan and optionally commit inventory to git |
| 75 | +./dcm scan --dir /volume1/docker --output ./docs --git-commit |
| 76 | + |
| 77 | +./dcm watch --dir /volume1/docker --output ./docs |
| 78 | + |
| 79 | +./dcm diff --output ./docs |
| 80 | + |
| 81 | +./dcm add --name MyService --url https://example.com --note "External" --output ./docs |
| 82 | + |
| 83 | +./dcm summary --output ./docs |
| 84 | + |
| 85 | +./dcm audit --output ./docs |
| 86 | +./dcm audit --output ./docs --ignore traefik --ignore homepage |
| 87 | + |
| 88 | +./dcm --version |
| 89 | +``` |
| 90 | + |
| 91 | +## Identifiers and service metadata |
| 92 | + |
| 93 | +- **Primary service identifier:** `container_name` when set, otherwise the Compose service name (field `name` in inventory). |
| 94 | +- **`compose_service_name`:** original key under `services:` in the Compose file. |
| 95 | +- **`service_type`:** heuristic classification from the image name: `web`, `database`, `cache`, `proxy`, `monitoring`, `automation`, `media`, `other`. |
| 96 | +- **`image_tag`:** literal tag from the image string; if the reference contains `${...}`, it is reported as **`unresolved`** (no substitution is performed). |
| 97 | + |
| 98 | +## Security model |
| 99 | + |
| 100 | +doCODEmentation is built to **avoid leaking secrets**. |
| 101 | + |
| 102 | +**Read:** |
| 103 | + |
| 104 | +- Compose files named `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, `compose.yaml` |
| 105 | +- `manual_overrides.yaml` in the output directory |
| 106 | + |
| 107 | +**Never read (skipped / refused):** |
| 108 | + |
| 109 | +- `.env` and any path ending in `.env` |
| 110 | +- `secrets.yaml` / `secrets.yml` |
| 111 | +- Any filename containing `secret` |
| 112 | + |
| 113 | +**Behavior:** |
| 114 | + |
| 115 | +- Environment variables: **keys only** in inventory—**never values** |
| 116 | +- **`${VAR}` is never resolved** anywhere (tags stay `unresolved` when templated) |
| 117 | +- Traefik-style **label values** for obviously sensitive label keys are **redacted** in output |
| 118 | +- **Potential hardcoded secrets:** the scanner can flag suspicious `environment` entries (by key name + value heuristics) and report **service + key + warning only**—never the value |
| 119 | + |
| 120 | +Best practice: keep secrets in `.env` (not scanned), Docker/Builtin secrets, or your secret manager—not inline in committed Compose. |
| 121 | + |
| 122 | +## `manual_overrides.yaml` |
| 123 | + |
| 124 | +Placed next to outputs (e.g. `docs/manual_overrides.yaml`). Use it for: |
| 125 | + |
| 126 | +- Manual services not present in scanned Compose |
| 127 | +- Policy exceptions (e.g. intentionally privileged reverse proxy) |
| 128 | +- Optional score floor for documented exceptions |
| 129 | + |
| 130 | +Example: |
| 131 | + |
| 132 | +```yaml |
| 133 | +services: |
| 134 | + - name: traefik |
| 135 | + security_exception: true |
| 136 | + security_exception_reason: "Intentional elevated privileges for Docker socket / proxy orchestration" |
| 137 | + security_score_floor: 75 |
| 138 | + note: "Review manually; do not treat like a random misconfiguration." |
| 139 | +``` |
| 140 | +
|
| 141 | +Match **`name`** to the inventory service id (`container_name` or Compose service name). |
| 142 | + |
| 143 | +## Security scoring & audit |
| 144 | + |
| 145 | +- Score is **0–100** heuristic from `no-new-privileges`, `cap_drop`, `read_only`, and `user` (`root` / `non_root` / `unset`). |
| 146 | +- **`database`** and **`cache`** types are **not** penalized for missing `cap_drop` (different baseline). |
| 147 | +- **`audit`** prints baseline findings and, when present, a **Potential Hardcoded Secrets** table (keys only). |
| 148 | +- Services with `security.exception: true` from overrides are skipped in the baseline audit table. |
| 149 | + |
| 150 | +Scores are **signals**, not compliance certification. |
| 151 | + |
| 152 | +## Development & tests |
| 153 | + |
| 154 | +```bash |
| 155 | +pip install -r requirements.txt |
| 156 | +pytest test_scanner.py |
| 157 | +``` |
| 158 | + |
| 159 | +CI (GitHub Actions) runs the same test file on push and pull requests. |
| 160 | + |
| 161 | +## Contributing |
| 162 | + |
| 163 | +Issues and PRs welcome. Please avoid changes that would log or persist secret values. See `.github/ISSUE_TEMPLATE/`. |
| 164 | + |
| 165 | +## License |
| 166 | + |
| 167 | +MIT — see [LICENSE](LICENSE). |
0 commit comments