Skip to content

NeuBird Proxy

The NeuBird Proxy is a redacting reverse proxy that you run in your own Kubernetes cluster, between NeuBird and your internal systems (Splunk, ServiceNow and other APIs). Use it when those systems aren’t reachable from the internet, or when you want to control exactly what NeuBird can send to them and receive from them.

On every request, the proxy:

  • Limits where requests go. It forwards only to the hosts you allow (neubird_destinations.hosts). It never connects to loopback, link-local or cloud metadata addresses.
  • Limits what requests do. By default it allows only GET and HEAD. You can block request patterns, such as Splunk commands that write, send or delete data.
  • Masks sensitive data in responses. Emails, SSNs, phone numbers, card numbers, IP addresses, dates of birth and secrets (JWTs, API keys, private keys) are masked before the response leaves your network. You can add your own patterns.
  • Fails closed. If it can’t redact a response (for example, a binary body or an oversized body), it refuses the response instead of passing it through.
  • Audits each request. It writes one log line per request with the destination, path, status and masking counts. Credentials and matched values are never logged.

You set which hosts NeuBird may reach once, in the proxy’s config. After that, you add, change and remove systems in NeuBird as ordinary connections, each with its own URL and credentials, without changing the proxy.

The proxy runs in one of two modes. Both apply the same checks and redaction; they differ in how NeuBird’s requests reach the proxy.

Outbound (tunnel)Inbound (proxy-only)
How requests arriveThe proxy opens outbound TLS tunnels to your dedicated NeuBird relay; requests come back over themYour API gateway forwards requests to the proxy’s Service on port 8443
Inbound exposureNone: nothing listens for inbound connectionsThrough your own gateway
FirewallOutbound 443 to your relay onlyWhatever your gateway needs
AuthenticationThe mutually authenticated tunnel; no proxy tokenA proxy token your gateway sends on every request
Chart valuemode: tunnel (the default)mode: inbound
Choose it whenYou want the simplest setup and no inbound pathYour policy requires all external traffic to pass through your API gateway

If you’re not sure, use outbound.

flowchart LR
  subgraph Outbound
    direction LR
    N1[NeuBird] --> R[Your NeuBird relay]
    P1[neubird-proxy] -- "opens tunnel :443" --> R
    P1 --> S1[Your systems]
  end
flowchart LR
  subgraph Inbound
    direction LR
    N2[NeuBird] --> G[Your API gateway]
    G -- ":8443" --> P2[neubird-proxy]
    P2 --> S2[Your systems]
  end
Helm chartoci://ghcr.io/neubirdai/charts/neubird-proxy, version 1.0.0
Imagedocker.io/neubirdai/neubird-proxy, build cc97e4f
Image digest (multi-arch index)sha256:78197d45a38c2ac25cacc6973a6af56c443345902258e543652ffa51f12a139b
Platformslinux/amd64, linux/arm64

Copy the image with a tool that keeps the multi-arch index, so the digest stays the same. For example, on Azure Container Registry:

Terminal window
DIGEST=sha256:78197d45a38c2ac25cacc6973a6af56c443345902258e543652ffa51f12a139b
az acr import --name <acr-name> \
--source docker.io/neubirdai/neubird-proxy@$DIGEST \
--image neubird-proxy/neubird-proxy:cc97e4f
# confirm the digest in your registry
az acr repository show -n <acr-name> --image neubird-proxy/neubird-proxy:cc97e4f --query digest

For other registries, crane copy or skopeo copy --all keep the index too.

For either mode, you need:

  • Kubernetes access: kubectl with a context for the target cluster and rights to create a namespace, plus Helm 3.8 or later.
  • The image in a registry your cluster can pull from (see above). If the registry is private, you also need a docker-registry pull Secret in the namespace.
  • The hostnames of the systems NeuBird should reach. Their credentials go into NeuBird, not into the proxy.
  • Network access from the cluster to those systems.
  • An internal CA bundle, only if a system’s certificate is issued by an internal CA. You pass it to the chart as upstreamCA.

Each setup guide lists what else that mode needs.