On-Prem Registry Proxy

Overview

The Aikido On-Prem Registry Proxy can be deployed as a transparent package firewall, allowing organizations to enforce package security policies without requiring developers or CI systems to change their package manager configuration.

Instead of configuring clients to use private registry URLs or special proxy paths, organizations redirect supported public package registries to the Aikido Registry Proxy using corporate DNS. Developers continue using the default package manager configuration, while the proxy transparently evaluates requests before retrieving content from the public registries.

Architecture

Running the Proxy

docker run -p 8080:8080 -e DEPLOYMENT_MODE=onprem public.ecr.aws/aikido-security/aikido-registry-proxy:latest

The proxy runs on port 8080 and expects TLS to be terminated at the ingress layer. The ingress must forward the original Host header (or set X-Forwarded-Host) so the proxy can identify the ecosystem.

A health endpoint is available at GET /health (no authentication required), suitable for Kubernetes liveness and readiness probes.

Configuration

Supported Host Mapping

The Registry Proxy routes requests to the appropriate ecosystem based on the incoming HTTP Host header.

Registry Compatibility

Metadata responses do not rewrite URLs to proxy paths. Clients receive URLs in their original public registry format and are never redirected to non-intercepted hosts.

npm

• Packument responses remain compatible with registry.npmjs.org.
• Tarball downloads use the standard npm workflow.

PyPI

• Metadata requests are served from pypi.org.
• Package downloads are served from files.pythonhosted.org.

Maven

• Requests to Maven Central use the standard /maven2/... path.

Egress IP and Rate Limiting

Because all proxied traffic egresses from a single IP (or two IPs with two replicas), Maven Central and other public registries may rate-limit or block requests that originate from that IP. This is a known limitation of the transparent proxy model.

To mitigate this, consider routing egress traffic through a NAT gateway with multiple IPs, or pointing the upstream URL overrides at an internal mirror that is not subject to public registry rate limits.

Preventing Upstream Routing Loops

The proxy resolves all of its own outbound calls using the UPSTREAM_DNS resolver (default 1.1.1.1), bypassing the container's system DNS entirely. This means even if the pod inherits the intercepting corporate DNS, the proxy's upstream fetches always reach the real public registries and never loop back.

No split-horizon DNS configuration is required on the proxy host itself. As an additional safeguard, you can configure the pod's DNS resolver explicitly via Kubernetes dnsConfig.

Request Flow

1. A developer or CI system installs a package using the standard package manager.
2. Corporate DNS resolves the public registry hostname to the internal Registry Proxy.
3. The Registry Proxy receives the request using the original HTTP Host header.
4. The proxy determines the target ecosystem based on the requested hostname.
5. Malware detection and minimum package age policies are evaluated.
6. If the request is allowed, the proxy retrieves the package or metadata from the corresponding public registry.
7. The response is returned transparently to the client.