IBM API Connect向けWallarmコネクタ¶

IBM API Connectは、APIの作成、保護、管理、監視のためのツールを含むフルライフサイクルのAPI管理ソリューションです。Wallarmはコネクタとして使用でき、IBM API Connectで管理されるAPIトラフィックを検査し、不正リクエストを軽減することでAPIを保護します。

WallarmをIBM API Connectと統合するには、外部にWallarm Nodeをデプロイし、検査のためにIBM API Gatewayがトラフィックをそのノードへプロキシするように構成します。

IBM API Connect向けWallarmコネクタはインライントラフィック解析のみをサポートします:

API仕様に一致するリクエスト

IBM API Connectの動作により、定義されたOpenAPIのパスに一致するリクエストのみがWallarm Nodeによって検査されます。

ユースケース¶

このソリューションは、IBM API Connect経由で公開されるAPIの保護に推奨されます。

制限事項¶

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.

All protected APIs are managed under a single Wallarm account; separating protection across multiple accounts for different infrastructures or environments is not yet supported.

要件¶

デプロイを進める前に、以下の要件を満たしていることを確認してください。

IBM API ConnectおよびIBM DataPower Gatewayの知識があること。
稼働中のIBM API Connect環境（ローカルまたはクラウド管理）。
IBM API Connectで公開済みのAPI。
コマンドライン操作用のIBM API Toolkit（apicまたはapic-slim）がインストールされていること。
US CloudまたはEU CloudのWallarm ConsoleでAdministratorロールを持つアカウントへのアクセス権。
0.13.x系では0.13.3以降、または0.14.1以降のバージョンのWallarm Node。

デプロイ¶

1. Wallarm Nodeをデプロイする¶

Wallarm NodeはWallarmプラットフォームの中核コンポーネントで、受信トラフィックを検査し、不正な挙動を検出し、脅威を軽減するように構成できます。

必要な管理レベルに応じて、Wallarmホスト型として、またはご自身のインフラストラクチャ内にデプロイできます。

必須のWallarm Nodeバージョン

IBM API Connectとの統合には、Wallarm Nodeのバージョンとして0.13.x系では0.13.3以降、または0.14.1以降が必要です。旧バージョンはこのコネクタをサポートしません。

Edge nodeSelf-hosted node

コネクタ用のWallarmホスト型ノードをデプロイするには、手順に従ってください。

セルフホストノードをデプロイするためのアーティファクトを選択し、各手順に従ってください:

ベアメタルまたはVM上のLinux環境向けのAll-in-one installer
コンテナ化デプロイを使用する環境向けのDocker image
Kubernetesを利用するインフラストラクチャ向けのHelm chart

2. Wallarmポリシーを取得し、IBM API ConnectのAPIに適用する¶

Wallarmは、API ConnectのAPIに付与できるカスタムポリシーを提供します。これらのポリシーは、APIのリクエストおよびレスポンスをWallarm Node経由でプロキシし、検査と脅威検出を行います。

Wallarm Console → Security Edge → Connectors → Download code bundleへ進み、プラットフォーム用のcode bundleをダウンロードします。

セルフホストノードを実行している場合は、code bundle取得のためsales@wallarm.comまでご連絡ください。

リクエスト検査ポリシーを登録します:

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

レスポンス検査ポリシーを登録します:

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

多くの場合、configured-gateway-serviceの名前はdatapower-api-gatewayです。

3. アセンブリパイプラインにWallarmの検査ステップを統合する¶

API仕様のx-ibm-configuration.assembly.executeセクション内で、トラフィックをWallarm Node経由にルーティングするため、以下のステップを追加または更新します。

invokeステップの前に、受信リクエストをWallarm Nodeへプロキシするwallarm_preステップを追加します。
invokeステップを次のように構成してください:
- target-urlは$(target-url)$(request.path)?$(request.query-string)という形式にします。これにより、元のバックエンドのパスとクエリパラメータを保ったままリクエストがプロキシされます。
- header-controlおよびparameter-controlでは、すべてのヘッダーとパラメータの通過を許可します。これにより、Wallarm Nodeがリクエスト全体を解析し、あらゆる部分の攻撃を検出し、APIインベントリを正確に構築できます。
invokeステップの後に、レスポンスをWallarm Nodeへプロキシして検査するwallarm_postステップを追加します。

...
x-ibm-configuration:
  properties:
    target-url:
      value: <BACKEND_ADDRESS>
  ...
  assembly:
    execute:
      - wallarm_pre:
          version: 1.0.1
          title: wallarm_pre
          wallarmNodeAddress: <WALLARM_NODE_URL>
      - 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.1
          title: wallarm_post
          wallarmNodeAddress: <WALLARM_NODE_URL>
...

Wallarmポリシーでサポートされるプロパティ:

パラメータ	ステップ名	説明	必須?
`wallarmNodeAddress`	`wallarm_pre`, `wallarm_post`	Wallarm NodeインスタンスのURL。	はい
`failSafeBlock`	`wallarm_pre`, `wallarm_post`	`true`（デフォルト）の場合、リクエスト/レスポンス転送中にWallarm Nodeが利用不可であるかエラーを返した際に、リクエストまたはレスポンスをブロックします。	いいえ

4. 変更済みAPIを含むプロダクトを公開する¶

トラフィックフローへの変更を適用するには、変更した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>

例: Wallarmポリシーを適用したAPIとプロダクト¶

この例は、アセンブリにwallarm_pre、invoke、wallarm_postの各ステップ（リクエスト/レスポンス検査）を追加した基本的なAPIとプロダクト構成を示します。これをデプロイして、Wallarm Node経由のトラフィック検査をテストできます。

API仕様:

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.1
          title: wallarm_pre
          wallarmNodeAddress: <WALLARM_NODE_URL>
      - 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.1
          title: wallarm_post
          wallarmNodeAddress: <WALLARM_NODE_URL>
  activity-log:
    enabled: true
    success-content: activity
    error-content: payload

プロダクト仕様:

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

テスト¶

デプロイしたポリシーの機能をテストするには、次の手順に従います。

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'
```
IBM API Connectの動作により、定義されたOpenAPIのパスに一致するリクエストのみがWallarm Nodeによって検査されます。
Wallarm ConsoleのUS CloudまたはEU CloudでAttacksセクションを開き、攻撃が一覧に表示されていることを確認します。

Wallarm nodeのモードがin blockingで、トラフィックがインラインで流れている場合は、リクエストもブロックされます（スクリーンショットはこのケースを示しています）。

ポリシーのアップグレード¶

デプロイ済みのWallarmポリシーを新しいバージョンへアップグレードするには:

Wallarm Console → Security Edge → Connectors → Download code bundleから、IBM向けの更新済みWallarmポリシーをダウンロードします。

セルフホストノードを実行している場合は、更新済みのcode bundle取得のためsales@wallarm.comまでご連絡ください。

policies:createコマンドで各ポリシーを再登録し、更新された.zipファイルを指定します:

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

wallarm-post.zipについても同様に実施します。

API仕様内のx-ibm-configuration.assembly.executeで、ポリシーのバージョンを更新します:

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

両ポリシーは同一のバージョン番号を使用します。

products:publishコマンドを使用して、関連するプロダクトを再公開します。

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>

ポリシーのアップグレードでは、特にメジャーバージョンの更新時にWallarm Nodeのアップグレードが必要な場合があります。セルフホストNodeのリリースノートおよびアップグレード手順はNative Nodeの変更履歴をご参照ください。Wallarmホスト型の場合はEdgeコネクタのアップグレード手順をご覧ください。非推奨を避け、将来のアップグレードを容易にするため、定期的なNodeの更新を推奨します。