| name | registry-mirror-trust |
| description | Design, assess, and harden trust in registry mirrors and pull-through caches for containers and packages (Harbor, Artifactory, Nexus, ECR/GHCR proxies, npm/PyPI/Maven mirrors). Use when clients resolve artifacts via a corporate mirror, when pull-through cache integrity is unclear, when TLS or signing at the mirror edge is weak, or when air-gapped/proxy registry policy must fail closed — hand namespace confusion to dependency-confusion; image Cosign/admission to container-image-signing; lockfile pins to dependency-pinning-strategies.
|
Registry Mirror Trust
Make every install and image pull go through an authorized mirror whose
upstream, integrity, and write path you control. Internal hosting alone is
not trust: treat TLS, auth, cache poisoning, stale upstream, and who can push
or overwrite as first-class risks.
When To Use
- Clients use a pull-through cache, proxy registry, or air-gapped sync
(Harbor, Artifactory, Nexus, Verdaccio, cloud pull cache, package group repos)
- CI/dev points at a corporate registry, custom
GOPROXY, Maven mirror, or
index-url that is not the public origin
- Unclear whether the mirror verifies upstream TLS/signatures, rewrites digests,
or allows anonymous/unscoped push
- Mentions: pull-through, registry mirror, proxy cache, Harbor, Nexus group,
Artifactory remote, corporate npm/PyPI mirror, content trust at the edge
Do not use as primary for:
| Need | Skill instead |
|---|
| Public vs private name confusion / dual index | dependency-confusion |
| Cosign/Sigstore sign + cluster admission | container-image-signing |
| Lockfiles, ranges, Renovate/Dependabot | dependency-pinning-strategies |
| Dockerfile layers / non-root | dockerfile-best-practices |
| CI graph, OIDC job perms | ci-cd-pipeline-patterns |
| Tokens, mirror admin creds, leak IR | secrets-management-hygiene |
| Config/policy code quality | code-quality-standards |
Workflow
1. Inventory resolve path
- List consumers: CI runners, dev machines, K8s nodes, offline promotion jobs.
- Per ecosystem: configured registry/index host, auth, public fallback yes/no.
- Table: ecosystem | client config | mirror host | mode | upstream | auth | notes.
- Prefer one authoritative mirror per ecosystem in prod CI. Dual public +
private without routing is a trust split (
dependency-confusion).
2. Classify mirror mode
| Mode | Meaning | Trust focus |
|---|
| Pull-through / remote | Cache on first pull | Upstream TLS, remote allowlist, cache immutability |
| Hosted / local | Org-owned only | Push rights, retention, overwrite policy |
| Group / virtual | Aggregates remotes + local | Resolve order; deny open public merge |
| Air-gap sync | Offline copy from blessed source | Sync identity, promotion, quarantine |
Note tag mutability and whether digests survive cache/sync end-to-end.
3. Transport and identity
- TLS to the mirror in all prod clients; no insecure-registry shortcuts.
- Enterprise-CA or pinned trust for the mirror hostname.
- Anonymous pull only if policy allows; push via SSO/2FA or short-lived
robot tokens, least privilege per pipeline.
- Admin UI/API not world-reachable; MFA; audit config changes
(
secrets-management-hygiene).
4. Upstream and content integrity
- Allowlist remotes (Hub, ghcr.io, Maven Central URL)—not open proxy.
- Promote by digest (
@sha256:…), not floating tags alone.
- Preserve OCI referrers/signatures through cache; enforce verify/admission with
container-image-signing where required.
- Packages: lockfile integrity; fail if resolved host leaves mirror allowlist.
- Cache controls: immutable-by-digest where possible; block tag overwrite on
promoted repos; optional scan-before-serve quarantine.
- Isolate upstream credentials; avoid shared Hub tokens across untrusted jobs.
5. Write path and fail-closed
- Split proxy-cache (read-mostly) from internal publish projects.
- Deny developer push to proxy namespaces; publish only via CI identity.
- Air-gap: sync from verified bastion; promote by digest; log source + digest + job.
- Missing auth or downed mirror must not silently fall back to public for
internal-only names.
6. Verify
- Capture resolve URL/host for a known package and image (verbose client/CI log).
- Lab: non-allowlisted upstream pull → deny; unauthenticated push → deny.
- Re-pull: same digest; signatures/referrers still present if expected.
- Apply
code-quality-standards to mirror IaC and client registry config.
Routing
| Situation | Primary | Helper |
|---|
| Mirror/proxy/cache trust, pull-through, air-gap registry policy | This skill | — |
| Namespace / dual-index confusion | dependency-confusion | this for mirror routing |
| Cosign keyless sign/verify/admission | container-image-signing | this if mirror strips sigs |
| Lockfile pins / frozen install | dependency-pinning-strategies | mirror host in lock URLs |
| CI stages, robot OIDC to registry | ci-cd-pipeline-patterns | this for registry policy |
| Creds, robot tokens, admin secrets | secrets-management-hygiene | this |
| Dockerfile/image build hygiene | dockerfile-best-practices | this post-push |
| Implementation quality of configs | code-quality-standards | always on config |
Hand-offs: name confusion → dependency-confusion; image signature identity →
container-image-signing; pin/update bots → dependency-pinning-strategies.
Output Checklist
Scope And Authorization
- Owned orgs, labs, CTFs, or written SOW covering registry, CI, and client fleets.
- Do not reconfigure or probe third-party mirrors outside engagement scope.
- Prefer read-only inventory and lab dry-runs; gate purge, forced re-sync, or
credential tests on explicit approval.
- Never use a corporate mirror as malware distribution in PoCs.
- Redact registry tokens, robot passwords, and unnecessary internal hostnames.
- Evidence over assumption: show resolve host, digest, and policy—not “internal
therefore safe.”
