Features
Everything mipo does
Nine capability areas — from scanning, reverse DNS, and the scanner architecture to audit, identity, health, and transparency. Each feature links to its documentation.
Scanning & Discovery
Schedule and execute TCP port scans across IPv4 and IPv6 subnets from multiple network vantage points simultaneously. The dispatcher resolves templates into concrete targets, expands CIDR ranges with deduplication, batches jobs across scanners, and monitors for stalls — so operators work with named groups while scanners receive fully-resolved jobs. Every result is timestamped in TimescaleDB for historical diffing.
| Feature | What it does | Links |
|---|---|---|
| Run Scan | Select a scan template and launch it on demand. The UI shows real-time progress — ports scanned, hosts completed, and scan status — updated via polling as scanners report results back through the ingest nodes. | Docs → |
| Recent Scans | Quick-triage view of completed and failed scans within a user-configurable time window (default 8 hours). Each scan shows its template, assigned scanners, start/end timestamps, and tests completed. Click a row to drill into results. | Docs → |
| Scan History | The scan list is a persistent archive of every completed and failed scan, with date-range filters and per-column controls. Suitable for audit, period reports, and forensic exploration. Export to CSV/JSON/PDF for evidence collection. Raw per-port rows follow the 90-day results retention below; the scan record, its port-state changes, and its signed receipt remain. | Docs → |
| Scan Results | Query historical scan results stored in TimescaleDB. Compare results across time to detect newly opened or closed ports. Filter by subnet, port, scanner, or time window. Raw results are kept for 90 days (the two most recent completed baselines per scope are always kept); port-state change history and signed execution receipts remain as the long-lived record. | Docs → |
| Recurring Schedules | Attach a schedule to any scan template using cron expressions, preset cadences (hourly, daily, weekly, monthly), or a continuous schedule that starts the next run as soon as the previous one finishes, with a minimum gap. Configurable jitter window randomizes start times to avoid predictable scan patterns. The dispatcher evaluates schedules and launches scans automatically. | Docs → |
| Multi-Vantage Scanning | Group scanners by network location and scan the same targets from every scanner in the group simultaneously. Each result is tagged with the originating scanner ID, enabling side-by-side comparison of what each network vantage point can see. | Docs → |
| Signed Execution Receipts | Every job ends with a receipt signed by the scanner that ran it — the hosts and ports it attested, with hashes the server recomputes before accepting. Proof of execution distinguishes "we scanned and nothing changed" from "we never scanned", and a no-change delta scan still shows the ports its receipt attested open. | Docs → |
| Job Batching & Reconciliation | Large scan scopes are split into batches sized to each scanner's capacity. A background reconciler monitors in-flight scans for stalls — jobs that haven't reported progress within the expected window emit a recovery event and are marked failed. Manual re-run is required after reconciliation; jobs are not automatically reassigned. | — |
Reverse DNS
Every scanned host can carry the hostname it answered to at scan time. Reverse-DNS lookups run on resolver identities — the same Go binary installed in its resolver role — grouped into resolver groups that act as DNS vantage points, against the resolver host's own DNS or an ordered nameserver group. Observations are append-only evidence and every DNS job ends with a signed receipt, so "which hostname was that IP" has the same chain of custody as the port result.
| Feature | What it does | Links |
|---|---|---|
| Resolvers | A resolver is a second identity kind sharing the scanner lifecycle — provisioning, mTLS enrollment, heartbeats, revocation — but eligible only for reverse-DNS work. Install the scanner binary with install.sh --role resolver and bind it to a resolver group. | Docs → |
| Resolver Groups | A resolver group is a DNS vantage point: the set of resolvers that will run lookups for a scan. Jobs are leased to the group's resolvers with deadlines and heartbeat-renewed leases, and an alarm opens when a group has no available resolver or its nameservers keep failing. | Docs → |
| Nameserver Groups | Ordered failover lists of nameservers for scans that must not use the resolver host's own DNS — for example an internal zone only reachable from one site. A scan template or the global default selects the nameserver group. | Docs → |
| Per-Template DNS Mode | Each scan template chooses disabled, resolver host DNS, a nameserver group, or inherit the global default set under Admin › Settings. The dispatcher snapshots the effective request when the scan expands, so the evidence records exactly what was asked. | Docs → |
| Hostnames on Results | The results page shows each host's reverse-DNS names and a DNS status (Resolved, No PTR, Timed out, Nameserver error, and more) with an evidence drawer listing every lookup attempt. Pruned evidence is labelled as removed by retention — never as "not requested". | Docs → |
| Signed DNS Receipts | A resolver signs a receipt for every DNS job it completes; the server recomputes every hash and count before writing it, and an unsigned receipt is refused. On a stable network a delta scan's unchanged hosts are derived from the receipt. | Docs → |
| Resolver Fleet Health | The reverse-DNS work queue: pending and assigned lookup tasks and jobs, how long the oldest pending item has waited, and the per-resolver-group backlog — alongside the scanner fleet pages. | Docs → |
Scanner Architecture
Most scanning tools require you to trust a third-party agent with network access and automatic updates. mipo's scanner is a single Go binary with zero dependencies — no node_modules, no transitive supply chain risk. It doesn't phone home, doesn't self-update, and the entire source fits in one directory. One binary serves two roles — port scanner or reverse-DNS resolver — fixed by the identity the server issues. The source will be published under Apache-2.0, so every line of code that runs on your network can be read.
| Feature | What it does | Links |
|---|---|---|
| Go Stdlib-Only Binary | The scanner is a single statically-linked executable built entirely from Go standard library packages — zero third-party dependencies, zero entries in go.mod. The entire codebase is small enough to audit in one sitting, which matters when you are deploying it inside customer networks. | Docs → |
| Signed Scanner Binary | Release binaries are Ed25519-signed. The installer verifies the SHA-256 and the signature before anything is installed and refuses on a mismatch (signature verification is on by default). Organisations building from source sign with their own key. | Docs → |
| One-Time Provisioning | The management UI generates an install one-liner carrying a one-time provisioning token valid for one hour. On the host, the installer verifies the binary, generates the scanner's own key pair and API key, and sends a certificate request plus the API-key hash with the token; the manager signs it and the host persists the issued client certificate. No secret is written to the environment file. | Docs → |
| Scanner mTLS Identity | Scanner runtime traffic arrives on a dedicated :8443 ingress that requires a client certificate on every handshake. Leaf certificates are valid 30 days and renew automatically 10 days before expiry; the issuing CA can be rolled over without fleet downtime. The API key is still presented, but the certificate is the identity. | Docs → |
| Heartbeat Monitoring | Each scanner sends a heartbeat to the ingest API every 60 seconds. If no heartbeat is received for 2 minutes, the scanner is automatically marked offline and a system event is emitted. The health dashboard shows last-seen timestamps and connection history for every scanner. | Docs → |
| IP Binding Modes | Lock each scanner to a specific source IP address, CIDR subnet, or ASN. The ingest API validates the source IP of every heartbeat and result submission against the configured binding. Connections from unauthorized IPs are rejected and logged. | Docs → |
| Scanner ACL Export | Generate consolidated firewall allow-rules for all registered scanners in iptables, nginx allow/deny, and Cloudflare IP Access Rule formats. Useful for operations teams who need to allowlist scanner IPs across network infrastructure. | Docs → |
| Enable / Disable | Soft-disable a scanner without deleting it. Disabled scanners retain their configuration, API key, and scan history but are excluded from new job assignments. Re-enable at any time to resume scanning without re-provisioning. | Docs → |
| Rotate API Key | Issue a new API key without re-provisioning. The previous key keeps authenticating for a 24-hour grace window so in-flight scans finish; the scanner takes the new key as MIPO_API_KEY in the env file on the host, where it must then stay. Use it for proactive rotation policies. | Docs → |
| Regenerate Token | Immediate revocation: the old identity stops authenticating the moment the token is regenerated, and the host must be re-provisioned with install.sh. Use it when a key or host may have been compromised. | Docs → |
| System Metrics | Scanners report CPU load, memory usage, and network I/O alongside each heartbeat. These metrics are displayed on the scanner fleet health page, enabling operators to detect resource-constrained scanners before they start dropping jobs. | Docs → |
Audit & Compliance
Audit logging isn't a plugin you enable — it's a global interceptor that records every state change before the API response is sent. Configuration edits, login attempts, data access, role assignments — all captured with actor identity, timestamp, and field-level diffs. Your SOC 2 auditor gets complete evidence without anyone remembering to turn logging on.
| Feature | What it does | Links |
|---|---|---|
| Configuration Changes | Every create, update, and delete operation is recorded with the acting user, timestamp, affected resource, and a field-level diff showing exactly what changed. The log is append-only — no application role can modify or delete a record, even the owner account. Events are kept 365 days by default (set AUDIT_RETENTION_DAYS in .mipo.env to change it); export for longer archival. | Docs → |
| Authentication Events | Records every login attempt (success and failure), logout, and session expiration for both local and OIDC authentication methods. Each event includes the source IP address, user agent, and authentication method used. Kept 180 days by default. | Docs → |
| Data Access Views | Tracks when users view sensitive resources such as scanner API keys, user profile details, and configuration secrets. Provides a read-access audit trail required by compliance frameworks that mandate data access logging. Kept 90 days by default. | Docs → |
| Audit Log Integrity | Every audit event is linked into a SHA-256 hash chain. The integrity page re-verifies the chain on demand and reports the first divergent row, so in-place tampering of historical records is detectable. | Docs → |
| Export | Download the full audit log or a filtered subset as structured data for ingestion into your SIEM, compliance reporting tool, or long-term archival storage. Useful for producing evidence during SOC2 or ISO 27001 audits. | — |
Identity & Access Control
Access control is enforced at the API layer, not the GUI. Every request is checked against path-based scopes before it reaches a handler. The GUI simply reflects what the API permits — there are no client-side-only restrictions to bypass.
| Feature | What it does | Links |
|---|---|---|
| User Management | Create, edit, and delete user accounts. Each user can authenticate via local credentials, an external OIDC identity provider, or both. User list is sortable and filterable by role and authentication method. | Docs → |
| RBAC Roles | Define custom roles using granular path-based scopes such as /scans:execute, /config:*, and /audit:view. Scopes are enforced at the API middleware layer — the GUI simply reflects what the API permits. Roles can be assigned to multiple users. | Docs → |
| Built-in Roles | Four default roles are seeded on every installation: admin (all scopes), run-scans (execute scans and view results, no configuration), configure-scans (manage scan configuration, no admin functions), and audit (read-only access for compliance review). They provide a known-good baseline to build custom roles from. | Docs → |
| OIDC / SSO | Connect any standards-compliant OpenID Connect identity provider (Okta, Azure AD, Google Workspace, Keycloak, etc.). A first-time OIDC user gets a new account; an existing local account with the same email is not linked automatically (an admin links it), and the owner account is never linkable. Role assignment happens manually via the Identity > Roles page after first login. Automatic role mapping from IdP claims is not currently supported. | Docs → |
| Multi-Factor Authentication | TOTP second factor for local accounts with ten one-time recovery codes generated at enrollment. A deployment-wide policy sets MFA to off, optional, or required for every local account; admins can reset a locked-out user's enrollment. | Docs → |
| Step-Up Re-authentication | Destructive, trust, and credential endpoints — user and role changes, backup download, certificate activation, scanner key rotation, mTLS policy — require the caller to re-prove their identity within the last 10 minutes. The owner's scope bypass does not apply; the GUI prompts automatically. | Docs → |
| Password Policy & Lockout | One password policy is evaluated by a single function that draws the live checklist under every new-password field and validates the API. Ten consecutive failed logins lock the account for 15 minutes, on top of per-IP rate limiting. | Docs → |
| Owner Account | A special bootstrap account created during initial setup that bypasses all RBAC scope checks (but not step-up re-authentication). Intended for emergency access and first-time configuration. Cannot be deleted or have its permissions reduced. | — |
| Session Management | Sessions are server-side records identified by a signed cookie, with a 24-hour absolute and 60-minute idle timeout. Expired sessions are cleaned up automatically on a background schedule. All session creation and expiration events are written to the authentication audit log with the associated IP address and user agent. | Docs → |
Configuration
Scan targets are defined as named objects that compose into templates. Subnets, port lists, and scanner assignments combine into reusable scan templates that can be scheduled or triggered on demand. Scope changes are version-tracked so you can audit what was in scope during any historical scan.
| Feature | What it does | Links |
|---|---|---|
| Subnets | Define IPv4 and IPv6 network ranges in CIDR notation. The UI calculates host counts and validates notation on input. Subnets are named objects that can be referenced by multiple scan templates, so renaming a network updates every template that uses it. | Docs → |
| Subnet Groups | Organize subnets into named collections — for example, "production-dmz" or "branch-offices". Groups can be assigned to scan templates instead of individual subnets, simplifying configuration when the same set of networks is scanned by multiple templates. | Docs → |
| Port Catalog | A built-in reference library mapping well-known TCP ports to their service names and descriptions (e.g., 443/HTTPS, 5432/PostgreSQL). Used as a lookup when building port lists, and to enrich scan results with human-readable service labels. | Docs → |
| Port Lists | Named collections of TCP ports that can be shared across scan templates. Define lists like "web-standard" (80, 443, 8080, 8443) or "database-ports" (3306, 5432, 27017) once and reference them everywhere. | Docs → |
| Port List Groups | Combine multiple port lists into a single comprehensive scan profile. For example, merge "web-standard", "database-ports", and "admin-services" into a "full-audit" group that covers all three sets of ports in one scan. | Docs → |
| Discovery | Bring targets in from the systems that already know them — cloud providers, firewalls, CMDBs — without giving mipo their credentials. Create a discovery source, get a per-source API key, and have your own scripts push IP lists to it; your cloud or CMDB credentials never leave your scripts. Scan templates reference discovery lists alongside subnets. | Docs → |
| Scan Templates | Reusable scan definitions that combine target scope (subnets or subnet groups), port lists, scanner assignments, timing parameters, and the reverse-DNS mode into a single named configuration. Templates are the primary unit of work — schedules and on-demand scans both reference templates. | Docs → |
| Scan Template Groups | Bundle multiple scan templates into a group for batch scheduling. When a schedule triggers a template group, all templates in the group are launched together, enabling coordinated multi-scope scanning with a single schedule. | Docs → |
Health & Alerting
mipo continuously monitors its own infrastructure — manager, ingest nodes, the database cluster, proxy, DNS, TLS certificates, backups, and the scanner and resolver fleets — and surfaces faults as structured alarms with severity levels and acknowledgment workflow. You don't monitor mipo with a separate tool; mipo monitors itself.
| Feature | What it does | Links |
|---|---|---|
| Dashboard | Customizable widget-based dashboards that provide at-a-glance visibility into scan activity, scanner health, and system status. Add, remove, and drag-to-reorder widgets to build views tailored to different roles — NOC operators, security analysts, and compliance reviewers each see what matters to them. | Docs → |
| Infrastructure Monitoring | Dedicated health pages for every component: manager process metrics, per-node ingest throughput, database connection pool utilization, Traefik proxy status, DNS resolution across public/internal/container layers, TLS certificate validity, and backup schedule adherence. All surfaced through a visual architecture overview with real-time status indicators. | Docs → |
| Scanner Fleet Health | Aggregated view of all registered scanners showing online/offline status, last heartbeat timestamps, system metrics (CPU, memory, network I/O), and active job assignments. Highlights scanners that have gone offline or are not picking up jobs. | Docs → |
| Alarms | Stateful, deduplicated alarms with a lifecycle of open, acknowledged, and resolved. When a fault is detected, an alarm is opened or bumped (if already open). Operators can acknowledge alarms to signal they are investigating. Alarms auto-resolve when the corresponding recovery event arrives. | Docs → |
| Alarm Rules | Built-in rules covering database connectivity, scanner heartbeat loss, scanner certificate expiry and CA rollover, TLS certificate expiry and renewal or activation failures, backup schedule failures, DNS resolution, reverse-DNS resolver and nameserver health, audit-chain divergence, container health, and every job-error class. Each rule maps an event pattern to an alarm with a default severity. Operators can override severity levels or disable individual rules without modifying code. | Docs → |
| Notification Channels | Deliver alarm events to outgoing webhooks (any HTTP endpoint), Slack (via incoming webhook URL), or email (via SMTP). Each channel has a built-in test button. Webhook requests include an HMAC signature header for verification. Failed deliveries retry with exponential backoff. | Docs → |
| Notification Policies | Define routing rules that determine which alarm transitions (opened, bumped, acknowledged, resolved) are sent to which channels. Filter by alarm severity, specific alarm rules, or both. A read-only notification log tracks every delivery attempt with status codes and error messages. | Docs → |
Security & Operations
mipo is designed to go from a fresh server to a running, encrypted, monitored system with minimal manual steps. Secrets are auto-generated, TLS is enabled by default, backups can be encrypted at rest, and three purpose-built schemas (config, time-series results, transient jobs) in a single TimescaleDB cluster isolate concerns by access pattern.
| Feature | What it does | Links |
|---|---|---|
| Setup Wizard | On first launch, when no owner account exists, all routes redirect to a setup wizard that walks you through creating the owner account and configuring the initial settings. The wizard is only accessible when the system has zero users — once an owner is created, the setup endpoints are permanently disabled. | — |
| Auto-Generated Secrets | The first time mipo starts, it generates a .mipo.env file containing cryptographically random database passwords, session signing salts, and encryption keys. Operators never need to invent or manage these secrets manually — they are created once and persisted on the host. | — |
| TLS Certificate Management | All external traffic is TLS-terminated at the reverse proxy. Self-signed certificates are generated automatically for day-one encryption. Upload your own PEM certificate, or enable automated Let's Encrypt/ACME issuance and renewal with built-in DNS-01 support for Cloudflare, DuckDNS, DigitalOcean, Hetzner, deSEC, and Namecheap. The scanner ingress on :8443 follows its own published anchor and is never changed by a :443 activation. | Docs → |
| Certificate Profiles | A profile is the saved recipe for one certificate: the hostname, the DNS credential set, the Let's Encrypt account (staging for proof, production for trust) and whether to renew automatically. Issuing only stages a certificate — nothing is served until it is activated — and a failing renewal or a rolled-back activation raises an alarm. | Docs → |
| DNS Credential Sets | Store each DNS provider's API access once and reference it from any profile. Secrets are encrypted and never shown again, a set in use by a profile cannot be deleted, and the built-in test is read-only — it never creates or changes a DNS record. | Docs → |
| Issuance Runs | Every issuance mipo has attempted, step by step, with its status (succeeded, failed, or refused by a guard before any rate limit was spent) and what became of the certificate (staged, activated, rolled back, or superseded) — so the certificate history is auditable, not just the current certificate. | Docs → |
| Certificates | Every certificate mipo has installed, one row per generation, with the state derived from the files on disk and the live bindings. Activation on :443 is verified on the wire and rolled back automatically if the new certificate is not actually served. | Docs → |
| Encrypted Backups | Full-cluster backups run on a configurable daily schedule with configurable retention (1–365 days). Backups can be AES-256-encrypted at rest (optional — enabled by configuring an encryption key; off by default). Replicate to AWS S3 or any S3-compatible store (MinIO, Backblaze B2, Wasabi). On-demand triggers; restore is the operator CLI (scripts/ops/restore.sh), which connects as the database owner — the setup-wizard restore exists only where the manager holds owner credentials (development stacks). | Docs → |
| Public URL Configuration | A settings page allows the administrator to configure the public-facing FQDN used in scanner provisioning URLs and OIDC callback redirects. Falls back to the hostname from the incoming request if not explicitly set, so the system works out of the box in simple deployments. | Docs → |
Transparent by Design
mipo is built for environments where operators need to understand, audit, and explain every component. No black boxes, no hidden state, no vendor lock-in.
| Feature | What it does | Links |
|---|---|---|
| Open Source | The full source code — manager, ingest, dispatcher, scanner, website, shared libraries, CI/CD pipelines, Docker configurations, and test suites — lives in a single repository that will be published under the Apache-2.0 license. Nothing is compiled from a private source or gated behind a license key. | — |
| API-First Design | Every action the GUI can perform is available as a documented API endpoint. The GUI is a consumer of the same public API that automation scripts and third-party integrations use. There are no hidden admin endpoints or GUI-only capabilities. | — |
| No Auto-Update | Scanners do not phone home for updates, download code at runtime, or self-modify. Every binary running on your network was explicitly placed there by your team. Updates happen on your schedule through your deployment process. | — |
| No Telemetry | mipo does not collect usage analytics, send crash reports, phone home to a license server, or transmit any data to external services. All data stays within your infrastructure. The only outbound connections are ones you explicitly configure (S3 backups, ACME certificates, notification webhooks). | — |
| Contextual Documentation | Every GUI page has a matching documentation page at the same path under /docs. Each page also includes a collapsible QuickHelp section with field descriptions, how-to steps, and gotchas — sourced from the same data file so the help text and full docs always agree. | — |
Compliance mapping
Capabilities mapped to control frameworks
How mipo features line up against SOC 2 and ISO 27001 control areas.
| Control area | mipo features | Frameworks |
|---|---|---|
| Logical access control | RBAC scopes, OIDC/SSO, MFA (TOTP), step-up re-authentication, owner bootstrap, session management | CC6.1, CC6.2 / A.9.2, A.9.4 |
| Audit logging | Append-only audit trail, actor + timestamp, data access views, hash-chain integrity check | CC7.2, CC7.3 / A.12.4 |
| Scan-execution evidence | Scanner-signed execution receipts per job, append-only results and DNS observations | CC7.1, CC7.2 / A.12.4 |
| Change management | Config version tracking, scan scope history | CC8.1 / A.12.1.2 |
| Availability monitoring | Built-in alarm rules, scanner heartbeats, health endpoints | CC7.1 / A.17.1 |
| Asset management | Subnet inventory, port catalog, scanner registry | CC6.6 / A.8.1 |
| Encryption | TLS everywhere, scanner mTLS, backup encryption, credential encryption at rest | CC6.7 / A.10.1 |
| Incident response | Alarm lifecycle (open→acknowledged→resolved), notification channels | CC7.4 / A.16.1 |
Disclaimer
mipo supports evidence collection. It does not certify compliance — your auditors determine whether controls are satisfied.