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

Watch the install (4 minutes): downloading the release, starting Defender beside DataPower, uploading the scripts, the three actions in the WebGUI, and an allowed and a blocked request in DataPower's Probe.

At a glance

Deployment architecture

Defender protects services on IBM DataPower Gateway used on its own: a Multi-Protocol Gateway (MPGW) and its processing policy. Three GatewayScript actions do the work:

• defender-decide, the first action of the request rule: sends each request to Defender. When Defender blocks, it rejects the message, so the rest of the rule and the backend call do not run.
• defender-block, in the error rule: answers a blocked request with your policy's status and block page. It does nothing for any other error.
• defender-record (optional), the first action of the response rule: sends the backend's 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 a host next to the appliance. The actions call it over HTTP on port 18082.

For DataPower under IBM API Connect (the API Gateway service and its assemblies), use Defender for IBM API Connect instead.

  BEFORE

    client ---> MPGW: request rule ---------------------------> your backend


  AFTER

    client ---> MPGW: request rule ---------------------------> your backend
                  |  defender-decide       defender-record (response rule)
                  |  (defender-block in the error rule 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 gateways, their front side handlers, your rules' other actions and your backends. defender-decide and defender-record read the message and never write it, so a rule that forwarded the request, or returned the response, correctly before still does so afterwards.

What Defender does with a request. A blocked request is answered from your error rule 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.

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

There is no installer for this platform, on purpose: where an action goes in a rule decides what your backend receives, and only you know what your existing rules do. You add the actions to your processing policy as below.

Prerequisites

• IBM DataPower Gateway with GatewayScript, and the Multi-Protocol Gateway to protect. Validated on DataPower Gateway 10.6.0.8.
• Access to the MPGW's domain through the WebGUI, or the REST management interface (port 5554) with a user that has access to the domain.
• Somewhere to run Defender beside DataPower: its Docker network, its Kubernetes namespace, or a host next to the appliance.
• 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.
• Your tenant's name, client ID and client secret.

The defender-for-datapower bundle holds the three scripts, an example Defender configuration (datapower/defender.json) and a complete example MPGW (datapower/defender-example.cfg).

1. Run Defender

Fill in datapower/defender.json with your tenant's edge and auth hosts and client ID, and start Defender with the client secret and the HTTP listener set, on DataPower's network:

export CEQUENCE_CLIENT_SECRET=<client secret>
docker run -d --name defender-extproc --network <datapower network> --restart unless-stopped \
  -e DEFENDER_CONFIG=/etc/defender/defender.json -e DEFENDER_HTTP_LISTEN=0.0.0.0:18082 \
  -e CEQUENCE_CLIENT_SECRET \
  -v "$PWD/defender.json:/etc/defender/defender.json:ro" \
  <defender-extproc image>:<version>

On Kubernetes, run the same image as a Deployment with a Service in DataPower's namespace. Defender's HTTP decision API has no authentication of its own: expose it only to DataPower.

2. Add the actions to your processing policy

1. Point the scripts at Defender. In defender-decide.js and defender-record.js, replace the address with the one DataPower reaches Defender at:

   sed -i 's|http://127.0.0.1:18082|http://<defender>:18082|' defender-decide.js defender-record.js
   

2. Upload the three scripts to local:///defender/ in the MPGW's domain, in the WebGUI under Administration > Main > File Management, or through the REST management interface:

   curl -sk -u "$DP_USER:$DP_PASSWORD" -X POST "https://<datapower>:5554/mgmt/filestore/<domain>/local" -d '{"directory": {"name": "defender"}}'
   for f in defender-decide.js defender-block.js defender-record.js; do curl -sk -u "$DP_USER:$DP_PASSWORD" -X POST "https://<datapower>:5554/mgmt/filestore/<domain>/local/defender" -d "{\"file\": {\"name\": \"$f\", \"content\": \"$(base64 -w0 "$f")\"}}"; done
   

3. Add the actions. In the WebGUI, open the Multi-Protocol Gateway, then its Multi-Protocol Gateway Policy:

4. Request rule (the rule matching the traffic to protect, direction Client to Server): a GatewayScript action as the first action after the Match, with GatewayScript file local:///defender/defender-decide.js, Input INPUT and Output NULL. Leave the rest of the rule as it is.
5. Error rule: if the policy has none, add one (direction Error, a Match on *) with one GatewayScript action, local:///defender/defender-block.js, Input INPUT, Output OUTPUT. If it has one, add that action last in it.
6. Response rule (optional; direction Server to Client): a GatewayScript action first after the Match, with local:///defender/defender-record.js, Input INPUT and Output NULL. If the policy has no response rule, add one with that action followed by a Results action, Input INPUT, Output OUTPUT.

Then Apply Policy, Apply the MPGW, and Save Configuration. 4. Check the MPGW's message types. Request Type and Response Type must be Non-XML (or JSON, XML or SOAP where every message is that type), not Pass through, which does not run the policy's actions on the payload. For GET and other requests without a body, enable Process Messages Whose Body Is Empty (Advanced tab).

To try Defender on a new MPGW first, defender-example.cfg is a complete example in DataPower's CLI configuration format: the actions, the three rules, an HTTP front side handler on port 8080 and an MPGW in front of one backend. Set its backend URL, upload it with the scripts to a test domain, and run it from the domain's CLI with exec local:///defender-example.cfg, or through the REST management interface's ExecConfig action. In release 0.20.1 the file begins with top; configure terminal; and ends with exit, which DataPower refuses there: delete those two lines first.

3. Check it before you go live

1. From DataPower's network, check that Defender answers: curl -s http://<defender>:18082/healthz answers ok.
2. In your tenant, create a policy that blocks on a test header, wait a moment for Defender to fetch it, and call the MPGW with and without that header. With it, you get the policy's status and page, and the backend sees no request; without it, the backend's own answer.
3. The transaction for the request without the header appears in your tenant with the backend's response status.
4. Stop Defender and call the MPGW again: you get the backend's answer, and defender-decide: not decided, forwarding in the domain's log.
5. To see each path in DataPower, use the WebGUI's Probe for the MPGW: enable it, send the two requests, and open the capture. The request that passed ran the request rule and then the response rule; the blocked one ran the request rule and then the error rule, where defender-block answered, and is counted as a failed transaction.

Behind an outbound proxy

If Defender reaches the internet only through a proxy, add a proxy section to its configuration (defender.json):

"proxy": { "url": "http://proxy.internal:3128", "username": "<proxy username>", "no_proxy": ["<hosts reached directly>"] }

url is an HTTP proxy (http://; your HTTPS calls to Cequence go through it with CONNECT and stay encrypted end to end), a proxy you reach over TLS (https://), or SOCKS5 (socks5://, or socks5h:// to have the proxy resolve host names). Give the container the password as CEQUENCE_PROXY_PASSWORD: export it and add -e CEQUENCE_PROXY_PASSWORD to the docker run command. A password in defender.json, or credentials in the url, is refused. Defender logs the proxy it uses when it starts, never the password.

Upgrades and rollback

• Defender: replace the container, or roll the Deployment, with the new image tag. While it restarts, requests go through uninspected.
• The scripts: edit the address in the new files as in step 2, and upload each over the old one (in File Management, or a PUT to .../mgmt/filestore/<domain>/local/defender/<file>). Flush the GatewayScript cache if the new version does not take effect. The actions and rules need no change.

To roll back, do the same with the previous image and the previous bundle's scripts.

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 DataPower 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 DataPower Gateway 10.6.0.8 with the example MPGW: an ordinary request reached the backend unaltered, a tenant policy blocked with the tenant's status and page in 11 ms, 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 a Docker host, Kubernetes cluster or server you already run. 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 backend untouched and uninspected: at once when the connection is refused, and after the 1 second timeout when Defender does not answer. If its address stops resolving, as when its container is stopped, each call takes about a second, about 2 seconds per request with defender-record. A failed response call never affects the response.
• If you need Defender off the path at once, take defender-decide out of the request rule and apply the policy.
• 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.
• Multi-Protocol Gateways are supported. Other DataPower services (Web Service Proxy, XML Firewall, the API Gateway service outside API Connect) are not.
• Requests DataPower rejects before the processing policy (TLS, the front side handler's method and URL limits) are not seen by Defender.
• An MPGW delays error responses by default (Delay Error Messages, 1000 ms in IBM's sample configuration), and a block is answered from the error rule, so blocked requests may be held that long unless the setting is off.
• Defender's HTTP decision API is plain HTTP, without TLS: keep it on a network only DataPower reaches.

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 the domain's log for lines starting defender-decide:, and check /healthz from DataPower's network. Then check that the MPGW's message types are not Pass through.
• DataPower logs "Unable to open the script module file 'local:///defender/...'", and requests get a 500. The scripts are not in local:///defender/ of the MPGW's domain: upload all three again and check each upload answered 201. Each takes a few seconds; let one finish before testing.
• A block is answered with a 500, not your page. The processing policy has no error rule running defender-block: add it as in step 2.
• Blocked requests take about a second. That is the MPGW's Delay Error Messages setting; turn it off if you do not want blocked answers held.
• An updated script does not take effect. Flush the GatewayScript cache.
• No policies loaded. Defender's logs say why it cannot reach your tenant: outbound access, the client ID or the secret.
• Every request appears to come from the same address. DataPower is behind a load balancer: set client_ip_header in defender.json to the header the load balancer writes, usually x-forwarded-for.

Removing it

1. Take the actions out of the rules: defender-decide from the request rule, defender-record from the response rule and defender-block from the error rule. Delete the error and response rules if you added them for Defender. Apply the policy and save the configuration.
2. Delete the action objects (Objects > Multi-Protocol Gateway Processing Actions, or the policy editor), then the files in local:///defender/.
3. Stop the Defender container.

Take the actions out first: with Defender stopped and the actions still in place, traffic keeps flowing, but every request waits for a refused connection.