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, then a real install with defenderctl-apic, Defender's global policies on the DataPower API Gateway in its WebGUI, an allowed and a blocked request, and removal.

At a glance

Deployment architecture

Defender protects APIs on IBM API Connect v10 with the DataPower API Gateway through API Connect's own global policies, which the gateway runs around every API in a catalog without any API being edited. Three global policies do the work:

• The pre-request hook runs before each API's assembly: it sends the request to Defender, and when Defender blocks, ends the transaction so the API's assembly does not run.
• The error hook answers a request Defender blocked with your policy's status and block page. Every other error keeps API Connect's own handling.
• The post-response hook (optional) sends the response so Defender can complete the request's analytics.

Defender itself runs beside DataPower: a container on the same Docker network, a Deployment and Service in the same Kubernetes namespace, or a service on the same host. The policies call it over HTTP on port 18082.

  BEFORE

    client ---> DataPower API Gateway ---> API assembly ---> your backend


  AFTER

    client ---> DataPower API Gateway ---> API assembly ---> your backend
                  |  pre-request hook       post-response hook
                  |  (error hook answers a block)
                  v                         v
               Defender service  (beside DataPower, HTTP on port 18082)
                  |
                  +---> your Cequence tenant: policies in, analytics out,
                        in the background

What stays the same. Your APIs, their assemblies and your backends. Nothing is installed on DataPower itself: no user-defined policy and no gateway extension. The hooks apply Defender to every API in the catalogs you choose, and removing them takes Defender out at once.

What Defender does with a request. A blocked request is answered by the gateway with your tenant's block page and never reaches your backend; none of the client's request headers are echoed back. 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. A policy that adds a request header has that header added before the request goes on. The pre-request hook runs before API Connect's built-in client identification, rate limiting and security, so Defender decides on every request the client sent.

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

• IBM API Connect v10 with a DataPower API Gateway service: the provider organization and the catalogs to protect.
• An API Connect user who is a provider organization owner or has Settings: Manage, or an API key.
• Somewhere to run Defender beside DataPower: its Docker network, its Kubernetes namespace, or its host.
• The defender-extproc image for this release, in a registry DataPower's host can pull from. Cequence support gives you access to the image for your release; the installer's render command prints its name.
• On the machine you install from: the apic toolkit (v10), curl, tar and python3.
• Your tenant's name, client ID and client secret.

1. Run Defender

From the unpacked defender-for-ibm-api-connect bundle, fill in defender.conf from defender.conf.example:

CEQUENCE_TENANT=<your tenant>
CEQUENCE_CLIENT_ID=<client id>
APIC_SERVER=<management server's platform API host>
APIC_ORG=<your provider organization>
APIC_CATALOGS=<catalogs, comma-separated>
APIC_GATEWAY_SERVICE=<your DataPower API Gateway service>
APIC_DEFENDER_URL=http://<where DataPower reaches Defender>:18082
APIC_REALM=provider/<identity provider>
APIC_USERNAME=<user>

To sign in with an API key instead, leave out APIC_REALM and APIC_USERNAME and export APIC_API_KEY. Then:

export CEQUENCE_CLIENT_SECRET=<client secret>
export APIC_PASSWORD=<password>
./bin/defenderctl-apic render

render changes nothing. It writes what the installer would upload to ./defender-apic/ for you to review, and prints a docker run command that starts Defender with your tenant's settings. The client secret is passed from your environment by name, so it is in no file. Run that command on the Docker network DataPower is on; on Kubernetes, run the same image as a Deployment with a ClusterIP Service in DataPower's namespace.

Defender's HTTP decision API has no authentication of its own: expose it only to DataPower.

2. Install with defenderctl-apic

./bin/defenderctl-apic preflight
./bin/defenderctl-apic install

preflight checks the apic toolkit and your sign-in, the organization, each catalog and its gateway service, the hooks, that Defender answers at APIC_DEFENDER_URL, and your tenant credential. The installer then uploads the three global policies to each catalog and creates the hooks last, the error hook first, so traffic goes through Defender only once everything is in place. It refuses to replace anything it did not create: a catalog has one hook of each kind, and if one of yours already runs another global policy, preflight tells you how to add Defender's step to that policy instead.

3. Check it before you go live

1. Run APIC_VERIFY_URL=https://<an API in the catalog> ./bin/defenderctl-apic verify. It checks that the hooks run Defender's policies, that an ordinary request passes and that a request matching a test policy is blocked.
2. Send a request that one of your own policies blocks, and check it is blocked.
3. ./bin/defenderctl-apic status shows each catalog's global policies and hooks, and whether Defender answers.
4. On the DataPower API Gateway, the WebGUI shows them too: in the apiconnect domain, search for Assembly and filter on defender-<namespace> (with no namespace set, defender-prod). Each catalog has its pre-request, error and post-response policy, each up and enabled.

Upgrades and rollback

./bin/defenderctl-apic upgrade

from the new bundle uploads the new version's global policies, points the hooks at them, and deletes the older versions no hook runs any more. Replace the Defender container with the image render prints from the new bundle; while it restarts, requests go through uninspected. To roll back, run upgrade from the previous bundle and run the previous image.

Performance and sizing

Every request waits for Defender's decision, so run Defender beside DataPower rather than across a network. Defender reads the first 64 KiB of each request body, and of each response body.

Measured on IBM API Connect 10.0.8.7 with DataPower API Gateway 10.6.0.8, Defender beside DataPower, alternating runs with and without Defender and with Defender confirmed deciding in each. Defender's own decision takes well under a millisecond; the rest is DataPower's call to it.

Validated on IBM API Connect 10.0.8.7 with DataPower API Gateway 10.6.0.8: a tenant policy blocked with the tenant's status and page, an allowed request reached the backend unaltered, a 300 KB request body and a 1 MB response passed whole, and with Defender stopped, requests went through.

Cost

Cequence charges nothing for the infrastructure. Defender is one container you run beside DataPower, on the Docker host, Kubernetes cluster or server you already run it on. Your usual infrastructure and IBM charges apply.

Availability

• If Cequence is slow or unreachable, your traffic is unaffected. Defender keeps enforcing the policies it last received, and sends the analytics it holds once Cequence is reachable again.
• If Defender is unreachable or slow, requests go through to your API uninspected: at once when the connection is refused, and after the 1 second timeout when Defender does not answer. If its address stops resolving, each call takes about a second, about 2 seconds per request with response recording on. A failed response call never affects the response.
• If you need Defender off the path at once, run ./bin/defenderctl-apic uninstall, or delete the pre-request hook in each catalog.
• 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.
• The DataPower API Gateway is supported. The DataPower Gateway (v5 compatible) is not.
• Defender applies to every API in a catalog, not to chosen APIs.
• Requests DataPower rejects before the pre-request hook (TLS, unknown paths) are not seen by Defender.
• Defender's HTTP decision API is plain HTTP, without TLS: keep it on a network only DataPower reaches.
• Response recording on APIs whose Invoke policy has buffering turned off is not validated yet.

If something is wrong

• Nothing is blocked. The most likely cause is that DataPower cannot reach Defender: requests go through when it cannot, so nothing else tells you. Look in DataPower's log for lines starting defender-decide:, and from DataPower's network check that curl -s http://<Defender>:18082/healthz answers ok. verify points to the same.
• DataPower's System Log shows "Assembly rule '...defender-...-prehook...' is interrupted: Failed to process the GatewayScript file". That is how DataPower logs Defender's block: the pre-request policy stops the request on purpose, and the error hook answers with your block page. One such pair of lines per blocked request is expected; allowed requests log nothing there.
• The installer refuses a hook. A catalog already has a hook of that kind running another global policy. Add Defender's step to that policy as preflight describes, point the hook at the new version, and leave that catalog out of APIC_CATALOGS.
• No policies loaded. Defender's logs say why it cannot reach your tenant: outbound access, the client ID or the secret. preflight also checks the credential.
• Every request appears to come from the same address. DataPower is behind a load balancer: set client_ip_header in Defender's configuration to the header the load balancer writes, usually x-forwarded-for.
• For Cequence support, ./bin/defenderctl-apic debug collects a support bundle with no passwords or secrets in it.

Removing it

./bin/defenderctl-apic uninstall

deletes the hooks first, the pre-request hook before the others, so traffic stops going through Defender, then the global policies the installer created. Anything it did not create is left alone. Then stop the Defender container.