Outbound (tunnel) setup
In outbound mode, the proxy opens TLS tunnels from your cluster to your dedicated NeuBird relay on port 443. NeuBird’s requests come back over those tunnels. Nothing listens for inbound connections, so there’s no inbound firewall rule, load balancer or proxy token to manage.
NeuBird ──▶ your relay ⇄ tunnel (opened by the proxy, :443) ⇄ neubird-proxy ──▶ your systems checks host and request rules; redacts responsesSetup takes about an hour. These steps use Splunk and ServiceNow as example systems; replace them with your own.
Before you start
Section titled “Before you start”You need everything listed in Before you start, and also:
- From NeuBird:
- your relay’s address (for example
acme.tunnel.neubird.ai:443) and its IP addresses, for your firewall - your tenant name
relay-ca.crt, the relay’s CA certificate- a join token (
nbjt_...) for the proxy name you’ll use. The join token is secret and works only once.
- your relay’s address (for example
- Outbound HTTPS from the cluster to the relay on port
443. - No TLS inspection on that traffic. A corporate proxy that re-signs outbound HTTPS breaks the tunnel’s mutual TLS. If you route egress through an HTTP proxy, it must pass the connection through untouched (
CONNECT). - Docker on your machine, to run the proxy’s tools before you deploy anything. Every tool is a subcommand of the same image, so you check with the same version you deploy.
Set a shortcut for running the tools:
IMAGE=<your registry>/neubird-proxy/neubird-proxy@sha256:<digest>np() { docker run --rm -i -v "$PWD":/work -w /work "$IMAGE" "$@"; }np helpRun the commands from a directory under your home directory, because Docker Desktop and Colima share only that directory with containers.
1. Write the config
Section titled “1. Write the config”Create config.yaml:
# The Helm chart sets listen, admin_listen and tunnel. Requests arrive# through the tunnel, so nothing listens for them and there's no proxy token.# Secrets never go in this file: the proxy reads them from environment# variables, which come from a Kubernetes Secret.
# NeuBird names the system each request is for (the endpoint URL of its# connection) and sends that system's credentials. The proxy forwards only# to hosts that match these patterns.neubird_destinations: hosts: - splunk.example.com - yourinstance.service-now.com methods: [GET, HEAD, POST] # Splunk's MCP server uses POST # Splunk commands that write, send, delete or reach other systems request_deny_patterns: - "(?i)\\|\\s*(sendemail|sendalert|outputlookup|outputcsv|outputtext|collect|mcollect|meventcollect|tscollect|delete|script|run|runshellscript|map|rest|dbxoutput|dbxquery|sendresults)\\b"
redaction: # All built-in rules are on by default: emails, SSNs, phone numbers, card # numbers, IP addresses, dates of birth, and secrets such as JWTs and API # keys. Add your own identifier formats: custom: - name: employee_id regex: "\\bEMP[0-9]{6}\\b"hostslists the systems NeuBird may reach, as exact names or as a domain such as*.corp.example.com. Without it, NeuBird can reach any host name the pod can resolve. IP addresses are reached only when listed exactly. Loopback, link-local and cloud metadata addresses are never reached.methodsdefaults toGETandHEAD, which are read-only. Add more only if a system needs them, as Splunk’s MCP server does.request_deny_patternsare RE2 regular expressions. The proxy refuses a request whose query string or body matches one, whichever system the request is for.
2. Validate the config
Section titled “2. Validate the config”np validate -offline -tunnel -config config.yaml-offline checks the config without its secrets. -tunnel checks it the way the chart runs it. A valid config prints VALID, a summary and any warnings. Two warnings are expected, and every pod prints them in its log too. They say what NeuBird may do and how to cut it off:
warnings: - neubird_destinations: client_auth: none: requests from the NeuBird relay need no proxy token; cut NeuBird off by scaling to 0 or by NeuBird revoking the tunnel key - neubird_destinations: NeuBird chooses the destination host within splunk.example.com, yourinstance.service-now.com and supplies the credentialsIf the config is broken, the output lists every problem and the setting it’s in.
3. Preview what NeuBird receives
Section titled “3. Preview what NeuBird receives”You can check the masking before you deploy anything. Save a typical response from one of your systems as sample.json, then run:
np preview -config config.yaml sample.jsonThe output shows each changed line twice: what the system returned (-), then what NeuBird receives (+):
redactions: email 1, employee_id 1, phone_us 1 8 - "short_description": "Portal login fails for EMP220019", + "short_description": "Portal login fails for [REDACTED:EMPLOYEE_ID]", 9 - "description": "Caller Dana Whitfield (dana.whitfield@example.org, 646-555-0192) reports a login loop.", + "description": "Caller Dana Whitfield ([REDACTED:EMAIL], [REDACTED:PHONE_US]) reports a login loop.",For a security review, write a side-by-side HTML report:
np preview -config config.yaml -html - sample.json > report.htmlIn the example above, the name “Dana Whitfield” isn’t masked, because names and other free text have no pattern to match. To mask them, add custom rules for formats you know, or a response_fields allowlist under neubird_destinations. With an allowlist, every field you don’t list is masked whole.
Repeat until the output contains only what you’re comfortable sending to NeuBird.
Optional: keep masked values linkable (HMAC)
Section titled “Optional: keep masked values linkable (HMAC)”By default, every masked value becomes the same label, so every email is [REDACTED:EMAIL]. That also hides whether two events involve the same person or host, which often matters for finding a root cause.
HMAC masking keeps that link without revealing the value. Each value is replaced with a code derived from the value and a secret key that stays in your cluster. The same value always gets the same code, and different values get different codes:
redaction: mask: hmac hmac_key_env: REDACTION_HMAC_KEYTo preview with the real codes, put the key in an env file:
printf 'REDACTION_HMAC_KEY=%s\n' "$(np token)" > hmac.env # keep it safe; step 4 stores the keynp preview -config config.yaml -env-file hmac.env sample.jsonKnow the trade-offs before you choose HMAC:
- The key is as sensitive as the data. Anyone with the key and the codes can test guesses. For values with few possibilities, such as SSNs or phone numbers, that means they can recover the values by trying every possibility. Never send the key to NeuBird.
- It’s pseudonymization, not anonymization. Many privacy policies still treat HMAC-masked data as personal data. Check with your privacy team.
- Rotating the key changes every code, so codes from before and after a rotation don’t match.
4. Create the namespace and Secret
Section titled “4. Create the namespace and Secret”Create the namespace, then a Secret that holds the join token. Your systems’ credentials don’t go here; you enter them in NeuBird in step 7.
export CTX=<kube-context> NS=neubirdkubectl --context "$CTX" create namespace "$NS"kubectl --context "$CTX" label namespace "$NS" pod-security.kubernetes.io/enforce=restricted
printf 'NeuBird join token: '; read -rs JOIN; echokubectl --context "$CTX" -n "$NS" create secret generic neubird-proxy \ --from-literal=NEUBIRD_JOIN_TOKEN="$JOIN"unset JOINread -rs keeps the join token off the screen and out of your shell history.
If you chose HMAC masking, add the key to the Secret, then delete hmac.env:
kubectl --context "$CTX" -n "$NS" patch secret neubird-proxy --type merge \ -p "{\"stringData\":{\"REDACTION_HMAC_KEY\":\"$(sed -n 's/^REDACTION_HMAC_KEY=//p' hmac.env)\"}}"rm hmac.envWith mask: hmac and no key, the proxy refuses to start, so a missing key shows up immediately.
5. Install with Helm
Section titled “5. Install with Helm”Create values.yaml with the values NeuBird gave you:
image: repository: <your registry>/neubird-proxy/neubird-proxy digest: sha256:<digest>imagePullSecrets: - name: <pull-secret> # leave out for a public registrytunnel: relays: ["acme.tunnel.neubird.ai:443"] # your relay, from NeuBird tenant: acme # your tenant, from NeuBird proxy: aks-prod # the proxy name the join token is forenv: existingSecret: neubird-proxy # the Secret from step 4Your config.yaml becomes the chart’s config value. Wrap it, then install:
{ echo 'config:'; sed 's/^/ /' config.yaml; } > config-values.yaml
helm install neubird-proxy oci://ghcr.io/neubirdai/charts/neubird-proxy --version 1.0.0 \ --kube-context "$CTX" -n "$NS" \ -f values.yaml -f config-values.yaml \ --set-file relayCA.cert=relay-ca.crt \ --waitIf a system uses a certificate from an internal CA, add --set-file upstreamCA.cert=/path/to/ca-bundle.crt. If you use it, pass it on every later upgrade too, because an upgrade without it removes the CA.
The chart generates the proxy’s tunnel key and stores it in a Secret; the key never leaves the cluster. When the proxy first connects, it presents the join token, the relay records the key, and the tunnels open within seconds. You don’t need to send NeuBird anything. Check that it worked:
kubectl --context "$CTX" -n "$NS" rollout status deploy/neubird-proxykubectl --context "$CTX" -n "$NS" logs deploy/neubird-proxy \ | grep -E '"(starting|enrolled with the join token|tunnel connected)"'Once the proxy is enrolled, you can delete NEUBIRD_JOIN_TOKEN from the Secret.
-
If the log says
enrollment: relay refused: join token expired(oralready used), ask NeuBird for a new join token. -
If you don’t have a join token, send NeuBird the key’s fingerprint instead. The pods become ready once NeuBird records it:
Terminal window kubectl --context "$CTX" -n "$NS" exec deploy/neubird-proxy -- \/neubird-proxy fingerprint /etc/neubird-proxy/tunnel/tunnel.key
The starting log line shows the hash of the config the pod runs. Any risky configuration lines point to settings worth a second look.
6. Test the tunnel and each system
Section titled “6. Test the tunnel and each system”Run the test inside a proxy pod, so it uses the pod’s real network. With no arguments, it checks the tunnel to each relay:
kubectl --context "$CTX" -n "$NS" exec deploy/neubird-proxy -- \ /neubird-proxy test -config /etc/neubird-proxy/config.yamltunnel -> acme.tunnel.neubird.ai:443 ok identity tenant acme, proxy aks-prod; key sha256:0f9f… ok dns acme.tunnel.neubird.ai -> 20.1.2.3 ok relay acme.tunnel.neubird.ai:443: mutual TLS and neubird-tunnel/1 in 41msTo check that the proxy is allowed to reach a system and can reach it, pass the system’s URL:
kubectl --context "$CTX" -n "$NS" exec deploy/neubird-proxy -- \ /neubird-proxy test -config /etc/neubird-proxy/config.yaml \ https://splunk.example.com https://yourinstance.service-now.comhttps://splunk.example.com -> neubird_destinations ok hosts allowed by neubird_destinations.hosts ok dns splunk.example.com -> 10.20.30.40 ok tcp splunk.example.com:443 connected in 18ms ok tls TLS 1.3, certificate "splunk.example.com" from "Example CA", expires in 106 daysThe test doesn’t send a request, because the credentials are in NeuBird.
To change the config later, edit config.yaml, re-create config-values.yaml and run helm upgrade with the same arguments. A config change restarts the pods.
7. Connect NeuBird
Section titled “7. Connect NeuBird”The tunnels are already up. In NeuBird, add each system as a connection, as you would without the proxy: enter its URL (for example https://splunk.example.com:8089) and its credentials. Then choose access through the NeuBird Proxy. The relay is already set for your NeuBird deployment, and you don’t enter a proxy token.
NeuBird sends each request through the relay and the tunnel, naming the system’s host. The proxy forwards the request only if the host is in hosts. To add, change or remove a system later, update its connection in NeuBird. You only need to change the proxy when a new system’s host isn’t covered by hosts.
To cut NeuBird off at any time, scale the Deployment to 0, or ask NeuBird to revoke the tunnel key at the relay.
8. Watch it work
Section titled “8. Watch it work”The proxy writes one audit line per request. Each line shows that the request came through the tunnel ("via":"tunnel"), the system it went to (destination), the path, status and duration, and how many values each rule masked. Credentials, matched values and query values are never logged.
kubectl --context "$CTX" -n "$NS" logs -l app=neubird-proxy -fTroubleshooting
Section titled “Troubleshooting”| Symptom | Cause / fix |
|---|---|
ImagePullBackOff | The digest isn’t in your registry (for example, because you copied the image with docker push), or the pull secret is wrong. See Copy the image. |
join token expired / already used | Ask NeuBird for a new join token. |
FAIL relay | Outbound 443 to the relay is blocked, or TLS inspection is re-signing the connection. |
FAIL hosts | The host isn’t in neubird_destinations.hosts. |
FAIL dns | The name doesn’t resolve from inside the cluster. |
FAIL tcp | A firewall or NetworkPolicy blocks the system. |
FAIL tls, “set upstream_ca_file” | The system uses an internal CA. Pass its bundle with --set-file upstreamCA.cert=.... |
403 destination_not_allowed | The connection’s host isn’t in neubird_destinations.hosts. |
403 request_denied | The query or body matched request_deny_patterns. The reason includes the index of the pattern that matched. |
405 | The method isn’t in methods. |
502 redaction_blocked | The proxy couldn’t redact the response (binary, oversized or unsupported content), so it refused it. |
Next steps
Section titled “Next steps”- Keep
hostsnarrow. List the systems, or the narrowest domains that cover them, rather than*. - Lock down egress at the network. Set
networkPolicy.enabled: truewithrelayCIDRs(the relay IPs from NeuBird) andupstreams(your systems), so the pod can reach only those, whateverhostssays. - Tighten the request rules. The audit lines show every method, path and query parameter name. Add
request_deny_patternsfor anything NeuBird shouldn’t send, and remove methods no system needs.