Guide
Getting started
Follow these steps to deploy a scanner, define scope, and run your first scan.
Prerequisites
- mipo is deployed and reachable over HTTPS.
- You have owner or admin access.
- At least one Linux host can run the scanner (a static Go binary, no runtime deps) and reach mipo on TCP 443 (provisioning) and TCP 8443 (the mutual-TLS runtime channel every scanner uses after provisioning). The ports are listed on the Scanner ACL page.
01
Register a scanner
- In Config > Scanners, add a scanner and give it a descriptive name. Creating a scanner is a high-impact action, so mipo asks you to confirm your identity (re-enter your password) before it proceeds.
- mipo generates a one-time provisioning token (valid for an hour, single use) and the install command that carries it in MIPO_PROVISIONING_TOKEN.
- Before running it, the host needs the scanner binary, its mipo-scanner.sig signature file, and the pinned public key at /etc/mipo/scanner.pub; if the manager still serves its day-one self-signed certificate, also set MIPO_SERVER_CA_FILE to that CA. install.sh refuses to run without them.
- Run install.sh on the Linux host. The host generates its own key pair and API key, receives a client certificate, and stores the identity in /var/lib/mipo-scanner — no secret is displayed or copied. The full procedure is on the scanner install guide linked below.
- The scanner begins heartbeating every 60 seconds.
02
Define target subnets
- Create subnets in CIDR notation (e.g. 192.168.1.0/24). IPv4 and IPv6 are both supported.
- Assign at least one provisioned scanner to each subnet.
- Group related subnets for easier reuse across templates.
03
Add port lists
- Built-in lists cover common services (web, database, mail).
- Create custom lists for your services; ports default to TCP.
- Port lists are reusable across multiple scan templates.
04
Build a scan template
- Combine subnets (the "where") with port lists (the "what").
- Templates are only eligible to run when their subnets have scanners assigned.
05
Add hostnames with reverse DNS (optional)
- Results show IP addresses only unless a template requests reverse DNS. The template's Reverse DNS field offers Off, Resolver host's DNS, Nameserver group, or Inherit global setting (the default set in Admin > Settings).
- Hostnames need a resolver: a second identity kind of the same scanner binary, installed with install.sh --role resolver and bound to a resolver group (a DNS vantage point). Create the resolver group first, then add the resolver under Config > Resolvers.
- Pick a nameserver group only when the lookups should go to specific servers rather than the resolver host's own DNS. See the scan template form docs at /docs/config/scan-templates/new.
06
Run your first scan
- Select an eligible template and launch it.
- Watch real-time progress as scanners report back through ingest.
- Open the completed scan to read per-host port state.
07
Set up schedules
- Attach a cron schedule, a preset cadence (hourly, daily, weekly, monthly), or a continuous schedule that starts the next run as soon as the previous one finishes.
- Jitter randomizes start times to avoid predictable scan patterns.
- Schedules can be disabled/enabled without deletion.