Open Source · OCI-Compliant · Rust-Powered

Your Images.
Your Infrastructure.
Zero Compromise.

NebulaCR is a cloud-native OCI container registry built in Rust. Multi-region replication, enterprise AD/OIDC authentication, pull-through caching, and a real-time dashboard — all in a single binary.

Get Started View on GitHub
OCI Distribution Spec Multi-Region Replication Enterprise SSO/OIDC Built in Rust
📦
OCI Registry
Full OCI Distribution Spec compliance. Push, pull, and manage container images with Docker, Podman, or any OCI client.
🌍
Multi-Region
Async replication across regions with automatic failover, health checks, and circuit breaker protection.
🔒
Enterprise Auth
OIDC/AD SSO, group-to-role mapping, robot accounts, short-lived tokens, and zero static credentials.
⚡
Rust Performance
Single binary, minimal memory footprint, async I/O with Tokio. Handles thousands of concurrent pulls.
🔎
CVE Scanning
Built-in scanner for every push: SBOM extraction, OSV/GHSA/NVD matching, AI-assisted remediation, nightly PDF reports.

Everything You Need for Container Images

From development to production, NebulaCR covers the entire container image lifecycle.

📦
OCI Distribution API
Full implementation of the OCI Distribution Specification. Compatible with Docker, Podman, Buildah, containerd, and any OCI-compliant client.
  • Manifest push/pull/delete (v2 schema)
  • Chunked and monolithic blob uploads
  • Multi-tenant with tenant/project/repo hierarchy
  • Tag listing and catalog API
  • Content-addressable storage by digest
🌍
Multi-Region Replication
Async replication of manifests and blobs across regions. Circuit breaker and retry logic ensure resilience during network partitions.
  • Async event-driven replication
  • Circuit breaker with configurable thresholds
  • Exponential backoff with jitter
  • Health check loop with failover
  • Read failover to healthy regions
🔒
Enterprise Authentication
OIDC Authorization Code flow with PKCE for Azure AD, Okta, and Google. Group-based role mapping, robot accounts, and token rotation.
  • OIDC/AD SSO with group-to-role mapping
  • CI/CD OIDC federation (GitHub, GitLab, K8s)
  • Robot accounts for machine identity
  • Refresh tokens with revocation
  • Short-lived JWT tokens (5 min default)
🔍
Pull-Through Cache
Mirror upstream registries (Docker Hub, GHCR, Quay) with automatic caching. Reduce bandwidth costs and improve pull latency.
  • Configurable upstream registries
  • Automatic manifest and blob caching
  • TTL-based cache invalidation
  • Transparent to Docker clients
  • Authenticated upstream support
🔎
Image Vulnerability Scanning
Every push is scanned in-process by the embedded nebula-scanner. SBOMs are built natively in Rust — no Trivy/Grype shell-out — then matched against OSV, GHSA, and NVD with ecosystem-aware version comparators.
  • SBOM parsers: dpkg, apk, rpm, npm, pypi, cargo, go, ELF
  • OSV bootstrap + local NebulaVulnDb (OSV/GHSA/NVD ingest)
  • Version matchers for apk, deb, rpm, semver, pep440, Go
  • VEX 1.4 ingestion (not_affected / fixed / under_investigation)
  • Pass/fail policy gate with per-severity thresholds
🤖
AI-Assisted Remediation
On-demand AI commentary on every CVE via Ollama (local LLM, no third-party calls). Generates Dockerfile fix suggestions and posts PR review comments straight into your build pipeline.
  • Per-CVE root-cause + impact summary
  • Dockerfile rewrite suggestions (/v2/scan/{id}/dockerfile-fix)
  • One-click PR review comment posting
  • CycloneDX SBOM + JSON report export to S3
  • WebSocket progress stream for live UIs
📊
Real-Time Dashboard
Embedded web dashboard with live metrics. Browse images, search repositories, monitor replication health, and track push/pull activity.
  • Image browser with wildcard search
  • CPU, RAM, disk usage monitoring
  • HA region health status
  • Audit log with filtering
  • Identity and access management
🛡
Security & Compliance
JWT-based auth with RS256/EdDSA signing. Rate limiting, network policies, audit logging, and Vault integration for key management.
  • HashiCorp Vault integration (Transit + KV)
  • Per-tenant rate limiting
  • Kubernetes NetworkPolicy templates
  • Full audit trail (push/pull/delete)
  • Webhook notifications for events
☸
Kubernetes Native
Helm chart with CRDs for Tenant, Project, AccessPolicy, and TokenPolicy. Horizontal autoscaling, pod anti-affinity, and service monitors.
  • Helm chart with comprehensive values
  • Custom Resource Definitions (CRDs)
  • HPA for registry and auth pods
  • Ingress with TLS termination
  • ServiceMonitor for Prometheus
💾
Flexible Storage
Store images on local filesystem, Amazon S3, Google Cloud Storage, or Azure Blob Storage. Object store abstraction via the object_store crate.
  • Filesystem with persistent volumes
  • Amazon S3 and S3-compatible (MinIO)
  • Google Cloud Storage
  • Azure Blob Storage
  • Configurable storage backends per deployment

Built-In Dashboard

A dark-themed operations dashboard with real-time metrics, image browsing, and identity management — embedded in the registry binary.

📊
System Metrics
CPU, RAM, disk usage with color-coded thresholds. HA region health with latency and failure counts.
📦
Image Browser
Search and browse all repositories with wildcard support. View tags, tag counts, and repository details.
📝
Activity & Audit Log
Real-time event feed: pushes, pulls, deletes. Filter by event type, user, or repository.
👥
Identity & Access
Users, groups, and service accounts. View SSO logins, group-role mappings, and robot account status.

Enterprise-Ready Identity

Zero static credentials. Seamless integration with your existing identity infrastructure.

🏢
Active Directory / Azure AD
OIDC Authorization Code flow with PKCE. Login with "Sign in with Azure AD" or any OIDC provider. Auto-provision users on first login with group sync.
👥
Group-Based Access Control
Map AD groups to NebulaCR roles: nebulacr-admins to Admin, nebulacr-devs to Maintainer, nebulacr-viewers to Reader. Per-tenant and per-project granularity.
🤖
Machine Identity
CI/CD OIDC federation for GitHub Actions, GitLab CI, and Kubernetes service accounts. No static secrets. Short-lived, scoped tokens auto-expire in 5-15 minutes.
🔄
Token Rotation & Revocation
Refresh token flow for long-lived sessions. Instant token revocation via API. Robot accounts with configurable expiry for automation pipelines.
📋
SCIM 2.0 Provisioning — Automated User Lifecycle
NebulaCR implements the SCIM 2.0 protocol (RFC 7644), enabling Azure AD, Okta, and OneLogin to automatically provision and deprovision users. When someone joins your org, SCIM pre-creates their registry access instantly — no first-login delay. When they leave, access is revoked in seconds, not minutes. Group membership changes sync immediately without requiring a new login.
ScenarioWithout SCIMWith SCIM
New hireMust login firstPre-provisioned instantly
Team changeNext login syncsImmediate role update
OffboardingToken expires in 5 minInstant revocation
Audit "who has access?"Only logged-in usersAll entitled users
500+ developersWorks but blind spotsFull visibility

How It Works

From deployment to pushing your first image in four steps.

Deploy Registry
Deploy NebulaCR via Helm chart to Kubernetes, Docker Compose, or as a native binary on bare metal. Single binary, no runtime dependencies.
Configure Auth
Connect your OIDC provider (Azure AD, Okta, Google). Map AD groups to roles. Enable CI/CD OIDC federation for GitHub Actions or GitLab.
Push Images
Login with docker login using SSO or robot account credentials. Push images to your multi-tenant registry with automatic replication.
Monitor & Scale
Use the built-in dashboard to monitor health, browse images, and manage access. Prometheus metrics for alerting. Scale with HPA.

CVE Scanning — How It Works

Built into the registry. Triggered on every push. No external scanner pod, no Trivy daemon, no shell-out.

Push Triggers Scan
A successful manifest push enqueues a scan keyed by digest. The scanner runs in-process inside nebula-registry, or in a dedicated nebula-scanner worker.
SBOM Extraction
Layers are pulled from object storage and walked for OS packages (dpkg/apk/rpm) and language deps (npm/pypi/cargo/go). Output is a CycloneDX SBOM.
Vuln Match + Policy
Packages are matched against OSV, GHSA, and NVD with ecosystem-aware comparators. Suppressions and VEX statements filter noise; a policy decides PASS / FAIL.
Report + Notify
Results land in Redis (1h TTL), the dashboard, and optionally Slack. AI commentary, Dockerfile fix suggestions, and PR comments are one API call away.

Scanner API Endpoints

EndpointDescription
GET /v2/scan/live/{digest}Poll-until-complete scan result
POST /v2/scanTrigger a scan for a (repo, tag)
GET /v2/scan/{id}/reportRendered scan report
GET /v2/scan/{id}/sbomCycloneDX SBOM
GET /v2/scan/{id}/dockerfile-fixAI-suggested Dockerfile remediation
POST /v2/scan/{id}/pr-commentPost results as a GitHub PR review comment
GET /v2/ws/scan/{digest}WebSocket progress stream
GET /v2/cve/searchCross-image CVE search
POST /v2/vexIngest CycloneDX VEX statements
POST /admin/vulndb/ingestTrigger an OSV/GHSA/NVD ingest run

All /v2/scan/** and /admin/** routes accept Authorization: Bearer nck_<secret> API keys with per-permission scoping.

Nightly Scan Automation

WorkflowTriggerScope
nightly-cve-scan.ymlManual dispatchCompose stack scan against a fixed image list (smoke test)
nightly-cve-scan-all.ymlCron 03:17 UTC + dispatchEnumerates /v2/_catalog and scans every (repo, tag) in the registry
deploy-nightly-cve-scan.ymlPush to deploy/k8s/nightly-cve-scan/**Deploys the in-cluster k3s CronJob — the production schedule

Each run produces JSON per (repo, tag), a rolled-up PDF via scripts/nightly-report-pdf.py, and a Slack upload via files.getUploadURLExternal (with a webhook text fallback).

Installation

Three ways to get started with NebulaCR.

Deploy to Kubernetes with Helm

# Install NebulaCR helm install nebulacr deploy/helm/nebulacr \ -n nebulacr --create-namespace \ -f values-production.yaml # Verify kubectl -n nebulacr get pods curl https://registry.example.com/health # Push your first image docker login registry.example.com docker push registry.example.com/myteam/myapp:latest # Open dashboard open https://registry.example.com/dashboard

Run with Docker

# Pull and run NebulaCR docker run -d --name nebulacr \ -p 5000:5000 -p 5001:5001 \ -v nebulacr-data:/var/lib/nebulacr/data \ ghcr.io/bwalia/nebulacr:latest # Push an image docker tag myapp:latest localhost:5000/demo/default/myapp:latest docker push localhost:5000/demo/default/myapp:latest # Open dashboard open http://localhost:5000/dashboard

Build from Source (Rust 1.80+)

# Clone and build git clone https://github.com/bwalia/nebulacr.git cd nebulacr cargo build --release # Generate JWT keys openssl genrsa -out private.pem 2048 openssl rsa -in private.pem -pubout -out public.pem # Run the registry ./target/release/nebula-registry --config=config.yaml # Run the auth service ./target/release/nebula-auth --config=config.yaml

Architecture

NebulaCR is composed of modular Rust crates, each handling a specific concern.

                          Docker / Podman / containerd
                                    |
                         OCI Distribution API (HTTPS)
                                    |
                    +---------------+----------------+
                    |                                |
              nebula-registry (:5000)          nebula-auth (:5001)
              /    |     |     \                /    |    \
         Manifests Blobs Tags Dashboard    OIDC  JWT  Robot
            |       |     |      |          |     |    Accounts
         Storage  Audit  Webhook Mirror   Vault  JWKS  CI/CD
            |                    |                      OIDC
      +-----+------+     +------+------+
      | filesystem | ... | S3 / GCS   |
      +------------+     +------------+

              nebula-replication
              /        |        \
         Events    Circuit     Failover
                   Breaker     Manager
                      |
            +----+----+----+
            |    |    |    |
          Region1  Region2  Region3  ...

   Metrics: Prometheus at :9090/metrics
   Dashboard: embedded at :5000/dashboard

API Endpoints

EndpointDescription
GET /v2/OCI version check
GET/PUT/DELETE /v2/{t}/{p}/{n}/manifests/{ref}Manifest operations (push/pull/delete)
POST/PATCH/PUT /v2/{t}/{p}/{n}/blobs/uploads/Blob upload (chunked or monolithic)
GET /v2/_catalogRepository catalog listing
GET/POST /auth/tokenDocker-compatible token exchange
GET /auth/oidc/loginOIDC SSO login redirect
POST /auth/ci/tokenCI/CD OIDC token exchange
GET /dashboardWeb dashboard
GET /api/images?q=searchImage browser API
GET/POST /scim/v2/UsersSCIM 2.0 user provisioning
GET/POST /scim/v2/GroupsSCIM 2.0 group management
GET /healthHealth check
GET /metricsPrometheus metrics

Project Structure

nebulacr/ crates/ nebula-registry/ # OCI registry + dashboard nebula-auth/ # Auth service (OIDC, JWT, RBAC) nebula-common/ # Shared models, config, storage nebula-replication/ # Multi-region replication nebula-mirror/ # Pull-through cache nebula-resilience/ # Circuit breaker + retry nebula-controller/ # Kubernetes CRD controller deploy/ helm/nebulacr/ # Helm chart ansible/ # Native deployment playbooks docs/landing/ # This landing page

Ready to Own Your Container Registry?

Deploy NebulaCR and take full control of your container images. Open source, enterprise-ready.

Get Started Star on GitHub