Wallarm APIリクエスト例¶
以下はWallarm APIの使用例です。コード例はUS cloudまたはEU cloud向けのAPI Reference UIでも生成できます。経験豊富なユーザーは、ブラウザのDeveloper console（“Network”タブ）を使用して、WallarmアカウントのUIがパブリックAPIからデータを取得するためにどのAPIエンドポイントとリクエストを使用しているかを素早く把握できます。Developer consoleの開き方は、公式ブラウザドキュメント（Safari、Chrome、Firefox、Vivaldi）を参照してください。
直近24時間に検出された攻撃の先頭50件を取得する¶
TIMESTAMPは、24時間前の日付をUNIXタイムスタンプ形式に変換した値に置き換えてください。
curl -v -X POST "https://us1.api.wallarm.com/v1/objects/attack" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"time\": [[TIMESTAMP, null]] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
curl -v -X POST "https://api.wallarm.com/v1/objects/attack" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"time\": [[TIMESTAMP, null]] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
大量の攻撃（100件以上）を取得する¶
100件以上のレコードを含む攻撃やヒットの集合は、パフォーマンスを最適化するため、一度に大きなデータセットを取得するのではなく、小さな単位に分割して取得するのが最適です。該当するWallarm APIエンドポイントは、1ページあたり100件のカーソルベースページネーションをサポートします。
この手法では、データセット内の特定の項目を指すポインタを返し、後続のリクエストではそのポインタ以降の結果をサーバーが返します。カーソルページネーションを有効にするには、リクエストパラメータに"paging": trueを含めてください。
以下は、カーソルページネーションを使用して
このリクエストは、最新から古い順に並べられた最新100件の攻撃情報を返します。加えて、レスポンスには次の100件へのポインタを含むcursorパラメータが含まれます。
次の100件の攻撃を取得するには、前回と同じリクエストを使用し、前回のレスポンスからコピーしたポインタ値をcursorパラメータとして含めてください。これにより、APIは次の100件の返却開始位置を把握できます。例:
curl -k 'https://api.wallarm.com/v2/objects/attack' \
-X POST \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"cursor":"<POINTER_FROM_PREVIOUS_RESPONSE>", "paging": true, "filter": {"clientid": [<YOUR_CLIENT_ID>], "vulnid": null, "time": [[<TIMESTAMP>, null]], "!state": "falsepositive"}}'
curl -k 'https://us1.api.wallarm.com/v2/objects/attack' \
-X POST \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"cursor":"<POINTER_FROM_PREVIOUS_RESPONSE>", "paging": true, "filter": {"clientid": [<YOUR_CLIENT_ID>], "vulnid": null, "time": [[<TIMESTAMP>, null]], "!state": "falsepositive"}}'
さらに続きのページを取得するには、前回のレスポンスからコピーした値をcursorパラメータに含めたリクエストを実行してください。
以下は、カーソルページングを使用して攻撃を取得するPythonコード例です。
import json
from pprint import pprint as pp
import requests
client_id = <YOUR_CLIENT_ID>
ts = <TIMESTAMP> # UNIX時刻
url = "https://api.wallarm.com/v2/objects/attack"
headers = {
"X-WallarmApi-Token": "<YOUR_TOKEN>",
"Content-Type": "application/json",
}
payload = {
"paging": True,
"filter": {
"clientid": [client_id],
"vulnid": None,
"time": [[ts, None]],
"!state": "falsepositive",
},
}
while True:
response = requests.post(url, headers=headers, json=payload)
data = response.json()
cursor = data.get("cursor")
if not cursor:
break
pp(data)
payload["cursor"] = cursor
import json
from pprint import pprint as pp
import requests
client_id = <YOUR_CLIENT_ID>
ts = <TIMESTAMP> # UNIX時刻
url = "https://us1.api.wallarm.com/v2/objects/attack"
headers = {
"X-WallarmApi-Token": "<YOUR_TOKEN>",
"X-WallarmAPI-Secret": "<YOUR_SECRET_KEY>",
"Content-Type": "application/json",
}
payload = {
"paging": True,
"filter": {
"clientid": [client_id],
"vulnid": None,
"time": [[ts, None]],
"!state": "falsepositive",
},
}
while True:
response = requests.post(url, headers=headers, json=payload)
data = response.json()
cursor = data.get("cursor")
if not cursor:
break
pp(data)
payload["cursor"] = cursor
直近24時間に確定したインシデントの先頭50件を取得する¶
このリクエストは直前の攻撃一覧の例と非常によく似ていますが、このリクエストには"!vulnid: null"の項目が追加されています。この項目は、脆弱性IDが指定されていない攻撃をすべて無視するようAPIに指示します。システムはこれによって攻撃とインシデントを区別します。
TIMESTAMPは、24時間前の日付をUNIXタイムスタンプ形式に変換した値に置き換えてください。
curl -v -X POST "https://us1.api.wallarm.com/v1/objects/attack" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"\!vulnid\": null, \"time\": [[TIMESTAMP, null]] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
curl -v -X POST "https://api.wallarm.com/v1/objects/attack" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"filter\": { \"clientid\": [YOUR_CLIENT_ID], \"\!vulnid\": null, \"time\": [[TIMESTAMP, null]] }, \"offset\": 0, \"limit\": 50, \"order_by\": \"last_time\", \"order_desc\": true}"
直近24時間におけるステータス"active"の脆弱性の先頭50件を取得する¶
TIMESTAMPは、24時間前の日付をUNIXタイムスタンプ形式に変換した値に置き換えてください。
curl -v -X POST "https://us1.api.wallarm.com/v1/objects/vuln" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"limit\":50, \"offset\":0, \"filter\":{\"clientid\":[YOUR_CLIENT_ID], \"testrun_id\":null, \"validated\":true, \"time\":[[TIMESTAMP, null]]}}"
curl -v -X POST "https://api.wallarm.com/v1/objects/vuln" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"limit\":50, \"offset\":0, \"filter\":{\"clientid\":[YOUR_CLIENT_ID], \"testrun_id\":null, \"validated\":true, \"time\":[[TIMESTAMP, null]]}}"
構成済みのルールをすべて取得する¶
すべてのルールの条件のみを取得する¶
特定の条件に紐づくルールを取得する¶
特定の条件を指し示すにはそのIDを使用します。IDはすべてのルールの条件をリクエストするときに取得できます（上記参照）。
/my/api/*に送信されるすべてのリクエストをブロックする仮想パッチを作成する¶
curl -v -X POST "https://us1.api.wallarm.com/v1/objects/hint/create" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"clientid\": YOUR_CLIENT_ID, \"type\": \"vpatch\", \"action\": [ {\"type\":\"equal\",\"value\":\"my\",\"point\":[\"path\",0]}, {\"type\":\"equal\",\"value\":\"api\",\"point\":[\"path\",1]}], \"validated\": false, \"point\": [ [ \"header\", \"HOST\" ] ], \"attack_type\": \"any\"}"
curl -v -X POST "https://api.wallarm.com/v1/objects/hint/create" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"clientid\": YOUR_CLIENT_ID, \"type\": \"vpatch\", \"action\": [ {\"type\":\"equal\",\"value\":\"my\",\"point\":[\"path\",0]}, {\"type\":\"equal\",\"value\":\"api\",\"point\":[\"path\",1]}], \"validated\": false, \"point\": [ [ \"header\", \"HOST\" ] ], \"attack_type\": \"any\"}"
特定のアプリケーションインスタンスID向けに/my/api/*に送信されるすべてのリクエストをブロックする仮想パッチを作成する¶
このリクエストを送信する前に、アプリケーションを構成しておく必要があります。既存のアプリケーションのIDをaction.point[instance].valueに指定してください。
curl -v -X POST "https://us1.api.wallarm.com/v1/objects/hint/create" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"vpatch\",\"action\":[{\"point\":[\"instance\"],\"type\":\"equal\",\"value\":\"-1\"},{\"point\":[\"path\",0],\"type\":\"equal\",\"value\":\"my\"},{\"point\":[\"path\",1],\"type\":\"equal\",\"value\":\"api\"}],\"clientid\":YOUR_CLIENT_ID,\"validated\":false,\"point\":[[\"header\",\"HOST\"]],\"attack_type\":\"any\"}"
curl -v -X POST "https://api.wallarm.com/v1/objects/hint/create" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"vpatch\",\"action\":[{\"point\":[\"instance\"],\"type\":\"equal\",\"value\":\"-1\"},{\"point\":[\"path\",0],\"type\":\"equal\",\"value\":\"my\"},{\"point\":[\"path\",1],\"type\":\"equal\",\"value\":\"api\"}],\"clientid\":YOUR_CLIENT_ID,\"validated\":false,\"point\":[[\"header\",\"HOST\"]],\"attack_type\":\"any\"}"
X-FORWARDED-FORヘッダーの特定の値を持つリクエストを攻撃として扱うルールを作成する¶
次のリクエストは、正規表現に基づくカスタム攻撃インジケーター ^(~(44[.]33[.]22[.]11))$を作成します。
MY.DOMAIN.COMへのリクエストにX-FORWARDED-FOR: 44.33.22.11というHTTPヘッダーがある場合、Wallarmノードはそれらをスキャナー攻撃と見なし、対応するフィルタリングモードが設定されていれば攻撃をブロックします。
curl -v -X POST "https://us1.api.wallarm.com/v1/objects/hint/create" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"regex\",\"action\":[{\"point\":[\"header\",\"HOST\"],\"type\":\"equal\",\"value\":\"MY.DOMAIN.NAME\"}],\"clientid\":YOUR_CLIENT_ID,\"validated\":false,\"comment\":\"comment\",\"point\":[[\"header\",\"X-FORWARDED-FOR\"]],\"attack_type\":\"scanner\",\"regex\":\"^\(~\(44[.]33[.]22[.]11\)\)$\"}"
curl -v -X POST "https://api.wallarm.com/v1/objects/hint/create" -H "X-WallarmApi-Token: <YOUR_TOKEN>" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"type\":\"regex\",\"action\":[{\"point\":[\"header\",\"HOST\"],\"type\":\"equal\",\"value\":\"MY.DOMAIN.NAME\"}],\"clientid\":YOUR_CLIENT_ID,\"validated\":false,\"comment\":\"comment\",\"point\":[[\"header\",\"X-FORWARDED-FOR\"]],\"attack_type\":\"scanner\",\"regex\":\"^\(~\(44[.]33[.]22[.]11\)\)$\"}"
特定のアプリケーションに対してフィルタリングモードをmonitoringに設定するルールを作成する¶
次のリクエストは、IDが3のアプリケーション宛てのトラフィックをmonitoringモードでフィルタリングするようノードを設定するルールを作成します。
curl 'https://us1.api.wallarm.com/v1/objects/hint/create' -H 'X-WallarmApi-Token: <YOUR_TOKEN>' -H "accept: application/json" -H "Content-Type: application/json" --data-raw '{"clientid":<YOUR_CLIENT_ID>,"type":"wallarm_mode","mode":"monitoring","validated":false,"action":[{"point":["instance"],"type":"equal","value":"3"}]}'
curl 'https://api.wallarm.com/v1/objects/hint/create' -H 'X-WallarmApi-Token: <YOUR_TOKEN>' -H "accept: application/json" -H "Content-Type: application/json" --data-raw '{"clientid":<YOUR_CLIENT_ID>,"type":"wallarm_mode","mode":"monitoring","validated":false,"action":[{"point":["instance"],"type":"equal","value":"3"}]}'
IDでルールを削除する¶
構成済みのルールをすべて取得する際に、削除したいルールIDをコピーできます。また、ルール作成リクエストのレスポンスにも、idレスポンスパラメータとしてルールIDが返されています。
IPリストオブジェクトの取得・追加・削除のためのAPI呼び出し¶
以下に、IPリストオブジェクトを取得、追加、削除するためのAPI呼び出し例を示します。
APIリクエストパラメータ¶
IPリストを読み取り・変更するAPIリクエストに渡すパラメータ:
| Parameter | Description |
|---|---|
X-WallarmApi-Token | Token to access Wallarm API, copy it from Wallarm Console → Settings → API tokens. |
clientid | ID of an account in Wallarm Cloud to populate/read IP list. |
ip_rule.list | The IP list type to add objects, can be: black (for denylist), white (for allowlist), gray (for graylist). |
ip_rule.rule_type | The type of objects to add to the list:
|
ip_rule.subnet( rule_type:"ip_range") | IP or subnet to add to the list, e.g. "1.1.1.1". |
ip_rule.source_values(for other rule_type values) | One of the options:
|
ip_rule.pools | Array of application IDs to allow or restrict access for IPs, e.g. [3,4] for applications IDs 3 and 4 or [0] for all applications. |
ip_rule.expired_at | Unix Timestamp date for IPs to be removed from the list. The maximum value is forever (33223139044). |
reason | Reason to allow or restrict access for IPs. |
force | If true and some objects specified in the request are already in the IP list, the script will overwrite them. |
.csvファイルからのエントリをリストに追加する¶
.csvファイル内のIPまたはサブネットをリストに追加するには、次のbashスクリプトを使用してください。
#!/bin/bash
UUID="<YOUR_UUID>"
SECRET="<YOUR_SECRET_KEY>"
CLIENT="<YOUR_CLIENT_ID>"
LIST="<TYPE_OF_IP_LIST>"
PATH_TO_CSV_FILE="<PATH_TO_CSV_FILE>" # path to the CSV file with IPs or subnets
APPLICATIONS="<APP_IDS_THROUGH_COMMA>"
REMOVE_DATE="TIMESTAMP_REMOVE_DATE"
REASON='<REASON>'
API="us1.api.wallarm.com"
index=0
while read line; do
subnets[$index]="$line"
index=$(($index+1))
done < "$PATH_TO_CSV_FILE"
for i in ${subnets[@]}; do
currentDate=`date -u +%s`
time=$REMOVE_DATE
remove_date=$(($currentDate+$time))
curl -X POST \
https://$API/v4/ip_rules \
-H "Content-Type: application/json" \
-H "X-WallarmApi-Token: <YOUR_TOKEN>" \
-d '{
"clientid": '$CLIENT',
"ip_rule": {
"list": "'$LIST'",
"rule_type": "ip_range",
"subnet": "'$i'",
"expired_at": '$remove_date',
"pools": [
'$APPLICATIONS'
],
"reason": "'"$REASON"'"
},
"force": false
}'
done
#!/bin/bash
UUID="<YOUR_UUID>"
SECRET="<YOUR_SECRET_KEY>"
CLIENT="<YOUR_CLIENT_ID>"
LIST="<TYPE_OF_IP_LIST>"
PATH_TO_CSV_FILE="<PATH_TO_CSV_FILE>" # path to the CSV file with IPs or subnets
APPLICATIONS="<APP_IDS_THROUGH_COMMA>"
REMOVE_DATE="TIMESTAMP_REMOVE_DATE"
REASON='<REASON>'
API="api.wallarm.com"
index=0
while read line; do
subnets[$index]="$line"
index=$(($index+1))
done < "$PATH_TO_CSV_FILE"
for i in ${subnets[@]}; do
currentDate=`date -u +%s`
time=$REMOVE_DATE
remove_date=$(($currentDate+$time))
curl -X POST \
https://$API/v4/ip_rules \
-H "Content-Type: application/json" \
-H "X-WallarmApi-Token: <YOUR_TOKEN>" \
-d '{
"clientid": '$CLIENT',
"ip_rule": {
"list": "'$LIST'",
"rule_type": "ip_range",
"subnet": "'$i'",
"expired_at": '$remove_date',
"pools": [
'$APPLICATIONS'
],
"reason": "'"$REASON"'"
},
"force": false
}'
done
単一のIPまたはサブネットをリストに追加する¶
To add particular IPs or subnets to the IP list, send the following request for each IP/subnet:
curl 'https://us1.api.wallarm.com/v4/ip_rules' \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{"clientid":<YOUR_CLIENT_ID>,"force":false,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>","pools":[<ARRAY_OF_APP_IDS>],"expired_at":<TIMESTAMP_REMOVE_DATE>,"rule_type":"ip_range","subnet":"<IP_OR_SUBNET>"}}'
curl 'https://api.wallarm.com/v4/ip_rules' \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{"clientid":<YOUR_CLIENT_ID>,"force":false,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>","pools":[<ARRAY_OF_APP_IDS>],"expired_at":<TIMESTAMP_REMOVE_DATE>,"rule_type":"ip_range","subnet":"<IP_OR_SUBNET>"}}'
複数の国をリストに追加する¶
curl 'https://us1.api.wallarm.com/v4/ip_rules' \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"country","source_values":[<ARRAY_OF_COUNTRIES_REGIONS>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'
curl 'https://api.wallarm.com/v4/ip_rules' \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"country","source_values":[<ARRAY_OF_COUNTRIES_REGIONS>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'
複数のプロキシサービスをリストに追加する¶
curl 'https://us1.api.wallarm.com/v4/ip_rules' \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"proxy_type","source_values":[<ARRAY_OF_PROXY_SERVICES>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'
curl 'https://api.wallarm.com/v4/ip_rules' \
-H 'X-WallarmApi-Token: <YOUR_TOKEN>' \
-H "accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{"clientid":<YOUR_CLIENT_ID>,"ip_rule":{"list":"<TYPE_OF_IP_LIST>","rule_type":"proxy_type","source_values":[<ARRAY_OF_PROXY_SERVICES>],"pools":[<ARRAY_OF_APP_IDS>],"expired_at":"<TIMESTAMP_REMOVE_DATE>","reason":"<REASON_TO_ADD_ENTRIES_TO_LIST>"},"force":false}'
IPリストからオブジェクトを削除する¶
オブジェクトはIDでIPリストから削除します。
オブジェクトIDを取得するには、IPリストの内容をリクエストし、レスポンスから対象オブジェクトのobjects.idをコピーしてください。
オブジェクトIDが分かったら、次のリクエストを送信してリストから削除してください。
削除リクエストでIDの配列を渡すことで、複数のオブジェクトを一度に削除できます。