> For the complete documentation index, see [llms.txt](https://help.aikido.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aikido.dev/miscellaneous-integrations/private-registries/on-premise-transparent-proxy.md). # 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 ```bash 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
VariableDefaultDescription
DEPLOYMENT_MODERequired to override default and set to onpremRequired to setup the DNS Proxy
UPSTREAM_DNS1.1.1.1Public DNS resolver used for the proxy's own outbound calls. Must point to a real public resolver, not the intercepting corporate DNS. Accepts comma-separated values for multiple resolvers.
MINIMUM_PACKAGE_AGE_HOURS48Block packages published more recently than this threshold.
NPM_UPSTREAM_URLhttps://registry.npmjs.orgOverride to point at an internal npm mirror.
PYPI_UPSTREAM_URLhttps://pypi.orgOverride to point at an internal PyPI mirror.
PYPI_FILES_UPSTREAM_URLhttps://files.pythonhosted.orgOverride to point at an internal PyPI files mirror.
MAVEN_UPSTREAM_URLhttps://repo1.maven.org/maven2Override to point at an internal Maven mirror.
## Supported Host Mapping The Registry Proxy routes requests to the appropriate ecosystem based on the incoming HTTP Host header. | Public Hostname | Ecosystem | | ---------------------- | ------------- | | registry.npmjs.org | npm | | pypi.org | PyPI | | files.pythonhosted.org | PyPI | | repo1.maven.org | Maven Central | ## 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.aikido.dev/miscellaneous-integrations/private-registries/on-premise-transparent-proxy.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.