# 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 |