Skip to content

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 responses

Setup takes about an hour. These steps use Splunk and ServiceNow as example systems; replace them with your own.

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.
  • 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:

Terminal window
IMAGE=<your registry>/neubird-proxy/neubird-proxy@sha256:<digest>
np() { docker run --rm -i -v "$PWD":/work -w /work "$IMAGE" "$@"; }
np help

Run the commands from a directory under your home directory, because Docker Desktop and Colima share only that directory with containers.

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"
  • hosts lists 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.
  • methods defaults to GET and HEAD, which are read-only. Add more only if a system needs them, as Splunk’s MCP server does.
  • request_deny_patterns are RE2 regular expressions. The proxy refuses a request whose query string or body matches one, whichever system the request is for.
Terminal window
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 credentials

If the config is broken, the output lists every problem and the setting it’s in.

You can check the masking before you deploy anything. Save a typical response from one of your systems as sample.json, then run:

Terminal window
np preview -config config.yaml sample.json

The 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:

Terminal window
np preview -config config.yaml -html - sample.json > report.html

In 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_KEY

To preview with the real codes, put the key in an env file:

Terminal window
printf 'REDACTION_HMAC_KEY=%s\n' "$(np token)" > hmac.env # keep it safe; step 4 stores the key
np preview -config config.yaml -env-file hmac.env sample.json

Know 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.

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.

Terminal window
export CTX=<kube-context> NS=neubird
kubectl --context "$CTX" create namespace "$NS"
kubectl --context "$CTX" label namespace "$NS" pod-security.kubernetes.io/enforce=restricted
printf 'NeuBird join token: '; read -rs JOIN; echo
kubectl --context "$CTX" -n "$NS" create secret generic neubird-proxy \
--from-literal=NEUBIRD_JOIN_TOKEN="$JOIN"
unset JOIN

read -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:

Terminal window
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.env

With mask: hmac and no key, the proxy refuses to start, so a missing key shows up immediately.

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 registry
tunnel:
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 for
env:
existingSecret: neubird-proxy # the Secret from step 4

Your config.yaml becomes the chart’s config value. Wrap it, then install:

Terminal window
{ 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 \
--wait

If 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:

Terminal window
kubectl --context "$CTX" -n "$NS" rollout status deploy/neubird-proxy
kubectl --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 (or already 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.

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:

Terminal window
kubectl --context "$CTX" -n "$NS" exec deploy/neubird-proxy -- \
/neubird-proxy test -config /etc/neubird-proxy/config.yaml
tunnel -> 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 41ms

To check that the proxy is allowed to reach a system and can reach it, pass the system’s URL:

Terminal window
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.com
https://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 days

The 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.

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.

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.

Terminal window
kubectl --context "$CTX" -n "$NS" logs -l app=neubird-proxy -f
SymptomCause / fix
ImagePullBackOffThe 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 usedAsk NeuBird for a new join token.
FAIL relayOutbound 443 to the relay is blocked, or TLS inspection is re-signing the connection.
FAIL hostsThe host isn’t in neubird_destinations.hosts.
FAIL dnsThe name doesn’t resolve from inside the cluster.
FAIL tcpA 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_allowedThe connection’s host isn’t in neubird_destinations.hosts.
403 request_deniedThe query or body matched request_deny_patterns. The reason includes the index of the pattern that matched.
405The method isn’t in methods.
502 redaction_blockedThe proxy couldn’t redact the response (binary, oversized or unsupported content), so it refused it.
  • Keep hosts narrow. List the systems, or the narrowest domains that cover them, rather than *.
  • Lock down egress at the network. Set networkPolicy.enabled: true with relayCIDRs (the relay IPs from NeuBird) and upstreams (your systems), so the pod can reach only those, whatever hosts says.
  • Tighten the request rules. The audit lines show every method, path and query parameter name. Add request_deny_patterns for anything NeuBird shouldn’t send, and remove methods no system needs.