feat: clone-and-go remote agent install kit

2026-08-21 05:43:26 +00:00
commit f84501be11
4 changed files with 183 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Only Scans — remote agent install kit
+
+This repo installs a **remote scan agent** for the Only Scans platform on a
+docker host at your site. The agent is a location-labelled scanner: it logs
+into the central instance with its own credentials, picks up scans queued
+for your location, and reports results back.
+
+The agent is inert without centrally-provisioned credentials — this repo
+contains no secrets.
+
+## What you get from Sam (central operator)
+
+1. An **agent username** (e.g. `chch-1`)
+2. The **password** shown once at agent creation
+3. Your **location name** (e.g. `chch-office`)
+
+## Prerequisites
+
+- Docker + the `docker compose` plugin
+- Egress to `scan-api.noctools.nz:443` (the central API, TLS)
+- Network reachability to the scan targets for your site — see
+  "Host-network variant" below if you need ARP-level LAN discovery
+- ~512 MB RAM for the container
+
+## Install
+
+```bash
+git clone https://gitea.noctools.nz/sam/onlyscans-agent-kit.git
+cd onlyscans-agent-kit
+cp .env.agent.example .env
+# edit .env: AGENT_IDENTITY / AGENT_PASSWORD / AGENT_LOCATION
+docker compose -f docker-compose.agent.yml up -d
+docker logs -f onlyscans-agent
+```
+
+The worker image pulls anonymously — no `docker login` required.
+
+**Expected log lines on a healthy start:**
+`authenticated` … `agent <name>: AGENT_LOCATION "<loc>" validated`.
+A rejected password or unknown location name is FATAL by design —
+check the values in `.env` and `docker compose -f docker-compose.agent.yml up -d --force-recreate`.
+
+**Verify centrally:** Sam confirms the agent flips **online** on the
+central `/agents` page within ~90 s, then queues a pinned test scan against
+your location — `claimed_by` should show the agent username.
+
+## Upgrades
+
+The compose file pins an image tag. To upgrade: `git pull` this repo,
+bump the tag + `AGENT_VERSION` in `docker-compose.agent.yml` if Sam hasn't
+already, then:
+
+```bash
+docker compose -f docker-compose.agent.yml pull
+docker compose -f docker-compose.agent.yml up -d
+```
+
+The agent re-authenticates and resumes polling.
+
+## Options
+
+- **Host-network variant** (scan the site LAN directly, ARP-level
+  discovery, non-routed subnets): swap the service to `network_mode: host`
+  per the commented block in `docker-compose.agent.yml`.
+- **Second agent on the same box:** copy the compose file, change the
+  project `name:` and `container_name` (and `WORKER_HEALTH_PORT` under
+  host networking) per the comments in the file.
+- **CVE matching** (optional): fill `CVE_MATCH_API` + `CVE_MATCH_TOKEN`
+  in `.env` only if Sam provides them. Without it, scans complete
+  normally with the CVE stage skipped.
+
+## Troubleshooting
+
+| Symptom | Meaning |
+|---|---|
+| Container exits ~1 s after start | Bad `AGENT_PASSWORD` or unknown `AGENT_LOCATION` — fatal by design; fix `.env` and recreate |
+| Agent shows **offline** centrally (`/agents`) | Container down, or no egress to `scan-api.noctools.nz:443` — check `docker logs onlyscans-agent` |
+| Scans stay queued | Agent online but for a different location, or targets unreachable from the container's network — try the host-network variant |