soc-collector: run-anywhere scanner that pushes reports to SOC Center

A single Docker image, configured entirely by env vars (SOC_URL + SOC_TOKEN +
targets). Runs once and exits; schedule with cron. Four self-skipping sources:
  - surface     nmap open-port/service scan (SOC_TARGETS)
  - cve         Trivy HIGH/CRITICAL scan of running images (Docker socket)
  - tls         cert-expiry / weak-TLS / missing-headers (SOC_DOMAINS)
  - config      0.0.0.0 binds, --privileged, rw docker-socket mounts (Docker socket)
Stable slugs per source so SOC Center versions/diffs/alerts. Pure stdlib;
image adds nmap + trivy. MIT, intended as a public Ethica repo.

README.md

@@ -0,0 +1,67 @@
+# soc-collector
+
+A single, run-anywhere container that scans your estate and pushes the results to a
+[SOC Center](https://soc.ethica.no) instance as auto-updating reports. No JSON to write,
+no curl — you give it an **API endpoint** and a **token**, point it at some targets, and
+run it. Same report slug every run, so SOC Center versions each scan, diffs what changed,
+and alerts you only on *new* findings.
+
+## Run it
+
+```bash
+docker run --rm \
+  -e SOC_URL=https://soc.ethica.no \
+  -e SOC_TOKEN=soc_xxxxxxxx \
+  -e SOC_TARGETS=10.0.0.5,10.0.0.6 \
+  -e SOC_DOMAINS=soc.ethica.no,ethica.no \
+  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  git.skui.io/ethica/soc-collector:latest
+```
+
+It runs once and exits. To keep reports fresh, schedule that command — e.g. nightly:
+
+```cron
+0 2 * * *  docker run --rm -e SOC_URL=… -e SOC_TOKEN=… -e SOC_TARGETS=… -e SOC_DOMAINS=… \
+             -v /var/run/docker.sock:/var/run/docker.sock:ro git.skui.io/ethica/soc-collector:latest
+```
+
+The `SOC_TOKEN` is a **write-scoped** token you mint once in SOC Center (**Admin → Tokens**).
+Reports are owned by, and visible per, that token's user.
+
+## What it collects
+
+| Report (slug) | Source | Needs |
+|---|---|---|
+| `attack-surface` | `nmap` open-port / service scan, flags risky exposed ports | `SOC_TARGETS` |
+| `container-cves` | `trivy` vuln scan of every **running** image (HIGH/CRITICAL) | Docker socket |
+| `tls-exposure` | cert-expiry, weak TLS, missing security headers | `SOC_DOMAINS` |
+| `config-drift` | `0.0.0.0` port binds, `--privileged`, rw docker-socket mounts | Docker socket |
+
+Each source **self-skips** when its inputs are absent — no `SOC_TARGETS` → no nmap; no
+socket mount → no Trivy / config-drift. So the same image is safe to run anywhere; you
+just enable what you give it.
+
+## Configuration (all via env)
+
+| Var | Required | Default | Meaning |
+|---|---|---|---|
+| `SOC_URL` | ✅ | — | SOC Center base URL, e.g. `https://soc.ethica.no` |
+| `SOC_TOKEN` | ✅ | — | write-scoped API token |
+| `SOC_TARGETS` | for nmap | — | comma/space hosts or IPs to scan |
+| `SOC_DOMAINS` | for tls | — | comma hostnames to TLS-probe |
+| `SOC_SOURCES` | | `surface,cve,tls,config` | which sources to run |
+| `SOC_SLUG_PREFIX` | | — | prefix slugs (e.g. `hetzner`) so multiple sites don't collide |
+| `SOC_VISIBILITY` | | `private` | `private` or `authenticated` |
+| `SOC_TAGS` | | `collector` | extra report tags |
+
+## Notes
+
+- **Docker socket** is mounted **read-only** (`:ro`) and is only used to *list* running
+  containers and *inspect* their config. For extra isolation, point it at a scoped
+  socket-proxy instead of the raw socket.
+- The collector is **pure-stdlib Python**; the image just adds `nmap` and `trivy`.
+- Multi-site: run one container per site with a distinct `SOC_SLUG_PREFIX`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).