Skip to main content
emisar

zot OCI registry

v0.1.10

Read-only inspection of a zot OCI registry over its HTTP API: the OCI distribution endpoints (version check, catalog, tags, manifests) plus the zot extensions — registry config/health (mgmt), Prometheus metrics, and a GraphQL search query that returns per-repo size and a newest-image vulnerability summary. Optional basic-auth credentials are streamed over curl stdin; many zot deployments allow anonymous read.

7 allowed by default
Pack ID
zot
Vendor
emisar
OS
linux
Actions
7
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install zot --hash sha256:7d97984a45c0a07b7b1f097194372e460af2ce31cd3b60b27edcf8ee4691ccb2

Setup

Every action calls the zot HTTP API at $ZOT_URL via curl on the runner host. Optional basic-auth credentials "user:password" are read from $ZOT_BASICAUTH , base64-encoded, and sent as an Authorization header over curl stdin, so they never appear in the process arguments or the audit log.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • ZOT_URL default http://127.0.0.1:5000

    Base URL of the zot registry — scheme, host, and port. Each action appends its path (e.g. /v2/, /v2/_catalog).

  • ZOT_BASICAUTH

    Optional user:password for registries that require auth; base64-encoded and sent as an Authorization header over curl stdin, never argv. Leave unset for anonymous-read registries.

Notes

  • Any of ZOT_URL / ZOT_BASICAUTH you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
  • Every action is read-only: GET, plus POST only to the read-only search GraphQL extension. Push/delete of manifests and blobs, and userprefs writes, are deliberately excluded.
  • The search/mgmt/metrics extensions require the full (extended) zot build — search/ui/mgmt are on by default; metrics must be enabled in config.
  • mgmt and metrics typically require auth and are denied to anonymous clients; set ZOT_BASICAUTH for those.

Verify it works

Runs zot.v2_base, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify zot

Install and configure a pack walks through the whole sequence on a host.

Actions 7 total

View on GitHub
  • zot.catalog script low Low — read-only or trivially reversible

    GET /v2/_catalog

    List the repositories in the registry. Large registries paginate via the ?n=<count>&last=<repo> query parameters; this returns the first page. Use to inventory what is stored. Read-only.

    View source on GitHub
  • zot.manifest script low Low — read-only or trivially reversible

    GET /v2/{repo}/manifests/{reference}

    Read the image manifest for a repository at a given reference (a tag or a digest). Returns the layer/config descriptors and annotations for that image. Read-only.

    View source on GitHub
  • zot.metrics script low Low — read-only or trivially reversible

    GET /metrics

    Show Prometheus-format metrics for the registry via the zot metrics extension — request counts, storage, and runtime gauges. Requires the full (extended) build with the metrics extension enabled in config, and typically auth (set ZOT_BASICAUTH). Read-only.

    View source on GitHub
  • zot.mgmt script low Low — read-only or trivially reversible

    GET /v2/_zot/ext/mgmt

    Show registry configuration and health via the zot mgmt extension — the active config (extensions enabled, storage settings) and a health summary. The mgmt extension is on by default in the full build but requires auth and is denied to anonymous clients, so set ZOT_BASICAUTH. Read-only.

    View source on GitHub
  • zot.search script low Low — read-only or trivially reversible

    POST /v2/_zot/ext/search (repo inventory + vuln summary)

    List repository inventory with per-repo storage size and a newest-image vulnerability summary, via the zot search GraphQL extension. This is how you get per-repo storage size + CVE summary — zot has no plain storage-usage endpoint, and garbage collection is not inspectable over HTTP. The GraphQL query is read-only (a RepoListWithNewestImage read). Read-only.

    View source on GitHub
  • zot.tags script low Low — read-only or trivially reversible

    GET /v2/{repo}/tags/list

    List the tags available for a single repository. Use after the catalog to see which versions of an image are published. Read-only.

    View source on GitHub
  • zot.v2_base script low Low — read-only or trivially reversible

    GET /v2/

    Check the OCI distribution base endpoint. A 200 confirms the registry is up and speaking the v2 API, and the response advertises the supported distribution-spec version. Use as a reachability/version check.

    View source on GitHub
← Back to registry
Pack reference  Publish your own