Overview:

A high level summary that describes the Epic in a clear, concise way.Complete during New status.

1. Automate base image tag discovery by polling container registries. Customers maintain 30-50 base image patterns (e.g., `ubi8:8.10-`, `alpine:3.19-`) with monthly rebuilds. Manual tag management requires 40+ updates/month. This epic  implements periodic registry polling, tag filtering/sorting, and storage for base
   image matching.
2. Supports both public registries (Docker Hub, Quay) and private cluster-local registries via delegated scanning pattern.

Requirements:

_A list of specific needs or objectives that an epic must deliver in order to be considered complete. Be sure
to include nonfunctional requirements such as security, reliability, performance, maintainability, scalability,
usability, etc._ Initial completion during Refinement status.

Functional:

• Periodic registry polling (configurable interval, default 4 hours)
• Tag filtering using glob patterns (e.g., `8.10-*`)
• Semver-based tag sorting (descending: newest first)
• Support 30-50 repository patterns per organization
• Store top 100 tags per pattern (configurable)
• Delegate tag listing to Sensor for private registries

Non-functional:

• Performance: Single API call per repository per cycle (minimize registry load)
• Reliability: Health tracking for failed repositories, retry with backoff
• Scalability: Support 100+ base images across deployed workloads
• Security: Reuse existing registry credentials, no new auth mechanisms
• Maintainability: Extend existing delegated scanning infrastructure

Technical Scope:

_High-level list of items that are in scope; usually completed by a staff engineer or a lead
from the Feature Delivery Team._ Initial completion during Refinement status.

• s

Out of Scope:

High-level list of items that are out of scope. _Initial completion
during Refinement status._

• Base image layer matching logic (separate epic/design)
• Timestamp-based tag sorting (Proposal 2 - future enhancement if customers need re-tag detection)
• Full image enrichment during discovery (layers fetched via existing reprocessor)
• Repository-level filtering via `/v2/_catalog` (only tag-level filtering)
• Multi-cluster support for same registry (inherits DelegatedRegistryConfig limitation)
• Scanner integration for base image vulnerability detection (separate track)

Outstanding Questions (Optional):

Include a list of refinement / architectural questions that may need to be answered before
coding can begin. Initial completion during Refinement status.

Critical:

1. Library conflict: POC uses `google/go-containerregistry`, production uses `heroku/docker-registry-client`.
Which to standardize on?
2. Pagination bug: Is it fixed in `stackrox/docker-registry-client v0.2.0`? Must verify with >100 tag
repository before implementation.

Important

3. Storage strategy: Extend WatchedImage table OR create dedicated BaseImage table? (Recommendation: BaseImage for separation)
4. Tag limit enforcement: Prune at discovery time (top 100 by semver) OR storage time with timestamp-based pruning? (Recommendation: Discovery time for Proposal 1)
5. Error handling: Skip and retry vs exponential backoff vs health tracking?(Recommendation: Health tracking for visibility)
6. Layer storage hook: Extract layers in reprocessor OR in enricher? (Recommendation: Reprocessor for centralization)