93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# 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/noctools/onlyscans-agent-kit.git
|
|
cd onlyscans-agent-kit
|
|
cp .env.agent.example .env
|
|
# edit .env: AGENT_IDENTITY / AGENT_PASSWORD
|
|
docker compose up -d
|
|
docker compose logs -f
|
|
```
|
|
|
|
The worker image pulls anonymously — no `docker login` required.
|
|
|
|
**Expected log lines on a healthy start:**
|
|
`authenticated to PocketBase …` — that's it. (The agent's location is
|
|
carried by its central record; nothing local participates.)
|
|
A rejected password is FATAL by design — check `AGENT_IDENTITY` /
|
|
`AGENT_PASSWORD` in `.env` and `docker compose 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
|
|
(the tag + `AGENT_VERSION` in `compose.yml` are usually already bumped
|
|
centrally), then:
|
|
|
|
```bash
|
|
docker compose pull
|
|
docker compose up -d
|
|
```
|
|
|
|
(Second agent on this box? Its `compose.agent2.yml` is not auto-discovered —
|
|
upgrade it explicitly: `docker compose --env-file .env-agent2 -f
|
|
compose.agent2.yml pull && docker compose --env-file .env-agent2 -f
|
|
compose.agent2.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 `compose.yml`.
|
|
- **Second agent on the same box:** each agent needs its OWN credentials —
|
|
copy `compose.yml` to `compose.agent2.yml` AND create a second env file
|
|
(`.env-agent2`), then run it with `docker compose --env-file .env-agent2
|
|
-f compose.agent2.yml up -d` (plain `docker compose up -d` always
|
|
operates on the first agent only — `compose.agent2.yml` is not
|
|
auto-discovered, which is the safe direction). In the copy, change the project `name:`
|
|
and `container_name` (and `WORKER_HEALTH_PORT` under host networking) per
|
|
the comments in the file. Two agents sharing one `.env` would share one
|
|
auth record — unsupported and silently wrong.
|
|
- **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 |
|
|
|---|---|
|
|
| `no configuration file provided: not found` | You're not in the kit directory (`compose.yml` is auto-discovered only from the directory you run in). `cd` into the `onlyscans-agent-kit` clone, or use plain `docker logs onlyscans-agent` (the container itself is fine) |
|
|
| Upgraded from an older kit (`docker-compose.agent.yml`)? | The compose file was renamed to `compose.yml` — `git pull` removes the old one. Use plain `docker compose up -d` / `logs -f` from now on; your `.env` is untouched. If you EDITED the old tracked file (e.g. applied the host-network swap) `git pull` will refuse — restore it first (`git checkout -- docker-compose.agent.yml`), pull, then re-apply your change in an untracked `compose.override.yml` (auto-merged with `compose.yml`, so future pulls stay clean) |
|
|
| Container exits ~1 s after start | Bad `AGENT_IDENTITY` or `AGENT_PASSWORD` — 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 |
|