【AeyeScan】VBAによるAPI実行方法

SaaS型Webアプリ診断ツール「AeyeScan」を運営している株式会社エーアイセキュリティラボによる、セキュリティテストの自動化、脆弱性診断の内製化、AI/機械学習などの技術情報の共有を目的とした記事です。
AeyeScanの情報はこちら https://www.aeyescan.jp
エーアイセキュリティラボの情報はこちら https://www.aeyesec.jp

[![2022-155641.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/dd3f69d5-879a-ed11-d6ac-353a85523c43.png)](https://www.aeyescan.jp)

こんにちは！株式会社エーアイセキュリティラボ　カスタマーサクセス担当　日髙です。
今回は、VBAのHTTP通信を利用して、AeyeScanにスキャン情報の一括登録を行う仕組みについてご紹介します。

# 目次
[概要](#概要)
[実現するもの](#実現するもの)
[作成のポイント](#作成のポイント)
[【ポイント①】HTTP通信によるドメイン登録](#ポイントhttp通信によるドメイン登録)
[【ポイント②】JSONパラメータの入れ子によるスキャン作成](#ポイントjsonパラメータの入れ子によるスキャン作成)
[利用上の注意](#利用上の注意)
[おわりに](#おわりに)
[参考文献](#参考文献)

# 概要
これまで、Google Apps Script（GAS）や自動化ツールを利用してスキャン実施や情報取得などの方法を解説してきましたが、企業によってはそもそもGASや自動化ツールを利用できないケースもあるかと思います。

そのため、今回の記事では、VBAのHTTP通信を利用して、APIを実行する方法をご紹介します。

AeyeScanでは様々なAPIを用意しており、今回ご紹介するのは、そのうちの一つであるスキャン情報の一括登録を行う仕組みです。スキャン情報の登録は画面から1件ずつ行うことができますが、スキャン対象が大量にある場合、スキャン情報も大量に作成しなければならず非常に面倒です。

この方法を利用すれば、GASや自動化ツールを使えない場合でもスキャン情報の一括登録が可能となりますので、ぜひご活用ください。

# 実現するもの
今回は、Excelシートにスキャン情報のリストを入力し、ボタン一つで、スキャン情報を一括登録する仕組みを作成します。
なお、スキャン情報の登録には事前にドメインの登録が必要ですが、そちらも一緒に実行されます。

以降はExcelシートのサンプルを使ってご説明します。

## スキャン情報の入力

登録するスキャン情報を「ドメインリスト」シートに入力します。

A列～J列、N列～W列には、AeyeScanにおいて新規スキャン作成時に設定する情報を入力します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/9029b2a2-22ac-95dc-bac9-c4ffd2a4e38a.png)

それぞれの入力項目は、AeyeScanのスキャン新規作成画面での入力項目と一致しています。

## APIキーの設定
APIを実行するためのAPIキーを「設定」シートの「■APIトークン」欄に設定します。
なお、APIキーの作成方法は[こちら](https://qiita.com/AeyeScan/items/b30d341da28130bc8f7a#api%E3%82%AD%E3%83%BC%E4%BD%9C%E6%88%90)をご確認ください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/6966cb1a-2f7a-c175-5b5e-4cf706c25221.png)



## スキャン情報の登録実行

入力が終わったら、Excel内の「実行」ボタンをクリックしてスキャン情報の一括登録を行います。

以下の通り、入力したスキャン情報がAeyeScanに登録されました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/914cfb2d-01c1-b0d8-6d99-78dc45cad856.png)


なお、今回作成したExcelファイルは、以下からダウンロード可能です。

https://drive.google.com/file/d/14yXSPH6J6QlFdNUd-Tn_uRHZFnSw1qDn/view?usp=sharing

:::note warn
外部から取得したマクロファイルは、そのまま開くと危険なマクロと判断されマクロの実行がブロックされます。
そのため、ファイルが正しいことを確認の上、ファイルをダウンロード後ファイルのプロパティからセキュリティ設定を許可してご利用ください。
![VBAセキュリティ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/dcc5c8d3-897e-91f4-71c8-b26070f70169.png)

:::

# 作成のポイント

今回作成したVBAのうち、ポイントとなる技術要素をご紹介します。

## 【ポイント①】HTTP通信によるドメイン登録

API実行のためVBAからHTTP通信を行う必要があり、その実装方法をご紹介します。

### HTTP通信の実装
VBAからHTTP通信を行う場合は、「ServerXMLHTTP」というライブラリを利用します。
以下のコードでは、AeyeScanの「スキャン情報のリストを取得」のAPIを実行しています。

```
'HTTPリクエスト生成
Dim xml_obj: Set xml_obj = CreateObject("MSXML2.ServerXMLHTTP")
xml_obj.Open "GET", "https://api.aeyescan.com/api/v1/scan/"

'HTTPヘッダーを設定
xml_obj.setRequestHeader "X-AEYE-API-KEY", "XXXXXXXXXXXXXXXX"
xml_obj.setRequestHeader "X-AEYE-API-TOKEN", "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
xml_obj.setRequestHeader "Content-Type", "application/json"

'HTTPリクエスト送信
xml_obj.send()

'レスポンスからstatusを取得
Set Parse = JsonConverter.ParseJson(xml_obj.responseText)
status = Parse("status")
```

簡単に解説します。
まず、Openメソッドで、リクエストのメソッドとURLを指定します。
```
xml_obj.Open "GET", "https://api.aeyescan.com/api/v1/scan/"
```
次に、setRequestHeaderメソッドにて、必要なHTTPヘッダを設定します。
今回の場合、AeyeScanのAPIの実行に必要なAPI_KEYとAPI_TOKENを設定します。
また、JSON形式のリクエストとなるため「Content-Type」を指定します。
```
xml_obj.setRequestHeader "X-AEYE-API-KEY", "XXXXXXXXXXXXXXXX"
xml_obj.setRequestHeader "X-AEYE-API-TOKEN", "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
xml_obj.setRequestHeader "Content-Type", "application/json"
```

最後にリクエストを送信します。
```
xml_obj.send()
```
なお、レスポンスの内容は、responseTextに格納されます。

### ドメイン情報を新規作成するAPIのドキュメントを確認

HTTP通信の実装方法を確認できたので、[ドメイン登録を行うAPIのドキュメント](https://aeyescan.com/api-doc.html?_=3161126543561#tag/DomainInfo/operation/registerScan)を確認します。
ドメイン登録に使用するAPIは「ドメイン情報を新規作成」のAPIになります。
また、必要なパラメータは「url」で「ドメインのURL表現」を指定する必要があることがわかります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/02ecc1f2-17be-4633-1740-1edbda0a08be.png)

### ドメイン登録の実装
ドメイン登録を行う処理を実装します。

まずは、HTTPリクエストの生成です。
APIのメソッドとURLを指定します。

```
'HTTPリクエスト生成
Dim xml_obj: Set xml_obj = CreateObject("MSXML2.ServerXMLHTTP")
xml_obj.Open "POST", "https://api.aeyescan.com/api/v1/domain/"
```

HTTPヘッダの設定は、先ほど説明した通りとなるので割愛します。

次に、リクエストの送信となりますが、その前にAPIに渡すパラメータ（url）を生成します。
AeyeScanのAPIでは、JSONパラメータを渡す必要があるので、
連想配列（Dictionary）を作成して以下のように対象サイトのURLを指定します。

```
Set param = New Dictionary
param.Add "url", "http://demosite1.aeyescan.work:3333/" '対象サイトのURL
```

最後にリクエストを送信する際に、JSON形式に変換してsendメソッドに渡します。
```
'HTTPリクエスト送信
xml_obj.send JsonConverter.ConvertToJson(param)
```

以上がドメイン登録処理の実装になります。

実際には、大量のドメインリストから登録を行いますので、ループ処理などで
ドメイン登録処理を繰り返すように実装しています。


## 【ポイント②】JSONパラメータの入れ子によるスキャン作成
ポイント①にて、JSONパラメータの生成方法についてお伝えしましたが、
実行するAPIによっては、設定内容が多くパラメータが入れ子になっているケースがあります。
ここでは、入れ子になった場合の実装方法及び、スキャン作成のAPIをどのように実装するかをご紹介します。

### スキャン情報を新規作成するAPIのドキュメントを確認
実装を行う前に、[スキャン作成を行うAPIのドキュメント](https://aeyescan.com/api-doc.html?_=3161126543561#tag/ScanInfo/operation/createScan)を確認します。
スキャン作成に使用するAPIは「スキャン情報を新規作成」のAPIになります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/89c8700a-24d2-a40c-a394-42706cfdbad9.png)


また、JSONパラメータの入れ子になっている例としては、通常ログイン設定の認証情報（appCredential）のパラメータが配列（Array）形式で入れ子になっていることがわかります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/029c2bf6-06d2-8805-e6ee-44fe6ce4d2be.png)

### スキャン作成の実装
スキャン作成を行う処理を実装します。

まずは、HTTPリクエストの生成です。
APIのメソッドとURLを指定します。

```
'HTTPリクエスト生成
Dim xml_obj: Set xml_obj = CreateObject("MSXML2.ServerXMLHTTP")
xml_obj.Open "POST", "https://api.aeyescan.com/api/v1/scan/"
```

HTTPヘッダの設定は、前回説明した通りです。

次に、APIに渡すJSONパラメータを生成します。

ポイント①にて説明した通り、シンプルなパラメータの場合は以下のように設定していきます。

```
'JSONデータ作成
Set param = New Dictionary
param.Add "scanName", [対象サイトのドメイン]
param.Add "domainId", [ドメイン登録で登録したドメインID]
param.Add "topPath", [エクセルから取得したトップURLのPath]
param.Add "maxPages", [エクセルから取得した最大画面数]
param.Add "ruleset", [エクセルから取得したスキャンルール]
：
```

入れ子のパラメータの場合はこちらの方法で行います。
以下は、通常ログイン設定の認証情報（appCredential）を設定する場合の例となります。

認証情報に設定する連想配列を生成したあと、元のJSONパラメータに連想配列をセットします。

```
'認証情報の生成
Set appCredential_JsonItem = New Dictionary
appCredential_JsonItem.Add "loginId1", [エクセルから取得した対象サイトのログインID]
appCredential_JsonItem.Add "password", [エクセルから取得した対象サイトのパスワード]

'認証情報のセット
param.Add "appCredential", New Collection  '通常ログイン設定
param("appCredential").Add appCredential_JsonItem
```

最後にリクエストを送信する際に、JSON形式に変換してsendメソッドに渡します。
```
'HTTPリクエスト送信
xml_obj.send JsonConverter.ConvertToJson(param)
```

以上がスキャン作成処理の実装になります。


# 利用上の注意
今回ご紹介したExcelシートの内容やVBAコードについては、自由に編集しご利用ください。ただし、無償無保証のため不明点の質問やカスタマイズについてのサポートはできません。
コードの改善、不具合については、是非ご連絡ください。

# おわりに
VBAのHTTP通信を利用して、AeyeScanにスキャン情報の一括登録を行う仕組みをご紹介しました。
今回ご紹介した方法は、ドメイン登録やスキャン作成以外のAPIでも応用可能ですので、是非ご活用ください。

# 参考文献
【VBScript】ServerXMLHTTPでWebAPIにアクセスする
https://qiita.com/aratana_ogawa/items/609953a85d713759610e

EXCEL(VBA)から、JSONデータをHTTP送信してみよう。
https://spirits.appirits.com/doruby/8717/

AeyeScanのトライアル、脆弱性診断の自動化のご相談は[こちら](https://www.aeyescan.jp/)
[![2022-155641.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2422105/dd3f69d5-879a-ed11-d6ac-353a85523c43.png)](https://www.aeyescan.jp)