Scanners

Scanners are stateless Go binaries deployed on customer networks that execute port scans. This page lets you provision new scanners, manage their lifecycle (enable/disable/delete), configure IP binding for security, and regenerate provisioning tokens. Each scanner connects to mipo via a one-time curl command generated during provisioning.

Inputs

Name Description Allowed Values Default
Name Unique label identifying this scanner Alphanumeric and hyphens only, must be unique —
Description Optional free-text note about the scanner Any text, max 10,000 characters Empty
Binding Mode Restricts which source IP the scanner can connect from ip, subnet, asn, or none none
Rate Limit Maximum probes per second this scanner can fire, reflecting its hardware capacity Integer 0–100,000 0 (unlimited)

Fields & Columns

Name Description
Name Editable inline — the scanner label
Description Editable inline — optional note
Status Pending (not yet registered), Active (sending heartbeats), Offline (no heartbeat for 2+ min), or Disabled (manually stopped)
Binding IP/subnet/ASN restriction for this scanner. Yellow badge shows IP mismatch count.
Created By User who provisioned this scanner
Rate Limit Editable inline — max probes per second, or "—" if unlimited
Created Date the scanner was provisioned

How To

Provision a New Scanner

  1. Click "Add Scanner" and fill in the name.
  2. Copy the one-time curl command from the modal.
  3. Run the curl command on the target server to register the scanner binary.
  4. The scanner status will change from Pending to Active once it sends its first heartbeat.

Configure IP Binding

  1. Open the row actions menu and click "Configure Binding".
  2. Choose a binding mode (IP, Subnet, or ASN).
  3. Enter the allowed value and save.
  4. Connections from non-matching IPs will be flagged with a yellow mismatch badge.

Troubleshoot an offline scanner

  1. Check that the scanner process is running on the target server.
  2. Verify network connectivity between the scanner and the ingest endpoint (port 443).
  3. Check scanner logs for connection errors or authentication failures.
  4. Confirm the scanner API key has not been revoked in Config > Scanners.
  5. If the scanner was recently re-provisioned, ensure it is using the new API key.

Gotchas

  1. Regenerating a token invalidates the previous one — the scanner must be re-provisioned with the new curl command.
  2. Disabling a scanner prevents it from receiving new scan assignments but does not kill in-progress scans.
  3. A scanner marked Offline has simply missed heartbeats; it may still be running but unable to reach mipo.
  4. Rate limits interact with subnet and port list limits — the most restrictive (lowest non-zero) value wins. When scanners share a subnet via a scanner group, the subnet rate is divided equally among them.

API Calls (15)

Method Path Description
GET /api/config/scanners List all scanners
POST /api/config/scanners Create a new scanner
PUT /api/config/scanners/:id Update scanner name or description
PATCH /api/config/scanners/:id Update scanner binding
DELETE /api/config/scanners/:id Delete a scanner and revoke its access
GET /api/config/scanners/:id/binding Get scanner binding details
POST /api/config/scanners/:id/release-binding Release scanner IP binding
POST /api/config/scanners/:id/disable Disable a scanner
POST /api/config/scanners/:id/enable Enable a disabled scanner
POST /api/config/scanners/:id/regenerate-token Regenerate provisioning token
GET /api/config/scanners/binary-hash Get the current scanner binary hash
GET /api/config/scanners/install-script-preview Preview the scanner install script
GET /api/config/scanners/source-code Get scanner source code for review
GET /api/config/scanners/:id Get single scanner configuration
GET /api/config/scanners/filter-values Get available filter values for the scanners table

Related Pages

  • Scanner Groups — Organize scanners into groups for distributed scanning
  • Subnets — Scanners are assigned to subnets to define which networks they scan
  • Scan Status — View scan progress and results from scanner executions
  • Scanner Health — Real-time health and heartbeat status for registered scanners
  • Settings — Public URL setting affects scanner provisioning commands
  • Scanner ACL — Exports firewall rules based on registered scanner IPs
  • Discovery — Discovery lists are assigned to scanners for execution