mipo
Menu
ProductFeaturesArchitectureSecurityComplianceDocsGitHub

Scanner Binary

The scanner binary download endpoint (GET /scanner/binary/:platform/:arch) intentionally returns 501 Not Implemented. mipo does not serve pre-built binaries — operators build the scanner from auditable source code to protect against supply chain attacks. The response body includes the exact build command for the requested platform and architecture.

How to

Build the scanner binary

  1. Clone or download the mipo source repository.
  2. Navigate to the scanner/ directory.
  3. Run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o mipo-scanner . (adjust GOOS and GOARCH for your platform)
  4. Verify the binary hash against the value shown in the mipo dashboard (Config > Scanners > Binary Hash).
  5. Copy the binary to /usr/local/bin/mipo-scanner on the target host.

Set up signature verification (Ed25519, required by default)

  1. Signature verification is mandatory by default — controlled by MIPO_REQUIRE_SIG (default 1). Absent mipo-scanner.sig or absent /etc/mipo/scanner.pub causes install.sh / upgrade.sh to exit 1. Set MIPO_REQUIRE_SIG=0 only for dev, transition, or unsigned-build environments.
  2. Install the public key from the source repository (independent channel — NOT from the manager): sudo install -D -m 0644 scanner/scanner.pub /etc/mipo/scanner.pub. Verify against the published fingerprint in docs/security/scanner-signing.md before trusting it.
  3. Download mipo-scanner.sig alongside the binary (CI release artifacts; produced only when the builder has configured a signing key).
  4. Place the .sig file next to the binary: the install and upgrade scripts then verify fail-closed and refuse a binary that fails verification.
  5. Manual check at any time: sh scripts/ops/verify-scanner.sh <binary> <binary>.sig /etc/mipo/scanner.pub — exit 0 means the signature is valid.
  6. For maximum assurance against a compromised manager: obtain install.sh and scanner.pub from the independent channel (the audited source repo / signed release tag), not from the manager, and verify scanner.pub against the published fingerprint.

Deploy the scanner after building

  1. Generate a provisioning token in Config > Scanners > Add Scanner.
  2. Copy the one-time curl command from the modal.
  3. On the target host, place the verified binary at /usr/local/bin/mipo-scanner.
  4. Run the curl command to register the scanner and create the systemd service.
  5. Start the service: sudo systemctl enable --now mipo-scanner

Gotchas

  • GET /scanner/binary/:platform/:arch always returns 501 by design — this is not a missing feature or misconfiguration.
  • Valid platforms are linux, darwin, and windows. Valid architectures are amd64 and arm64. Invalid combinations return 400.
  • The binary must be built with CGO_ENABLED=0 to produce a statically linked binary with no runtime libc dependency.
  • Always verify the binary hash before deployment. The dashboard shows the expected hash for the current release.
  • The scanner binary uses Go standard library only — no third-party runtime dependencies. This keeps the attack surface minimal and enables reproducible builds.
  • Who signs vs who verifies: the Ed25519 private key lives only in the build pipeline of whoever BUILDS the binary (mipo CI for project releases; your own key via scripts/ops/sign-scanner.sh if you build from source — no CI required). Scanner hosts only ever hold the public key. Nobody needs access to the builder's GitLab or build system to verify.
  • Two-channel trust is the point of signing: the binary and .sig arrive via the manager, but scanner.pub is pinned from an independent channel (the source repo or the public docs site). A compromised manager can serve a tampered binary with a MATCHING hash — it cannot forge a signature the independently-pinned key accepts. The guarantee is only as strong as the independence of the public-key channel.
  • Organizations that build from source are their own signing authority: generate a keypair (openssl genpkey -algorithm ED25519), commit your scanner.pub, sign each build, and pin your own key on scanner hosts. One keypair per binary-producing organization; zero private keys on consuming hosts.
  • Signature verification is mandatory by default (MIPO_REQUIRE_SIG=1): absent mipo-scanner.sig or absent /etc/mipo/scanner.pub causes install.sh / upgrade.sh to exit 1 with a clear error message. Set MIPO_REQUIRE_SIG=0 to revert to the previous conditional behavior (warn-and-continue when either artifact is absent). Hash verification alone cannot survive a compromised manager.

API calls (1)

MethodPathDescription
GET /scanner/binary/:platform/:arch Returns 501 Not Implemented with the build command for the requested platform/arch. Platforms: linux, darwin, windows. Architectures: amd64, arm64.

Related

  • Ingest Health — The binary download endpoint is served by the ingest service
  • Scanners — Scanner provisioning and binary hash verification
  • Scanner Heartbeat — After building and deploying, the scanner sends heartbeats through the ingest protocol