This is a preview release. Do not use it in production environments.

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

Watch the install (3 minutes): downloading the release, starting Defender beside Omni Gateway, adding the External Processing policy in API Manager, allowed and blocked requests, the blocks in the API's Key Metrics, and removing the policy.

At a glance

Deployment architecture

Defender protects APIs on MuleSoft Omni Gateway (formerly Flex Gateway) through the gateway's own External Processing policy, included with Omni Gateway 1.6.0 and later. The policy calls the Defender service, which runs next to your gateway as a container named defender-extproc, and Defender decides each request before it reaches your API.

  BEFORE

    client ---> Omni Gateway ----------------------------> your API's upstream


  AFTER

    client ---> Omni Gateway ----------------------------> your API's upstream
                     |
                     | External Processing policy (each request and response)
                     v
              Defender service  (beside the gateway)
                     |
                     +---> your Cequence tenant: policies in, analytics out,
                           in the background

What stays the same. Your APIs keep their hostnames, base paths, upstreams and other policies. You apply Defender once, as an automated policy for every API in an environment, or on the APIs you choose, and remove the policy to undo it.

What Defender does with a request. A blocked request is answered by the gateway and never reaches your upstream. An allowed request is forwarded byte for byte, and your client receives the response byte for byte: Defender inspects a copy of each body, up to your tenant's capture settings, and never changes what it forwards.

What is sent to Cequence. For each request: its headers and URL, the response status and headers, and the inspected body copies, masked first with your tenant's Sensitive Data rules. Your traffic filters decide whether a request is reported at all.

Installation

Prerequisites

• Omni Gateway 1.6.0 or later, self-managed, in connected mode (managed from API Manager) or local mode (configured from files). For a Managed Omni Gateway on CloudHub 2.0, see "On CloudHub 2.0" below.
• A place to run the Defender service next to the gateway: on the same Docker network, in the same Kubernetes cluster, or on the same host.
• Access to the defender-extproc image for your release, from Cequence support.
• Outbound HTTPS from the Defender service to your Cequence tenant.
• Your tenant's name, client ID and client secret.

1. Run the Defender service

In the unpacked defender-for-mulesoft bundle, fill in mulesoft/defender.json. For a tenant named acme.1:

"edge_url": "https://edge.acme.1.cequence.cloud",
"auth_url": "https://auth.acme.1.cequence.cloud/auth/realms/cequence/protocol/openid-connect/token",
"client_id": "<client id>"

Start the service with the client secret in CEQUENCE_CLIENT_SECRET. mulesoft/docker-compose.yaml runs it next to the gateway on one Docker network; on Kubernetes, run the same image as a Deployment of two replicas behind a Service. It listens for the gateway on port 18081.

With the compose file, three things to set before docker compose up -d:

• Your gateway's registration goes in mulesoft/conf.d/: the registration.yaml that flexctl registration create wrote for your gateway.
• The Omni Gateway image's version: replace <version> in mulesoft/flex-gateway:<version> with the one you run. The Defender image is already named for this release.
• The policy's URI in the next step is then h2://defender-extproc:18081, the service's name on the compose network.

2. Apply the External Processing policy

Connected mode. In API Manager, open your API, or Automated Policies to cover every API in the environment. Choose Add inbound policy, then External Processing, and set:

Leave the header, body and trailer modes at their defaults: Defender asks the gateway for the request body and the response when it needs them.

Local mode. Copy mulesoft/policy-binding.yaml into the gateway's configuration directory, with targetRef.name set to your API instance.

Put External Processing first among the API's policies, so Defender decides on what the client sent.

3. Check it before you go live

1. Set "diagnostics": true in defender.json on a test gateway, restart the Defender service, and request /__end/status through one of your APIs. policies_loaded shows your tenant's policy count.
2. Send a request that one of your policies blocks, and check it is blocked. Send one that should pass, and check it passes.
3. In API Manager, the API's Key Metrics count Defender's blocks: under Total Errors over Time as status code 4XX, a few minutes after the requests. They are not Policy Violations, which counts only MuleSoft's own policies.
4. Set "diagnostics": false again. The status page is readable by anyone who can reach the API.

On CloudHub 2.0

A Managed Omni Gateway runs in a CloudHub 2.0 private space, where nothing else can run beside it. Run the Defender service in your own AWS or Google Cloud network instead, behind an internal load balancer, and let the policy reach it over the private space's private connection: AWS PrivateLink, a Transit Gateway or a VPN. Only the policy's URI changes. Expect about a millisecond more than the figures below in the same region. Contact Cequence support for the deployment details for your cloud.

Upgrades and rollback

Each release publishes a new defender-extproc image version.

1. Change the image version: in docker-compose.yaml, or in your Kubernetes Deployment.
2. Restart the service. On Kubernetes, a rolling update replaces one replica at a time, so the gateway always has a Defender to call. With a single container, requests pass through uninspected for the few seconds of the restart.
3. Check /__end/status as in "Check it before you go live".

To roll back, set the previous image version and restart the same way. The External Processing policy and its settings do not change between releases.

Performance and sizing

Measured on a live Omni Gateway 1.14.2 with the Defender service beside it, at 25 requests a second of GETs and 2 KB JSON POSTs, with the External Processing policy on and then off. Defender's own decision is about a millisecond; the rest is the gateway's call to it. Keep the service close to the gateway: on another host, the network round trip adds to every request.

Cost

Cequence charges nothing for the infrastructure. The Defender service is one small container per replica, on infrastructure you already run beside the gateway. The External Processing policy is included with Omni Gateway.

Availability

• If Cequence is slow or unreachable, your traffic is unaffected. Defender keeps enforcing the policies it last received. It holds a bounded backlog of analytics and sends it once Cequence is reachable again; a long outage can drop the oldest.
• If the Defender service is unreachable or slow, Failure mode allow lets requests through to your API after the 500 ms message timeout, uninspected. Run two replicas so a restart or a failed container does not leave the gateway without one.
• If you need Defender off the path at once, remove or disable the External Processing policy in API Manager. The gateway stops calling Defender immediately.
• A fresh install blocks nothing until your tenant's first policy publish arrives.

Known limits

• block and add-header policies are enforced. challenge, rate-limit and redirect policies are reported but not applied: the request is forwarded.
• Mule Gateway on the Mule 4 runtime has no External Processing policy and is not supported.

If something is wrong

• Requests are not inspected. Check the policy is applied and first in order, and that the gateway can resolve and reach the URI's host on port 18081.
• No policies loaded. The Defender service's log says why it cannot reach your tenant: outbound access, the client ID or the secret. Check the tenant's hosts in defender.json end in .cequence.cloud.
• The API's Message Log is empty. It shows requests only with MuleSoft's Message Logging policy applied; Defender does not need it. To see blocks without it, use the API's Key Metrics (4XX errors).
• The client address is the gateway's or a load balancer's. Defender reads it from client_ip_header in defender.json (x-forwarded-for in the example). Set it to the header your load balancer writes.

Removing it

Remove the External Processing policy from the API, or the automated policy. The gateway stops calling Defender at once; then stop the Defender service.