Wallarm Connector for IBM API Connect¶

IBM API Connect is a full lifecycle API management solution that includes tools for creating, securing, managing, and monitoring APIs. Wallarm can be used as a connector to protect APIs managed through IBM API Connect by inspecting API traffic and mitigating malicious requests.

To integrate Wallarm with IBM API Connect, deploy a Wallarm node externally and configure IBM API Gateway to proxy traffic to the node for inspection.

The Wallarm connector for IBM API Connect supports both in-line (blocking) and monitoring (out-of-band) traffic analysis. You select the mode per policy with the failSafeBlock property (see Traffic modes):

Traffic modes¶

Both Wallarm policies (wallarm_pre for requests and wallarm_post for responses) run in one of two modes, selected by the failSafeBlock property. Set the same value on both policies.

Use cases¶

This solution is recommended for securing APIs published via IBM API Connect.

Limitations¶

• When deploying the Wallarm service with the LoadBalancer type using the Helm chart, a trusted SSL/TLS certificate is required for the domain. Self-signed certificates are not yet supported.

• Custom blocking page and blocking code configurations are not yet supported.

  All blocked malicious traffic is returned with status code 403 and the default block page.

• Rate limiting by Wallarm rules is not supported.

  Rate limiting cannot be enforced on the Wallarm side for this connector. If you need rate limiting, use the features built into your API gateway or cloud platform.

• Multitenancy is not supported on Security Edge hosting, but it is supported for a self-hosted node deployed with the connector.

Requirements¶

To proceed with the deployment, ensure that the following requirements are met:

• Familiarity with IBM API Connect and IBM DataPower Gateway.

• An IBM API Connect environment up and running (either local or cloud-managed).

• A published API in IBM API Connect.

• IBM API Toolkit installed for command-line interaction (apic or apic-slim).

• Access to the account with the Administrator role in Wallarm Console for the US Cloud or EU Cloud, or ME Cloud.

• Wallarm Node of version 0.13.3 or later in the 0.13.x series, or version 0.14.1 or later.

Deployment¶

1. Deploy a Wallarm node¶

The Wallarm node is a core component of the Wallarm platform that you need to deploy. It inspects incoming traffic, detects malicious activities, and can be configured to mitigate threats.

You can deploy it either hosted by Wallarm or in your own infrastructure, depending on the level of control you require.

2. Obtain and apply the Wallarm policies to APIs in IBM API Connect¶

Wallarm provides custom policies that can be attached to APIs in API Connect. These policies proxy API requests and responses through the Wallarm Node for inspection and threat detection.

1. Proceed to Wallarm Console → Security Edge → Connectors → Download code bundle and download a code bundle for your platform.

   If running a self-hosted node, contact sales@wallarm.com to get the code bundle.

2. Register the request inspection policy:

   apic policies:create \
       --scope <CATALOG OR SPACE> \
       --server <MANAGEMENT SERVER ENDPOINT> \
       --org <ORG NAME OR ID> \
       --catalog <CATALOG NAME OR ID> \
       --configured-gateway-service <GATEWAY SERVICE NAME OR ID> \
       /<PATH>/wallarm-pre.zip
   

3. Register the response inspection policy:

   apic policies:create \
       --scope <CATALOG OR SPACE> \
       --server <MANAGEMENT SERVER ENDPOINT> \
       --org <ORG NAME OR ID> \
       --catalog <CATALOG NAME OR ID> \
       --configured-gateway-service <GATEWAY SERVICE NAME OR ID> \
       /<PATH>/wallarm-post.zip
   

In most cases, the configured-gateway-service name is datapower-api-gateway.

3. Integrate Wallarm inspection steps into the assembly pipeline¶

In your API specification, within the x-ibm-configuration.assembly.execute section, add or update the following steps to route traffic through the Wallarm Node:

1. Before the invoke step, add the wallarm_pre step to proxy incoming requests to the Wallarm Node.

2. Ensure that the invoke step is configured as follows:

   • The target-url should follow the format $(target-url)$(request.path)?$(request.query-string). This ensures that requests are proxied to the original backend path along with any query parameters.
   • header-control and parameter-control allow all headers and parameters to pass through. This enables the Wallarm Node to analyze the full request, detect attacks in any part of it, and accurately build the API inventory.

3. After the invoke step, add the wallarm_post step to proxy responses to the Wallarm Node for inspection.

...
x-ibm-configuration:
  properties:
    target-url:
      value: <BACKEND_ADDRESS>
  ...
  assembly:
    execute:
      - wallarm_pre:
          version: 1.0.2
          title: wallarm_pre
          wallarmNodeAddress: <WALLARM_NODE_URL>
          failSafeBlock: true   # false = monitoring (out-of-band) mode
      - invoke:
          title: invoke
          version: 2.0.0
          verb: keep
          target-url: $(target-url)$(request.path)?$(request.query-string)
          persistent-connection: true
      - wallarm_post:
          version: 1.0.2
          title: wallarm_post
          wallarmNodeAddress: <WALLARM_NODE_URL>
          failSafeBlock: true   # false = monitoring (out-of-band) mode
...

Supported properties in Wallarm policies:

To run the policies in monitoring (out-of-band) mode, set failSafeBlock: false on both the wallarm_pre and wallarm_post steps.

4. Publish your product with the updated API¶

To apply changes to the traffic flow, re-publish the product that includes the modified API:

apic products:publish \
    --scope <CATALOG OR SPACE> \
    --server <MANAGEMENT SERVER ENDPOINT> \
    --org <ORG NAME OR ID> \
    --catalog <CATALOG NAME OR ID> \
    <PATH TO THE UPDATED PRODUCT YAML>

Example: API and product with Wallarm policies¶

This example shows a basic API and product configuration with Wallarm request and response inspection steps (wallarm_pre, invoke, wallarm_post) added to the assembly. You can deploy it to test traffic inspection via Wallarm Node.

• API specification:

openapi: 3.0.3
info:
  title: Hello API
  version: 1.0.0
  x-ibm-name: hello-api
servers:
  - url: /
paths:
  /hello:
    get:
      summary: Say Hello
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
x-ibm-configuration:
  properties:
    target-url:
      value: https://httpbin.org
      description: Where to proxy the filtered traffic
      encoded: false
  type: rest
  phase: realized
  enforced: true
  testable: true
  cors:
    enabled: true
  gateway: datapower-api-gateway
  assembly:
    execute:
      - wallarm_pre:
          version: 1.0.2
          title: wallarm_pre
          wallarmNodeAddress: <WALLARM_NODE_URL>
          failSafeBlock: true   # false = monitoring (out-of-band) mode
      - invoke:
          title: invoke
          version: 2.0.0
          verb: keep
          target-url: $(target-url)$(request.path)?$(request.query-string)
          persistent-connection: true
      - wallarm_post:
          version: 1.0.2
          title: wallarm_post
          wallarmNodeAddress: <WALLARM_NODE_URL>
          failSafeBlock: true   # false = monitoring (out-of-band) mode
  activity-log:
    enabled: true
    success-content: activity
    error-content: payload

• Product specification:

product: 1.0.0
info:
  name: hello-product
  title: Hello Product
  version: 1.0.0
  description: A basic product exposing Hello API
apis:
  hello-api:
    $ref: ./api.yaml
plans:
  default:
    title: Default Plan
    description: Open access plan
    approval: false
    rate-limit:
      value: unlimited
    apis:
      hello-api: {}
visibility:
  view:
    enabled: true
    type: public
  subscribe:
    enabled: true
    type: authenticated
gateways:
  - datapower-api-gateway

Testing¶

To test the functionality of the deployed policies, follow these steps:

1. Send the request with the test Path Traversal attack to your API:

   curl -k --request GET --url https://localhost:9444/<PATH ALLOWED BY SPEC> \
     --header 'X-IBM-Client-Id: <YOUR IBM CLIENT ID>' \
     --header 'accept: /etc/passwd'
   

   According to IBM API Connect behavior, only requests matching the defined OpenAPI paths will be inspected by the Wallarm Node.

2. Open Wallarm Console → Attacks section in the US Cloud or EU Cloud, or ME Cloud and make sure the attack is displayed in the list.

   

   If the Wallarm node mode is set to blocking and the traffic flows in-line, the request will also be blocked (the screenshot demonstartes this case).

Upgrading the policies¶

To upgrade the deployed Wallarm policies to a newer version:

1. Download the updated Wallarm policies for IBM from Wallarm Console → Security Edge → Connectors → Download code bundle.

   If running a self-hosted node, contact sales@wallarm.com to get the updated code bundle.

2. Re-register each policy using the policies:create command and specify the updated .zip files:

   apic policies:create \
       --scope <CATALOG OR SPACE> \
       --server <MANAGEMENT SERVER ENDPOINT> \
       --org <ORG NAME OR ID> \
       --catalog <CATALOG NAME OR ID> \
       --configured-gateway-service <GATEWAY SERVICE NAME OR ID> \
       /<PATH>/wallarm-pre.zip
   

3. Repeat for wallarm-post.zip.

4. In your API specification, update the policy versions in x-ibm-configuration.assembly.execute:

   ...
   x-ibm-configuration:
     ...
     assembly:
       execute:
         - wallarm_pre:
             version: <NEW_VERSION>
         ...
         - wallarm_post:
             version: <NEW_VERSION>
   ...
   

   Both policies use the same version number.

5. Re-publish the associated product using the products:publish command.

   apic products:publish \
       --scope <CATALOG OR SPACE> \
       --server <MANAGEMENT SERVER ENDPOINT> \
       --org <ORG NAME OR ID> \
       --catalog <CATALOG NAME OR ID> \
       <PATH TO THE UPDATED PRODUCT YAML>
   

Policy upgrades may require a Wallarm node upgrade, especially for major version updates. See the Native Node changelog for the self-hosted Node release notes and upgrade instructions or the Edge connector upgrade procedure. Regular node updates are recommended to avoid deprecation and simplify future upgrades.

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send