zot Registry Documentation

The search component provides enhanced registry search capabilities using a GraphQL backend. It allows for complex queries including searching by digest, CVE vulnerability status, image relationships (base/derived), and global registry scans.

To interact with the search component, you can send GraphQL queries via HTTP POST requests to the endpoint: http://<host>:<port>/v2/_zot/ext/search.

Example using curl:

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ ImageListForCVE (id:\"CVE-2002-1119\") { Results { RepoName Tag } } }" }' http://localhost:8080/v2/_zot/ext/search

The mgmt component provides an endpoint for managing and inspecting the current Zot configuration. The response returned by the endpoint is subject to user privileges:

• Unauthenticated and Authenticated users: Receive a stripped version of the configuration.
• Admins: Receive the full configuration (note: password hiding for admins is currently not implemented).

If ldap or htpasswd are enabled, the response will include {"htpasswd": {}} (or similar for LDAP) to indicate that clients can authenticate using those specific methods. Any key present under the 'auth' object in the response signifies that the corresponding authentication method is enabled.

The zot extension provides several specialized capabilities accessible through the /v2/_zot endpoint prefix. These components allow for enhanced registry search, configuration management, user preference updates, and image trust management (via cosign or notation).

zot is a container registry designed for minimal builds, OCI conformance, and built-in features that often require auxiliary components in other registries like docker distribution.

Key advantages of zot include:

• Storage Layout: Uses the ociv1 image layout.
• Security: Built-in authentication, authorization, vulnerability scanning, and image signature support (including Notation and Cosign).
• Maintenance: Inline garbage collection and storage deduplication (unlike docker distribution which may require server shutdown for GC).
• Management: Supports deleting by tag and includes a built-in UI.
• Compliance: Fully conforms to the distribution-spec.

zot supports two types of underlying filesystems for storage:

1. local: A locally mounted filesystem.
2. remote: A remote filesystem, such as AWS S3.

Ensure your configuration specifies the appropriate storage type based on your environment requirements.

When using AWS Secrets Manager for key retrieval, every JWT presented to Zot must include a kid (Key ID) header. Zot uses this kid to look up the corresponding public key in the secret fetched from AWS.

Example JWT Header:

{
  "alg": "EdDSA",
  "kid": "key-id-1",
  "typ": "JWT"
}

A Generator is an abstraction used to produce tasks one by one. To create a custom generator, you must implement the following four methods:

1. Next() (Task, error): Implements the logic to generate the next task. It should return tasks sequentially until no more are available. The returned Task must implement the DoWork(ctx context.Context) method.
2. IsDone() bool: Returns true when the generator has finished all work and has no more tasks to produce.
3. IsReady() bool: Returns true if the generator is ready to produce a new task. This is used to introduce delays between task generations.
4. Reset(): Resets the generator to its initial state. This is used by the scheduler for periodic generators to restart the generation cycle after a specified interval.

A Task represents a single unit of work. To create a custom task, you must implement the following three methods:

1. DoWork(ctx context.Context) error: Contains the actual logic to be executed when the scheduler runs the task.
2. Name() string: Returns the name of the task.
3. String() string: Returns a description of the task, primarily used for debugging and identification during execution.

Zot uses session cookies for authenticated users.

Session Drivers:

• local: Uses the filesystem (for local storage) or in-memory (for cloud storage). This is the default.
• redis: Use a Redis instance for shared sessions across multiple Zot instances. Requires url and keyprefix.

Securing Sessions: To prevent session hijacking/tampering, use sessionKeysFile to provide keys for HMAC hashing and AES encryption. The file should contain a JSON object with hashKey and optionally encryptKey.

• hashKey: Used for HMAC. Recommended length: 32 or 64 bytes.
• encryptKey: Used for AES encryption. Valid lengths: 16, 24, or 32 bytes.

"auth": {
  "sessionDriver": {
    "name": "redis",
    "url": "redis://localhost:6379",
    "keyprefix": "zotsession"
  },
  "sessionKeysFile": "/home/user/keys"
}