docs/Using Flareo/Verify any container

Verify any container

The verification tool at flareo.app/verify is not limited to Flareo-signed modules. It works on any OCI image, from any registry, as long as the image has a Sigstore signature manifest attached in the standard :sha256-<digest>.sig form.

What the tool actually does

Given an image reference like registry.example.com/app:v1.2.3:

  1. Parse. Splits the ref into registry, repository, tag, and (if given) digest. Supports Docker Hub shorthand (alpine:3.20), GHCR, ECR Public, Quay, and any other v2-compliant OCI registry.

  2. Resolve tag → digest. If you gave a tag, the tool does a HEAD request to the registry's manifest endpoint to pin down the sha256 digest. Tags can be moved; digests cannot. All subsequent checks run against the digest.

  3. Fetch and verify the signature. cosign writes signatures as a sibling image tagged <repo>:sha256-<hex>.sig. The tool GETs that manifest, locates a recognised Sigstore bundle layout (a Sigstore bundle layer, or the older simplesigning layer with cosign annotations), and verifies the bundle against the Sigstore public-good trust root. A 404 means unsigned. A present but unrecognised layout, or a cryptographic failure, means invalid — not unsigned.

  4. Cross-reference with the Flareo catalog. If the digest matches a Flareo-signed module, we enrich the result with the catalog metadata — trust score, CVE counts, SBOM link, scan report link. Signer identity, issuer, and Rekor index always come from the verified bundle; if a catalog row disagrees, the bundle wins and the mismatch is surfaced.

Possible results

Verified. The image has a valid Sigstore signature AND it's in the Flareo catalog with an acceptable CVE status. You see the signer identity, Rekor log index, and full catalog metadata.

Signed. The image has a valid Sigstore signature but isn't in the Flareo catalog. You still get the resolved digest, signer identity, OIDC issuer, and Rekor log index from the verified bundle. Flareo does not make a full trust claim (no scan, no trust score) for images it did not catalog — see ADR-014.

Unsigned. No Sigstore signature manifest exists for this image. Very common for images pushed without a signing step. Not a statement about the image being bad — just a statement that there's no cryptographic provenance to check.

Invalid. Verification failed or the signature is present but rejected. Causes include a bad signature, a certificate-chain failure, an unrecognised bundle layout, or (for catalog images) a CVE threshold breach after a successful cryptographic check.

Error. We couldn't reach the registry, the request timed out, or something else went wrong before a verification outcome was possible. Registry outages are not reported as unsigned or invalid.

What this is not

The endpoint verifies the signature and the Fulcio certificate chain. It does not enforce a keyless identity policy — any correctly signed third-party image can return signed. It also does not run an on-demand Trivy scan of arbitrary images, and it does not replace cosign verify when you need to pin a specific signer identity in your own policy. For offline / identity-pinned checks, use Verify from the CLI against cosign directly.

Rate limits

The /api/v1/verify endpoint is rate-limited to:

  • 60 requests per hour per IP for unauthenticated callers
  • 600 requests per hour per user for authenticated callers

If you need more, sign in with GitHub — that alone bumps you to the authenticated bucket.

Next steps