Download the release bundle from Download Edge-Native Defender. New to Edge-Native Defender? Start with Edge-Native Defender overview.

Watch the install (3½ minutes): downloading the release, render and validate, the pieces merged into an Envoy configuration, Envoy restarted, allowed and blocked requests, and Envoy's own admin counters.

At a glance

Deployment architecture

Defender runs inside Envoy that you run yourself, configured with a bootstrap file, on hosts, VMs or containers. Running Envoy Gateway, Istio or kgateway? See Defender for Kubernetes Gateways.

Each request is decided on the Envoy worker thread that already holds it, from a policy set kept in that Envoy's memory. There is no extra service to size, no extra hop, and no network call on the request path. Defender scales with Envoy.

  BEFORE

    client ----> Envoy listener ----> router ----> your upstream


  AFTER

    client ----> Envoy listener ----> router ----> your upstream
                      |
              +----------------+
              |    Defender    |   (inside Envoy)
              |  Wasm filter   |
              +----------------+
                      |
                      +---> your Cequence tenant: policies in, analytics out,
                            in the background

What stays the same. Your listeners, routes, upstreams and other filters. You add Defender's filter to the listeners you want protected; listeners without it are not inspected. Removing the filter undoes it.

What Defender does with a request. A blocked request is answered by Envoy and never reaches your upstream. An allowed request is forwarded unchanged: Defender inspects a copy of each body, up to your tenant's capture settings, and never cuts short or changes what it forwards. When new policies arrive, Envoy builds them in small slices between requests and swaps them in whole, so a policy change does not pause traffic.

What is sent to Cequence. For each request: its headers and URL, the client address, the response status and headers, the decision if a policy acted, and the inspected body copies. Compressed bodies (gzip, deflate, brotli, zstd) are decoded for this copy only; your traffic is never decoded. Everything is masked inside Envoy with your tenant's Sensitive Data rules before it leaves, and nothing is sent until those rules have arrived. Your traffic filters decide whether a request is reported at all. Discovery sends counts of the hosts, methods and paths seen, with no request content.

All connections are outbound HTTPS from Envoy; nothing connects in. Envoy signs in at auth.<tenant>.cequence.cloud, checks edge.<tenant>.cequence.cloud for policy changes every 10 seconds, and sends analytics there in batches after your client already has its response. Envoy downloads the filter from downloads.cequence.ai at start, unless you use a local copy.

Installation

Prerequisites

• Envoy 1.33 or later, with WebAssembly support and the V8 runtime (envoy.wasm.runtime.v8). Each release is tested on Envoy 1.34. Some Envoy distributions ship without Wasm, so check your vendor's notes. You must be able to add a bootstrap extension to your Envoy configuration; settle that first if your configuration is generated for you.
• Your tenant name (for example acme.1, exactly as Cequence gave it), client ID and client secret. The client needs the scopes api:dataplane:traffic:write and api:dataplane:config:read.
• Outbound HTTPS (443) from each Envoy to auth.<tenant>.cequence.cloud, edge.<tenant>.cequence.cloud and, unless you use a local copy of the filter, downloads.cequence.ai. Certificates and host names are checked against the standard trust store at /etc/ssl/certs/ca-certificates.crt, which the official Envoy image and most Linux distributions have.
• A way to give Envoy the secret. The client secret is in none of the files Defender writes. Envoy reads it from its own environment as CEQUENCE_CLIENT_SECRET and hands it to Defender, so whatever starts Envoy (a systemd unit, docker run, your orchestrator's secret store) must set that variable.
• A free loopback port, 127.0.0.1:18101 by default, for Defender's check of request bodies. It is never reachable from outside the host.
• Docker, or your own Envoy binary, on the machine where you run defenderctl-envoy validate.

1. Fill in defender.conf

In the unpacked defender-for-envoy bundle, copy defender.conf.example to defender.conf and set:

CEQUENCE_TENANT=acme.1
CEQUENCE_CLIENT_ID=<client id>

That is all that is required. Optional Envoy settings:

2. Render and validate

./bin/defenderctl-envoy render
./bin/defenderctl-envoy validate

render writes five files to ./defender-envoy/ and prints where each one goes. None of them holds your client secret. validate checks them with Envoy itself, without your configuration and without the secret. Set ENVOY_BIN to your Envoy binary to check against the version you run; otherwise it uses Docker. With a local copy of the filter, add --wasm ./defender-envoy-<version>.wasm.

Want to see it work first? ./bin/defenderctl-envoy quickstart writes a trial Envoy in Docker with Defender in front of a public test upstream, and ./bin/defenderctl-envoy status shows that trial and Defender's status page.

3. Merge the files into your Envoy

Two things to get right:

• The client address. With the default x-envoy-external-address, that connection manager needs use_remote_address: true, plus xff_num_trusted_hops set to the number of proxies in front of Envoy.
• One render per Envoy. Each Envoy needs its own ENVOY_INSTANCE_ID, so render each one's files with its own value.

To protect part of your traffic, add the filter only to those listeners, or use a route or filter-chain match so only those requests reach a chain with it.

4. Restart Envoy

Envoy reads bootstrap extensions at startup, so restart it with the new configuration and with CEQUENCE_CLIENT_SECRET in its environment. For example, in a systemd unit, EnvironmentFile=/etc/defender/secret.env, a file readable by root alone holding CEQUENCE_CLIENT_SECRET=<client secret>; in Docker, export CEQUENCE_CLIENT_SECRET=<client secret> and then docker run -e CEQUENCE_CLIENT_SECRET ..., which passes it by name so it never appears on a command line. Without it Defender refuses to load and Envoy does not start. Run envoy --mode validate -c <your envoy.yaml> first if you like. At start, Envoy downloads the filter and logs that it is loading for a second or two; it serves traffic once the filter has loaded.

5. Check it before you go live

1. On a test Envoy, set CEQUENCE_DIAGNOSTICS=yes in defender.conf, render, merge and restart. Then request /__end/status through a protected listener: policies_loaded shows your tenant's policy count. The bundle's README.md lists every field to check, including that masking is active and analytics are being sent.
2. Send a request that one of your policies blocks, and check it is blocked. Send one that should pass, and check it passes. Envoy's own counters show both: on the admin interface, /stats?filter=downstream_rq_[24]xx lists each listener's 2xx and 4xx counts (blocks are 4xx, under the protected listener's stat_prefix), and wasm.defender stats appear once the filter has loaded.
3. Read your tenant's Sensitive Data rules against the fields that matter to you. A header is masked only when a rule names it, so check authorization and your session cookie.
4. Compare latency with and without Defender on a copy of your own traffic.
5. Set CEQUENCE_DIAGNOSTICS=no, render and restart again. While it is on, the status page and the x-end-echo header are readable by anyone who can reach the listener.
6. Roll out to a few Envoys first and compare them with the rest. The bundle's README.md also covers writing the configuration by hand.

Behind an outbound proxy

Defender running inside Envoy cannot reach Cequence through a proxy, and the installer refuses a proxy setting rather than produce a configuration that cannot connect. Where your network needs one, run Defender as a service beside Envoy instead (defender-extproc, called through Envoy's external processing filter), which can use an HTTP proxy, a proxy reached over TLS, or SOCKS5, with a username and password. Cequence support can help you set it up.

Upgrades and rollback

Each release has its own filter URL, and Envoy loads the filter at startup, so an upgrade is a render and a restart.

1. Set ENVOY_WASM_PATH in defender.conf to the URL in the new bundle's defender.conf.example. With a local copy, put the new .wasm beside the old one under a new name, such as /etc/defender/defender-<version>.wasm, and point ENVOY_WASM_PATH at it.
2. Run the new bundle's defenderctl-envoy render and validate, and merge the new files. render keeps every reference to the filter in step.
3. Restart one Envoy, check it as in "Check it before you go live", then roll through the rest.

To roll back, set ENVOY_WASM_PATH back to the previous release's URL (or file), render, and restart the same way.

During each restart, Envoy's own restart behaviour applies to your traffic; drain connections from an Envoy first if you normally do. Analytics not yet sent are lost on restart. After a restart Defender fetches your policies again and forwards requests until they arrive, a matter of seconds. Policy changes never need an upgrade: Defender picks them up while it runs. Changing a setting works the same way as an upgrade: edit defender.conf, render, restart.

Performance and sizing

Measured on a 4 vCPU host at 1,000 requests a second with two workers, a policy set of about 6,000 policies, analytics and masking on, and 1 KB responses. Cost scales with request rate; more policies, larger bodies or more Sensitive Data rules raise it, so measure with your own traffic before sizing.

When your tenant has dynamic fingerprint algorithms, computing them adds about 2 ms a request. Envoy also keeps a second copy of your policy set per worker for checking request bodies, and a bounded backlog of analytics while Cequence is slow or unreachable.

Cost

Cequence charges nothing for the infrastructure. Defender runs inside the Envoy you already run, with no extra service or host. Budget the extra CPU and memory under "Performance and sizing", and the outbound HTTPS traffic to your Cequence tenant, which is compressed.

Availability

• If Cequence is slow or unreachable, your traffic is unaffected. No request waits on Cequence: Defender keeps enforcing the policies it last received and keeps a bounded backlog of analytics, sent once Cequence is reachable again. A long outage can drop analytics beyond that backlog.
• If Defender itself cannot decide, the request goes through. A body check that does not answer within 0.5 seconds lets the request continue, and a Defender that has never loaded policies forwards everything. A configuration error stops Envoy at start, before it takes traffic, which validate catches first.
• If you need Defender off the path at once, remove its filters from the listener and restart Envoy; traffic then bypasses it entirely. To stop blocking without a restart, change your policies in your Cequence tenant to a non-blocking action: each Envoy picks the change up within about 10 seconds and keeps reporting.
• A fresh install blocks nothing until your tenant's first policy publish arrives.

Known limits

• block, add-header, rate-limit and challenge policies are enforced. redirect policies are reported but not applied: the request is forwarded. Block pages use your tenant's templates.
• Body policies check the first 16 KiB. A request with a body (not GET, HEAD or OPTIONS) waits until 16 KiB has arrived, or it ends, before its headers go upstream; the body is always passed on whole. A match after the first 16 KiB is not seen, and WebSocket, gRPC and event-stream requests are not checked on their body. Slow uploads are delayed by the wait. If such a request is blocked, your upstream has received its headers but not its body.
• Fingerprints of requests with a body use the header order Envoy passes on, not the client's, so learn fingerprint-keyed policies from traffic through Defender.
• Defender sees the request as Envoy has normalised it. For example, Envoy drops a Referer that is not a valid header value; Defender keeps a copy and restores it before the request goes upstream.
• The traffic-policy configuration is not fetched yet; Defender uses the client address with no allow-filters.
• Analytics not yet sent are lost if Envoy restarts, and a request that never receives a response is not reported.
• There is no secret-store integration: the client secret reaches Defender from Envoy's environment.
• Masking applies your tenant's Sensitive Data rules and nothing more.
• Kong Gateway does not run this filter; see Defender for Kong.

If something is wrong

The bundle's README.md has the full troubleshooting table. If you contact support, send the /__end/status output (it holds no credentials) and Envoy's startup log, never your client secret.

Removing it

1. Remove the contents of filter.yaml from each listener's http_filters and of connection-manager.yaml from its connection manager.
2. Remove what singleton.yaml, decision-listener.yaml and clusters.yaml added, and the filter file if you copied one to the host.
3. Restart Envoy.
4. Ask Cequence to disable the client credential, or rotate the secret.

Your listeners, routes and upstreams were never changed, so nothing else needs undoing.