The Traversal Connector runs inside a private network and exposes its internal
data sources to the Traversal control plane without opening any inbound
firewall holes. It holds outbound tunnels to the controller's host on port 443
(mutual TLS, ALPN x-traversal-tunnel). Traversal opens a pipe on a tunnel per
destination, carrying a signed capability for one host:port; the connector
checks it, applies its dial policy, and serves the pipe as an HTTP/2 or
HTTP/1.1 forward proxy inside TLS of its own, redacting responses from hosts
its rules cover.
┌────────────────────┐ outbound tunnels (mTLS) ┌────────────────────┐ HTTP(S) ┌──────────────────┐
│ Traversal control │ ◄───────────────────────► │ Traversal Connector│ ────────► │ upstream services│
│ plane │ pipes: TLS, then HTTP │ (this binary) │ │ (Prometheus, …) │
└────────────────────┘ └────────────────────┘ └──────────────────┘
The tunnel and pipe protocol is defined in
connector-lib/rawpipe.
Run after cloning:
./setup.shInstalls just and the Go-based CLI tools the recipes depend on.
ENV_NAME, TRAVERSAL_CONTROLLER_URL, and TRAVERSAL_CONNECTOR_ID are
required; everything else has sensible defaults (see Configuration below).
These have no defaults — startup fails if any is unset.
Docker Compose (containerized, hot-reload via air):
TRAVERSAL_CONTROLLER_URL=http://host.docker.internal:9080 docker compose up --buildNative (skip docker, fast iteration):
ENV_NAME=dev TRAVERSAL_CONNECTOR_ID=local-dev TRAVERSAL_CONTROLLER_URL=http://localhost:9080 go run ./cmd/connectorhttp:// is rejected when ENV_LEVEL=production. In development any
http:// host is accepted. Production deployments must use https:// and
configure mTLS, see Configuration below.
go build ./... # build all packages
go test ./... # run the test suite
go vet ./... # static checksFormatting follows gofmt plus
golines at a 100-column limit:
golines -w -m 100 .
go fmt ./...The protobuf definitions are managed with buf:
cd connector-lib && buf lint
cd connector-lib && buf format -wGenerated code lives under connector-lib/gen/ and is
checked in.
Build and load the production image for the current host platform with a
default tag of traversal-connector:prerelease-<short-sha>:
just prerelease-image-localAn explicit push publishes an unsigned, multi-platform test image to an existing Amazon ECR repository selected by the caller:
just prerelease-image-push --region <aws-region> \
--ecr-repository traversal-connectorThe AWS account is derived from the active credential chain. Use --profile to
select a configured profile; region resolution follows --region, AWS_REGION,
AWS_DEFAULT_REGION, then the AWS CLI configuration. The ECR repository must
already exist. The push refuses to replace an existing tag, so prerelease tags
are immutable by convention.
These images are not signed, are for testing only, and are not supported
releases. The command does not create Git tags, GitHub releases, Helm assets,
stable image tags, or latest. Use --tag prerelease-<name> to override the
default tag.
The command prints the immutable image reference after publishing. To test its tag with the existing chart, use the printed registry/repository as the image repository:
helm upgrade --install traversal-connector <chart> \
--set image.repository=<printed-registry/repository> \
--set image.tag=prerelease-<short-sha>For an internal test build from a pull request, apply the existing
build:prerelease label. The dedicated workflow runs only for same-repository
PRs carrying that exact label; fork PRs and ordinary unlabeled PRs never receive
AWS credentials or publish artifacts. A new PR commit cancels an older in-flight
run and builds the exact new head SHA.
The workflow publishes an unsigned, test-only multi-architecture image to the
internal ECR repository as prerelease-<12-character-head-sha>. It uploads a
paired Actions artifact named prerelease-pr-<number>-<short-sha> containing:
traversal-connector-charts-0.0.0-pr.<number>.<short-sha>.tgz- the chart's portable
.sha256file manifest.json, which binds the full source SHA and PR/run metadata to the image's immutablerepository@sha256:...reference and chart checksum
Actions retains the bundle for seven days. Consumers should pin the immutable
image reference from manifest.json, not reconstruct or rely on its tag. The
chart appVersion equals the image tag, while its SemVer prerelease version
also carries the PR number and commit. Rerunning the same commit fails clearly
if its immutable ECR tag already exists; a changed commit receives a new tag and
bundle. This path never writes Docker Hub, GitHub Releases, release Git tags, or
the canonical chart OCI registry.
Releases are only ever dispatched by a person; merging a PR releases nothing.
The version is given, not computed, and checked before anything is built: it
must be the next version of an existing line (the patch after the newest
vX.Y.*, or the first of the next minor or major), its tag must not exist, and
the commit must contain the release it follows. Only a release from main, for
the newest version, may be marked GitHub's Latest.
Validate first with a dry run, which builds and publishes nothing:
gh workflow run release.yml --ref main -f version=v0.10.1 -f dry_run=true \
-f description="$(cat notes.md)"The prepare job prints the plan (Releasing v0.10.1 from main at <sha> …).
Then run the same command without dry_run. A patch for an older line is
dispatched from its release/X.Y branch with -f latest=false. If a run is
cancelled or fails during publish, its cleanup job removes the draft release
and the tag it made; it never touches a published release.
Docker Hub is the canonical public image distribution. Before publishing each GitHub Release, the workflow also copies the validated OCI index and its existing signatures, attestations, and SBOMs to an internal Amazon ECR repository.
Each connector release publishes a matching Helm chart and portable SHA-256
checksum as GitHub Release assets. These assets are the canonical and preferred
installation source. The chart version omits the leading v; its appVersion
and the default connector image tag retain the complete release version.
VERSION=v0.8.5
CHART="traversal-connector-charts-${VERSION#v}.tgz"
DOWNLOAD_PATH="releases/download"
BASE="https://github.com/InteractionLabs/traversal-connector/${DOWNLOAD_PATH}/${VERSION}"
curl -fLO "${BASE}/${CHART}"
curl -fLO "${BASE}/${CHART}.sha256"
# Linux:
sha256sum --check "${CHART}.sha256"
# macOS alternative:
# shasum -a 256 --check "${CHART}.sha256"
helm upgrade --install traversal-connector "./${CHART}" \
--namespace traversal-connector \
--create-namespace \
-f customer-values.yamlFor temporary compatibility with existing OCI-based installations, new release
charts are also mirrored to Docker Hub. OCI versions do not include the leading
v:
CHART_VERSION=0.8.5
OCI_CHART="oci://registry-1.docker.io/traversalext/traversal-connector-charts"
# Pull the mirrored archive locally, or install it directly.
helm pull "$OCI_CHART" --version "$CHART_VERSION"
helm upgrade --install traversal-connector "$OCI_CHART" \
--version "$CHART_VERSION" \
--namespace traversal-connector \
--create-namespace \
-f customer-values.yamlimage.tag is empty in the canonical values and therefore falls back to the
chart's appVersion, keeping the chart and connector image on the same release.
An explicit image.tag override remains supported when a deployment needs to
pin another image.
The chart defaults to non-root containers, read-only root filesystems, no privilege escalation, no Linux capabilities, and runtime-default seccomp. See the chart security settings for container and pod overrides and writable-volume behavior.
Historical chart availability is intentionally incomplete: release assets are backfilled only where an authentic version-specific chart exists. Historical Docker Hub OCI coverage may differ from GitHub Release asset coverage; future normal releases are mirrored while this transitional compatibility path remains in place.
With Docker, kind, kubectl, Helm, curl, and OpenSSL installed, validate that a downloaded release chart installs and upgrades in a disposable kind cluster:
scripts/validate-chart-install.sh \
./traversal-connector-charts-0.8.5.tgz \
--image-ref docker.io/traversalext/traversal-connector:v0.8.5The validator checks /healthz rather than Kubernetes readiness. /readyz
requires an active tunnel to a real Traversal controller, which the disposable
cluster intentionally does not have. The cluster is always deleted on exit.
This validator is transitional: it will be replaced by the future deploy system's install-validation flow.
Released images are published as
docker.io/traversalext/traversal-connector. Verify the immutable digest, not a
mutable tag. Set DIGEST to the release digest (a sha256: value), then verify
the image with Cosign
and the public key checked into this repository:
DIGEST=sha256:<64-lowercase-hex-release-digest>
IMAGE="docker.io/traversalext/traversal-connector@${DIGEST}"
cosign verify --key cosign.pub "$IMAGE"BuildKit publishes a platform-specific SPDX SBOM and provenance alongside each release image. Choose the platform you will run, then inspect each attestation separately with Docker Buildx:
DIGEST=sha256:<64-lowercase-hex-release-digest>
IMAGE="docker.io/traversalext/traversal-connector@${DIGEST}"
PLATFORM=linux/amd64 # or linux/arm64
docker buildx imagetools inspect "$IMAGE" --format '{{ json .SBOM }}' \
| jq --arg platform "$PLATFORM" '.[$platform]'
docker buildx imagetools inspect "$IMAGE" --format '{{ json .Provenance }}' \
| jq --arg platform "$PLATFORM" '.[$platform]'| Variable | Default | Description |
|---|---|---|
ENV_NAME |
required | Free-form environment name attached to telemetry as service.namespace and deployment.environment (e.g. staging, production). Startup fails if unset. |
ENV_LEVEL |
development |
Deployment level (production or development). The container image bakes in production; leave unset for local dev. |
HTTP_PORT |
8080 |
Port for the local HTTP server (/healthz, /readyz). |
TRAVERSAL_MEMORY_LIMIT_BYTES |
(none) | The container's memory limit in bytes; the Helm chart sets it from resources.limits.memory through the downward API. The connector sets Go's soft memory limit to 90% of it, so it collects garbage harder before the kernel kills it. Unset, or with GOMEMLIMIT set, Go's default applies. |
ENV_FILE |
(none) | Optional path to a dotenv file (e.g. /mnt/secrets/connector.env). Useful when secrets are mounted as a file (e.g. Vault Agent). Process-environment values win over file values; the file only fills in values that are unset. Startup fails if the path is set but unreadable. |
| Variable | Default | Description |
|---|---|---|
TRAVERSAL_CONTROLLER_URL |
required | URL of the Traversal control plane; tunnels go to its host on port 443. https:// requires mTLS (see below). http:// is rejected when ENV_LEVEL=production. Startup fails if unset or if the scheme/level combination is rejected. |
TRAVERSAL_CONTROLLER_CONNECT_TO |
(none) | Optional curl --connect-to-style host:port override for the controller, for example edge-istio.traversal-gateways.svc.cluster.local:443. Only the TCP connection destination changes; the logical controller URL still supplies the scheme, path, HTTP/2 :authority, TLS SNI, and certificate verification identity. It also routes tunnels unless TRAVERSAL_TUNNELS_CONNECT_TO is set. Cannot be combined with EGRESS_PROXY_URL. |
REQUEST_TIMEOUT |
60s |
How long a destination may take to send its response headers, and how long a response from a host your redaction rules cover may take to end; one that takes longer is a stream, which cannot be redacted, and is refused. Other response bodies stream for as long as they run. 0 or less is the default. |
MAX_REQUEST_BODY_SIZE_MB |
32 |
Maximum size of a request body sent to a destination. Bodies stream, so a larger one is cut off with an error once it passes the limit. |
MAX_RESPONSE_BODY_SIZE_MB |
32 |
Maximum size read off the wire from a response from a host your redaction rules cover, which is buffered to be redacted. A larger response is refused. Other responses stream and have no limit. |
MAX_DECODED_RESPONSE_BODY_SIZE_MB |
256 |
Maximum size a compressed response may expand to when the connector decodes it to redact. A stream that expands past this is dropped rather than decoded further. |
TRAVERSAL_REDACTION_MAX_CONCURRENT |
8 |
How many responses from hosts your redaction rules cover the whole connector buffers and redacts at once; each may hold MAX_RESPONSE_BODY_SIZE_MB plus MAX_DECODED_RESPONSE_BODY_SIZE_MB in memory. A response waits for a slot for what is left of REQUEST_TIMEOUT, then is refused as capacity, counted in connector.response_refusals_total. From 1 to 1024; any other value stops the connector starting. |
TRAVERSAL_UNCOVERED_STREAM_MAX_LIFETIME |
15m |
While any redaction rules exist, how long a long-lived response from a host no rule covers may run: an event stream (text/event-stream), a gRPC response, or an upgraded connection (WebSocket). Coverage is decided when a request is sent, so a rule added later for the host, by OTA or a reload, reaches such a stream only once it ends. At the cap the stream ends cleanly (an event stream's body ends, gRPC gets UNAVAILABLE trailers, a WebSocket closes) and its client reopens it under the rules then current. Ordinary responses, and every response while no rules exist, are not capped. 0s turns the cap off; an invalid value stops the connector starting. |
TRAVERSAL_CONNECTOR_ID |
required | This connector's ID, a lower-case UUID provided by Traversal. It names the connector's tunnels. Any certificate issued to the connector's organization works, whichever connector or processor it was issued for. Startup fails if unset. |
EGRESS_PROXY_URL |
(none) | An http:// forward proxy the connector reaches Traversal through, as in 0.9.x: tunnels open with CONNECT <controller host>:443 (credentials in the URL become Proxy-Authorization), and TLS, the tunnel ALPN and certificate checks run end to end inside it, so the proxy must not intercept TLS. The OTA config client and telemetry use it too. Cannot be combined with TRAVERSAL_CONTROLLER_CONNECT_TO or TRAVERSAL_TUNNELS_CONNECT_TO. It is unrelated to TRAVERSAL_PIPES_EGRESS_PROXY, the proxy for destinations. |
mTLS is required whenever TRAVERSAL_CONTROLLER_URL is https://....
The connector refuses to start if TLS_CERT_BASE64 and TLS_KEY_BASE64 are
not both provided, or if either fails to parse as valid PEM. mTLS is the only
supported posture for production traffic; there is no "TLS without mTLS"
mode.
All certificate variables accept either raw PEM (starting with
-----BEGIN) or base64-encoded PEM.
| Variable | Default | Description |
|---|---|---|
TLS_CERT_BASE64 |
required for https:// |
Client TLS certificate. Must be paired with TLS_KEY_BASE64. |
TLS_KEY_BASE64 |
required for https:// |
Client TLS private key. Must match the public key in TLS_CERT_BASE64. |
TLS_CA_BASE64 |
(none) | Additional CA certificate used to validate the control plane's server certificate. When set, it extends the system CA bundle. Leave unset for public CAs (e.g. Let's Encrypt). |
The connector verifies upstream TLS certificates by default. Tune via:
| Variable | Default | Description |
|---|---|---|
UPSTREAM_TLS_VERIFY |
true |
Verify TLS certificates when calling upstream HTTPS services. Set to false to accept self-signed. |
UPSTREAM_TLS_CA_BASE64 |
(none) | CA certificate (raw PEM or base64-encoded) for validating upstream certificates. When set, this CA is added to the connector container's system trust store. The connector does not inherit trust from the Kubernetes node. |
UPSTREAM_TLS_CA_FILE |
(none) | Path to a PEM CA certificate file (e.g. a mounted Secret or ConfigMap), used the same way as UPSTREAM_TLS_CA_BASE64. Mutually exclusive with UPSTREAM_TLS_CA_BASE64: setting both fails at startup. |
Examples:
# Default — verify against the system CA bundle.
UPSTREAM_TLS_VERIFY=true
# Accept self-signed (no verification).
UPSTREAM_TLS_VERIFY=false
# Add an internal CA alongside the container's system CAs.
UPSTREAM_TLS_VERIFY=true
UPSTREAM_TLS_CA_BASE64="LS0tLS1CRUdJTi..."
# Or read the internal CA from a mounted file instead (not both).
UPSTREAM_TLS_VERIFY=true
UPSTREAM_TLS_CA_FILE=/etc/traversal/upstream-ca/ca.crtEvery request reaches its destination through the connector's dial policy, which refuses loopback, link-local, cloud metadata and the connector's own addresses, and any CIDR you add. Private ranges are allowed.
| Variable | Default | Description |
|---|---|---|
TRAVERSAL_CAPABILITY_ROOTS |
(none) | Traversal's capability root certificates (PEM, raw or base64). Required unless TRAVERSAL_CAPABILITY_KEYS is set. |
TRAVERSAL_CAPABILITY_KEYS / TRAVERSAL_CAPABILITY_ISSUER |
(none) | Pinned capability keys and their issuer, beside or instead of roots. |
TRAVERSAL_TUNNELS_COUNT |
2 |
Tunnels held, at most 8. |
TRAVERSAL_TUNNELS_CONNECT_TO |
TRAVERSAL_CONTROLLER_CONNECT_TO |
host:port to dial instead of the controller host on 443; SNI and certificate checks are unchanged. Unset, tunnels follow TRAVERSAL_CONTROLLER_CONNECT_TO, or with neither set go to the controller host on 443. |
TRAVERSAL_PIPES_MAX |
200 |
Pipes open at once. |
TRAVERSAL_PIPES_MAX_LIFETIME |
4h |
A pipe this old is closed; the proxy opens another. |
TRAVERSAL_PIPES_IDLE_TIMEOUT |
15m |
A pipe that carries no request for this long is closed. |
TRAVERSAL_PIPES_MAX_STREAMS |
100 |
Concurrent requests in one HTTP/2 pipe. |
TRAVERSAL_PIPES_STREAM_WINDOW_KB / TRAVERSAL_PIPES_CONNECTION_WINDOW_KB |
256 / 1024 |
HTTP/2 flow-control windows per request and per pipe. |
TRAVERSAL_PIPES_EGRESS_PROXY |
(none) | http:// forward proxy every request reaches its destination through (CONNECT). |
TRAVERSAL_PIPES_EGRESS_PROXY_RESOLVES |
false (true for HTTPS_PROXY/HTTP_PROXY) |
Send hostnames to that proxy, which resolves them; off, only IP literals go through it. Turn on only if the proxy refuses loopback, link-local and metadata addresses. |
TRAVERSAL_PIPES_FORBIDDEN_CIDRS |
(none) | Comma-separated CIDRs never to reach, beside the built-in list. |
TRAVERSAL_PIPES_EGRESS_PROXY is the documented setting. For backwards
compatibility with #67, when it is unset HTTPS_PROXY (or else HTTP_PROXY)
is used the same way, and NO_PROXY hosts are dialed directly; the dial policy
applies either way. As in #67, that proxy resolves hostnames unless
TRAVERSAL_PIPES_EGRESS_PROXY_RESOLVES is set. When both are set, TRAVERSAL_PIPES_EGRESS_PROXY wins
and the connector logs that the environment proxy is ignored.
Whenever the proxy resolves hostnames, the connector warns once at start, as
its address floor then covers only IP literals. Each dial handed to the proxy
is counted in connector.egress_proxy_unresolved_dial_total, by target_kind:
hostname (resolved by the proxy, not checked by the connector) or ip. A
dial the dial policy refuses never reaches the proxy and is not counted.
Choose either a local TOML rules file or S3-backed remote (OTA) configuration.
The two sources are mutually exclusive: setting REDACTION_RULES_FILE together
with TRAVERSAL_CONFIG_ENABLED=true fails startup. Helm also rejects combining
local redaction sources with configUpdates.enabled: true.
If neither source is enabled, the connector runs without redaction.
There is no automatic fallback between sources.
Set REDACTION_RULES_FILE to a readable file inside the connector container.
Leave TRAVERSAL_CONFIG_ENABLED unset or false; no remote config is fetched.
| Variable | Default | Description |
|---|---|---|
REDACTION_RULES_FILE |
(none) | Path to the local TOML rules file. Startup fails if the file cannot be read, parsed, or compiled. |
REDACTION_RELOAD_INTERVAL |
10s |
Positive duration between local-file checks. Used only when a local file is configured. |
Local files use top-level default_replacement and [[rules]] tables:
version = "1"
default_replacement = "[REDACTED]"
[[rules]]
name = "ssn"
type = "regex"
pattern = '\b\d{3}-\d{2}-(\d{4})\b'
replacement = "***-**-$1"
hosts = ['.*']
[[rules]]
name = "email"
type = "regex-structured-data"
pattern = '[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}'
redact_fields = ["body|message"]
hosts = ['api\.example\.com']The optional version string is metadata. Unknown TOML fields are ignored.
OTA documents without top-level local rules are rejected. Every rule must set
type to regex or regex-structured-data; unsupported or omitted types reject
the entire ruleset, retaining any last-known-good rules. Field filters on regex
rules are still ignored with a warning.
The initial rules load completes before any tunnels open. Changed file contents
are compiled and applied atomically; unchanged content is not recompiled.
Reload errors retain the last-known-good rules. After three consecutive reload
failures, the connector exits; a successful read resets the failure count.
To disable redaction without changing the selected source, replace the file
with rules = [].
In Helm, set redaction.enabled: true and exactly one of
redaction.rulesContent, redaction.existingConfigMap, or
redaction.existingSecret. ConfigMaps and Secrets must contain the key
redaction-rules.toml. The legacy redactionRules inline string also enables
local redaction and cannot be combined with another source.
See the chart examples.
Enable OTA redaction using TRAVERSAL_CONFIG_ENABLED=true
(configUpdates.enabled: true in Helm). The URL is derived from the validated
controller's scheme, hostname and port, with the absolute path
/v1/config/<connector-id>. Controller path prefixes, credentials, queries and
fragments are not copied. There is no endpoint override or new network destination.
When OTA is enabled, the connector ID must be a canonical lowercase UUID,
matching the published object key.
The config HTTP client reuses controller mTLS, additional trust roots,
EGRESS_PROXY_URL and TRAVERSAL_CONTROLLER_CONNECT_TO; ambient proxy variables
are not used and redirects are refused.
| Variable | Default | Description |
|---|---|---|
TRAVERSAL_CONFIG_ENABLED |
false |
Enable OTA polling and require a valid config document before startup. |
TRAVERSAL_CONFIG_REFRESH_INTERVAL |
30s |
Poll interval, with up to 10% jitter; positive and at most 24h. |
When OTA is enabled, startup requires a valid config document before opening any tunnels. Any initial fetch failure (including 404, 403, 5xx, network errors, or invalid TOML/regexes) fails startup. Runtime errors or deletion retain the last-known-good rules in memory and emit warnings; there is no persistent local cache. After a restart, a missing or invalid config blocks startup again. ETags avoid downloading unchanged configs; unchanged bodies do not recompile rules. Responses are limited to 1 MiB and requests time out after 15 seconds. To intentionally run without redaction while retaining OTA polling, publish a valid empty-rules document; do not delete the object:
schema_version = 1
[redaction]
rules = []If OTA configuration is not needed, leave TRAVERSAL_CONFIG_ENABLED=false
(the default); no remote config fetch is performed. Local-file redaction can
still be enabled independently.
Publish through ingestion-configs at
connector/<env>/<certificate-org-id>/<connector-id>.toml; the gateway proxies
connector/<certificate-org-id>/<connector-id>.toml from S3. Publish the document
before enabling OTA. Rules added to an initially empty document are picked up
by polling.
schema_version = 1
[redaction]
default_replacement = "[REDACTED]"
[[redaction.rules]]
name = "ssn"
type = "regex"
pattern = '\b\d{3}-\d{2}-(\d{4})\b'
replacement = "***-**-$1"
hosts = ['.*']
[[redaction.rules]]
name = "email"
type = "regex-structured-data"
pattern = '[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}'
redact_fields = ["body|message"]
hosts = ['api\.example\.com']Validate a document locally with go run ./cmd/validate-config < config.toml.
This uses the same parser and compiler as the running connector, including every
hosts expression even when the list also contains .*. CI/publication must
pin this validator to a reviewed connector revision. Invalid regexes (including
lookbehind) are rejected without printing rule contents.
Only schema version 1 is supported. Unknown keys, unsupported rule types,
missing redaction.rules, empty patterns and duplicate/empty names are rejected.
Rule field filters are only accepted for regex-structured-data. Metric
connector.config_refresh_total records bounded outcomes (applied, unchanged,
error); missing configs count as errors. connector.config_rule_count and
connector.config_staleness_seconds expose active rules and time since the last
successful fetch. Applied ETags are logged, not used as metric labels.
To switch from local files to OTA, replace the local version header with
integer schema_version = 1, move default_replacement under [redaction],
and rename [[rules]] tables to [[redaction.rules]]. Publish the document,
then remove the local settings and enable OTA in the same deployment update.
To switch to local files, reverse this document conversion, mount the file,
and disable OTA when enabling the local source. Source selection changes
require restarting the connector; rule updates within a source are polled.
Each rule requires:
name— human-readable label used in log output.type—"regex"for byte-level redaction over the full response body, or"regex-structured-data"for per-field redaction over JSON response bodies. Unsupported types reject the entire remote update.pattern— a RE2 regular expression.replacement(optional) — replacement string; use$1,$2, … to insert numbered capture groups from the pattern. Falls back todefault_replacement.hosts— allowlist of RE2 patterns matched against the request hostname (port and userinfo stripped). The rule only fires when the hostname fully matches at least one pattern. A rule with nohosts, orhosts = [], covers every host, as in v0.9: the connector then buffers and redacts every response it carries, and logs a warning at load naming the rule by its position. Writehosts = [".*"]to cover every host on purpose. Each pattern is anchored to the whole hostname, so.*github\.commatchesapi.github.comandgithub.combut notgithub.com.evil.com. Applies to both rule types. Listing.*anywhere in the list makes the rule match every host.
Matching follows DNS rather than byte equality, so one upstream cannot be reached under a spelling that carries a different rule set. Patterns are matched case-insensitively (api\.github\.com and API\.GITHUB\.COM both match API.github.com), and a single trailing dot on the requested hostname is ignored, since it only marks the name as already absolute (github.com. matches github\.com).
Because that dot is removed before matching, the hostname a pattern is compared against never ends in one. Write the pattern without a trailing dot — github\.com, not github\.com\. — since a pattern in the absolute form matches nothing. The pattern text is used exactly as written and is never rewritten, because RE2 can spell a trailing dot several ways and trimming one out would corrupt some patterns rather than fix them.
Case-insensitivity uses Unicode case folding, so it applies to non-ASCII hostnames too.
A non-ASCII hostname is converted to its IDNA ASCII (punycode) form before matching, because that is the form the connection itself uses. Write the pattern in that ASCII form, xn--bcher-kva\.example rather than bücher\.example, since a pattern in the Unicode form matches nothing. Both spellings of one name then select the same rules: a request to bücher.example and a request to xn--bcher-kva.example are the same host. As with the trailing dot, the pattern text is never converted in turn, because it is a regex and rewriting it could change what it matches. A hostname that is already ASCII is matched as it arrived and is not validated, so a name the conversion would reject, such as one carrying an underscore, still matches a pattern written for it.
regex-structured-data rules additionally accept:
redact_fields— allowlist of pipe-delimited paths. When set, the rule only fires inside the matching subtrees.skip_fields— blocklist of pipe-delimited paths. When set, the rule never fires inside the matching subtrees.
Field names use pipe-delimited notation for nested objects: body|message matches the body.message field. Both filters may be set on the same rule; skip_fields wins on overlap.
Scope is prefix-based on the path. An entry body in redact_fields matches body itself plus everything underneath it (body|message, body|x|y|z, every array element under any of those). Once the walk enters an in-scope node, every primary leaf reachable from it is redacted — including map keys, map values, and array elements. Numbers are matched against their JSON textual form, so a credit-card or phone-number pattern catches values whether the upstream serialized them as strings or as JSON numbers; when a number actually matches, the field is rewritten as a string in the output (since the redacted text is no longer a valid number). Numbers that don't match are preserved as numbers, and booleans and null always pass through unchanged. The addressing key that brought you into the subtree lives at the parent scope, so e.g. with redact_fields = ["data"] the literal key "data" is not redacted, but every nested key inside it is.
How the two rule types are applied:
regexrules always run byte-level over the full response body, regardless ofContent-Typeor whether the body parses as JSON. They have no concept of fields, soredact_fields/skip_fieldsdon't apply.regex-structured-datarules fire per-field, honoringredact_fields/skip_fields, and require a JSONContent-Type. On any other content type they are skipped entirely (their field filters can't be honored on raw bytes, so applying them globally would cross the boundaries the filters were configured to enforce).
When a per-field rule is in scope and the response declares a JSON Content-Type, the body has to be exactly one complete JSON document, since that is the only way the configured fields can be located. A body that does not parse, or that carries anything beyond its first complete value, is dropped: the requester receives an error and connector.response_refusals_total records the reason malformed_json. Trailing content counts because parsing stops at the end of the first document, so forwarding such a body would silently shorten it to that first value.
A host no per-field rule covers is unaffected. With only regex rules in scope nothing needs parsing, so an unparseable body is still forwarded with byte-level redaction applied.
If you need a pattern to redact everywhere unconditionally, use regex. If you need per-field control, use regex-structured-data and ensure the upstream answers with one complete JSON document under a JSON Content-Type.
Rules are applied in order; each rule operates on the output of the previous one.
Redaction patterns run against the plaintext of a response, so the connector has to reach it. Request headers pass through untouched, which means an upstream may answer in whatever coding the original caller negotiated, and the connector handles the response by what actually came back:
Response Content-Encoding |
Behavior when a rule targets the host |
|---|---|
absent, or identity |
Redacted in place. |
gzip |
Decoded, redacted, and re-encoded as gzip. |
| anything else | Dropped. The response never reaches the requester. |
Anything else covers deflate, zstd, br, a stacked value such as
gzip, br, and a gzip stream that is corrupt, truncated, or expands past
MAX_DECODED_RESPONSE_BODY_SIZE_MB. Forwarding a body the connector cannot scan
would ship the very content the rules exist to remove, so there is no degraded
mode: the requester receives an UNSUPPORTED_ENCODING error, and
connector.response_refusals_total carries the reason. A 206 Partial Content
is dropped for the same reason, because a pattern straddling the boundary
between two ranges is invisible to both.
Hosts no rule targets are unaffected: their responses are forwarded byte for byte, in whatever coding they arrived, with nothing decoded or re-encoded.
On every response, whether rules target its host or not, the connector drops
any X-Traversal-* header the destination sent. Those headers are the
connector's and Traversal's own (X-Traversal-Redacted, X-Traversal-Reason),
and Traversal cannot tell a forged one from the connector's.
Two response headers change when the connector rewrites a body. It sets
X-Traversal-Redacted: true, and it strips the headers that fingerprint the
original bytes (ETag, Last-Modified, Content-MD5, and the Digest family)
so a client cannot validate a redacted body against them. On hosts with rules it
also stops advertising Accept-Ranges, since a range request would be refused.
Regardless of rules, connector.response_content_encoding_total reports the
coding of every upstream response, so a deployment can see which of its
upstreams would be affected before configuring anything.
The connector emits OpenTelemetry traces, metrics, and logs. Telemetry is the
only view Traversal has into a connector running inside a customer network, so
exporting all three signals is required. Outside ENV_LEVEL=development,
the connector refuses to start without it.
| Variable | Default | Description |
|---|---|---|
OTEL_SERVICE_NAME |
traversal-connector |
Service name reported on all signals. |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT |
(required) | OTLP endpoint for metrics. Must be an https:// URL. |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |
(required) | OTLP endpoint for traces. Must be an https:// URL. |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT |
(required) | OTLP endpoint for logs. Must be an https:// URL. Logs also always go to stdout. |
OTEL_EXPORTER_OTLP_PROTOCOL |
(empty) | grpc or http/protobuf selects gRPC; http/json (or empty) selects HTTP. |
OTEL_EXPORTER_OTLP_CONNECT_TO |
(none) | Optional curl --connect-to-style host:port override shared by metrics, traces, and logs. Only the TCP connection destination changes; logical endpoint scheme and path, HTTP Host/gRPC :authority, TLS SNI, and certificate verification remain unchanged. All three endpoints must be reachable through the one socket. Cannot be combined with EGRESS_PROXY_URL; it is cleared when telemetry is disabled. |
TRAVERSAL_DISABLE_TELEMETRY |
false |
Opts out of all telemetry export. Strongly discouraged. Traversal cannot diagnose or assist with issues in a deployment that reports nothing. |
Point all three endpoints either at a collector you operate or at the ingest
endpoints supplied with your deployment. Their shape follows the protocol: grpc
takes a host and port and names the signal in the request
(https://collector.example.com:4317), while http/* names it in the path
(https://collector.example.com/v1/metrics). The deployment chart fills these in;
a deployment that sets the environment directly has to provide them.
Connect-to overrides mirror curl --connect-to and support enterprise routing such as PrivateLink, split
DNS, service-mesh gateways, Kubernetes Services, and tunnels without weakening
TLS identity. For example, retain https://telemetry.traversal.com:4317 as the
logical endpoint while connecting to
telemetry-istio.traversal-gateways.svc.cluster.local:443. With direct export,
the connector receives OTEL_EXPORTER_OTLP_CONNECT_TO. With the chart's
sidecar enabled, the connector continues exporting to loopback; the override is
applied only to Alloy's remote endpoint while Alloy preserves the logical gRPC
authority and TLS server name. Custom CA material remains additive to system
roots in both modes.
Startup rejects a telemetry configuration that would export nothing or export in cleartext:
- All three endpoints must be set. A partially configured exporter looks healthy from the outside while leaving a gap nobody finds until an incident.
- Each must be an
https://URL naming a host. A scheme-lesshost:portis rejected withhttp://, because the exporters read the scheme to decide whether to negotiate TLS at all. http://is accepted only on loopback: anything in127.0.0.0/8,localhost,[::1], or the IPv4-mapped form. A telemetry forwarder colocated with the connector receives it. That hop never leaves the pod's network namespace. The forwarder holds the mTLS identity for the egress that does.
Two exemptions: ENV_LEVEL=development, and TRAVERSAL_DISABLE_TELEMETRY=true,
which drops any endpoints that were configured anyway so the opt-out is absolute.
Note what the first exemption means in practice. ENV_LEVEL defaults to
development, and only the published container image sets it to production
(see the Dockerfile), so a connector built from source or repackaged into a
custom image gets no telemetry enforcement at all until ENV_LEVEL says
otherwise. This mirrors the exemption that allows an http://
TRAVERSAL_CONTROLLER_URL in development.
The connector also reads the OTel-standard
OTEL_RESOURCE_ATTRIBUTES
env var and merges those attributes into the resource — useful for attaching
compliance IDs, team names, or any other site-specific metadata.
| Port | Description |
|---|---|
8080 (container) |
HTTP /healthz and /readyz endpoints. The compose file maps host 8081 → container 8080. |
Licensed under the Apache License, Version 2.0.