catch-img

PAシリーズとAPIの活用 ~APIとは?~

こんにちは。

セキュリティ製品を担当しているSEの五十嵐と申します。

本ブログを通して製品の便利な機能をご紹介したり、運用を楽にするTipsをお届けさせていただきます。


今回はPaloalto社製のFWである PAシリーズ を題材に、APIに触れる内容です。

※以下の方々におすすめです。 

  • これまでAPIに触れたことが無い方
  • これからAPIを学びたい方
  • PAシリーズを利用している方

目次[非表示]

  1. 1.PAシリーズとAPIの必要性
  2. 2.APIのユースケース
  3. 3.APIを試してみよう
    1. 3.1.APIの例
    2. 3.2.Web GUIの例
    3. 3.3.(応用)スクリプト化
    4. 3.4.PAシリーズの場合
      1. 3.4.1.SSH、APIの出力を比較
  4. 4.APIを使用するときに必要なツール
  5. 5.PAシリーズで試してみよう
    1. 5.1.APIキーを取得しよう
    2. 5.2.APIでステータスを取得しよう
  6. 6.APIの探し方
  7. 7.おわりに



PAシリーズとAPIの必要性


これまで、何か機能を調べてみたらAPIを使わないと取得できないとわかってゲンナリ・・・  
なんて経験、ありませんか?
突然使えと言われても困ってしまいますよね。

PAシリーズの場合ですが、こちらの製品はAPIのみで提供される機能はありません。

Web GUIとSSHが充実していますので、これらを用いて各機能を設定可能になっています。
例えば導入時やトラブルシューティング時にいきなりAPIを求めることはございませんのでご安心ください。

もちろんAPIをうまく活用いただいた方が運用が楽になりますので、ぜひこの記事の続きも読んでみてください。


APIのユースケース


PAシリーズのAPIガイドでは、次のようなシナリオを自動化する場合にAPIが有効と説明されています。

  • ファイアウォール設定の作成、更新、および変更
  • コマンド操作(システムの再起動や設定の検証など)
  • レポートの取得
  • ユーザーIDのユーザー管理
  • 動的オブジェクトの更新  

PAシリーズに限らず、APIを使うということは運用者の負荷軽減完全自動化が目的になることが多いかと思います。

具体的に何を行うかは自身のタスクやアイデア次第ですが、どんな製品でも以下のシナリオは存在するのではないでしょうか。

  • サーバーCPUやメモリなどのリソース使用量をモニタリング、グラフの作成 
  • 組織変更などに対応するバッチ処理(ある程度はCSVでバッチ処理できるようになってると思います)
  • これらの内容を製品をまたいで一括管理する



APIを試してみよう


「REST API」と書かれている製品なら、制御通信の手段はWeb(HTTPS)で提供されるため、簡単な操作であればChromeやInternetExplorerなどのWebブラウザでも利用できます。


APIの例

他社様のサービスになりますが、郵便番号検索をREST形式で行えるサイトがあります。

利用イメージは以下画像の用に、URLの中に検索したい郵便番号を含めてアクセスするだけです。

これだけ?と思われるかもしれませんがこちらはRESTで公開されているサービスです。  
つまり皆さんもこれでREST APIを活用したエンジニアになれたわけですね。


Web GUIの例

APIを使わない場合の例として、もう一つサイトを挙げましょう。  
情報元、日本郵便株式会社の郵便番号検索です。

こちらの場合はWebに一度アクセスして、フォームに検索したい郵便番号を含めてボタンを押して検索するサービスです。

Web GUIの方なら入力フォームも用意されているので誰でもすぐに利用できそうです。

しかし、例えば郵便番号を一人で大量に検索する必要があるとしたら、APIを使って一度に検索した方が早くデータをまとめられるかもしれません。


(応用)スクリプト化

どんな情報を集めてどのように整形したいのかにより作りこむ量が変わりますが、とりあえず検索結果だけテキストを残せるようにしてみましょう。

  • スクリプト
#!/usr/bin/bash
for CODE in 1007024 1007025 1007026
do
echo $CODE
curl "https://zip-cloud.appspot.com/api/search?zipcode=${CODE}" | grep address
done
  • 実行中
[admin@py3 palo]$ ./postcode.sh > postcode.log
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   355  100   355    0     0    882      0 --:--:-- --:--:-- --:--:--   883
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   355  100   355    0     0    887      0 --:--:-- --:--:-- --:--:--   889
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   355  100   355    0     0    870      0 --:--:-- --:--:-- --:--:--   870
  • 保存されたテキストファイル
1007024
                        "address1": "東京都",
                        "address2": "千代田区",
                        "address3": "丸の内JPタワー 24階",
1007025
                        "address1": "東京都",
                        "address2": "千代田区",
                        "address3": "丸の内JPタワー 25階",
1007026
                        "address1": "東京都",
                        "address2": "千代田区",
                        "address3": "丸の内JPタワー 26階",

curlを使い、決められたURLにアクセスするスクリプトです。

これを作りこんでいく話もしたいのですが、そこそこ長くなりますのでまた別途まとめさせていただきますね。


PAシリーズの場合

PAシリーズもAPIが用意されており、前述の通りAPI限定機能は無いためWebGUIやSSHと使い分けて運用いただけます。

手段が豊富に用意されていますので、使い分けの参考になるようにポイントを記載しておきます。

手段
メリット
デメリット
GUI
臨機応変に好きな情報にアクセスできる
目的のページを見るために数回クリックが必要
SSH
目的の情報に合わせてコマンドを使い分けでき、応答も速い
1行で複数の情報(CPU,メモリ使用量など)がまとまっていたり、体裁は様々
API
必要な情報を抜き取りやすく高速
フォーマットが決まっている分、データの集計や加工が楽
都度URLを手で入力するのは非常に困難


それぞれ有効な場面がありますので、APIがあればGUIが不要になるわけでもありません。

APIを無理に使おうとして手間が増え、業務が滞ってしまわないよう(特に扱い始めは)注意してください。マニュアル化できているようなタスクが目の付け所だと思います。


SSH、APIの出力を比較

どちらの手段でもPAで管理しているセッション情報を取得することができますので、データの見え方がどのように変わるのか見てみましょう。

  • API

https://<FWのIPアドレス>/api/?type=op&cmd=<show><session><info></info></session></show>&key=<APIキー>

<response status="success">
    <result>
        <tmo-sctpshutdown>30</tmo-sctpshutdown>
        <tcp-nonsyn-rej>True</tcp-nonsyn-rej>
        <tmo-tcpinit>5</tmo-tcpinit>
        <tmo-tcp>3600</tmo-tcp>
        <pps>4</pps>
        <tmo-tcp-delayed-ack>250</tmo-tcp-delayed-ack>
        ~ 省略 ~
    </result>
</response>

PAシリーズの場合、URLで検索する形式は郵便番号のAPIと同じですが、このサンプルの通り応答時のテキスト形式はXMLです。APIキーは認証に関する情報で、この記事の後半で説明します。

  • SSH

show session info

target-dp:                                       *.dp0
--------------------------------------------------------------------------------
Number of sessions supported:                    262142
Number of allocated sessions:                    23
Number of active TCP sessions:                   15
Number of active UDP sessions:                   6
Number of active ICMP sessions:                  1
Number of active GTPc sessions:                  0
Number of active GTPu sessions:                  0
Number of pending GTPu sessions:                 0
Number of active BCAST sessions:                 0
Number of active MCAST sessions:                 0



APIを使用するときに必要なツール


HTTPSによる通信ですので、様々なクライアントでAPIを使用できます

  • Webブラウザ
  • 各種Webリクエストを行えるツール
    • curl
    • PowerShell
    • Postman
    • その他
  • 自身で開発したプログラム



PAシリーズで試してみよう


APIの利用には、APIキーをURLに含めてリクエストを行います。  
都度ログインを行う手間は必要ありません。


APIキーを取得しよう

APIキーを取得するためのURLの構文と、アクセスした結果を記載します。

https://<FWのIPアドレス>/api/?type=keygen&user=<ユーザ名>&password=<パスワード>  
例)https://192.168.1.1/api?type=keygen&user=admin&password=password

<response status="success">
    <result>
        <key>
            UQT09LUFRP12345678901R09KV
        </key>
    </result>
</response>

長い文字列がkeyとして返されました。  
以降、この文字列をURLに含めると認証済み機器として扱われるようになります。


APIでステータスを取得しよう

APIキーを記録したら、いくつかのAPIを実際に使用してみましょう。  
IPアドレスやAPIキー(key=の後の文字列)は、操作しているデバイスに合わせて変更してください。


  • URLカテゴリ確認(www.google.com)

https://192.168.1.1/api/?type=op&cmd=<test><url>www.google.com</url></test>&key=UQT09LUFRP12345678901R09KV

<response cmd="status" status="success">
    <result>
        www.google.com search-engines (Base db) expires in 0 seconds www.google.com search-engines (Cloud db)
    </result>
</response>


  • コミット

https://192.168.1.1/api/?type=commit&action=set&cmd=<commit></commit>&key=UQT09LUFRP12345678901R09KV

<response status="success" code="19">
    <msg>There are no changes to commit.</msg>
</response>


  • 前日に多く使用されたアプリケーション(top-applications)

https://192.168.1.1/api/?type=report&async=yes&reporttype=predefined&reportname=top-applications&key=UQT09LUFRP12345678901R09KV

<report reportname="top-applications" logtype="appstat">
    <result name="Top applications" logtype="appstat" start="2020/03/09 00:00:00" start-epoch="1583679600" end="2020/03/09 23:59:59" end-epoch="1583765999" generated-at="2020/03/10 02:02:06" generated-at-epoch="1583773326" range="Monday, March 09, 2020">
        <entry>
            <name>web-browsing</name>
            <nbytes>77326315</nbytes>
            <nsess>22819</nsess>
        </entry>
        <entry>
            <name>ping</name>
            <nbytes>763042</nbytes>
            <nsess>7767</nsess>
        </entry>
        <entry>
            <name>dns</name>
            <nbytes>977278</nbytes>
            <nsess>1942</nsess>
        </entry>
        <entry>
            <name>paloalto-wildfire-cloud</name>
            <nbytes>6946895</nbytes>
            <nsess>713</nsess>
        </entry>
(一部省略)
    </result>
</report>


  • バックアップ(コンフィグファイル)の取得

https://192.168.1.1/api/?type=config&action=show&key=UQT09LUFRP12345678901R09KV

<response status="success">
    <result>
        <config urldb="paloaltonetworks" version="8.1.0">
            <mgt-config>
                <users>
                    <entry name="admin">
                        <phash>xxxxxxxxx</phash>
                        <permissions>
                            <role-based>
                                <superuser>yes</superuser>
                            </role-based>
                        </permissions>
                    </entry>
                    <entry name="vsys1">
                        <permissions>
                            <role-based>
                                <vsysadmin>
                                    <entry name="localhost.localdomain">
                                        <vsys>
                                        <member>vsys1</member>
                                        </vsys>
                                    </entry>
                                </vsysadmin>
                            </role-based>
                        </permissions>
                        <phash>xxxxxxxxxx</phash>
                    </entry>
                </users>
            </mgt-config>
            <shared></shared>
            <devices>
                <entry name="localhost.localdomain">
                    <network>
                        <interface>
                            <ethernet>
                                <entry name="ethernet1/1">
                                    <layer3>
                                        <ipv6>
                                            <neighbor-discovery>
                                                <router-advertisement>
                                                    <enable>no</enable>
                                                </router-advertisement>
                                            </neighbor-discovery>
                                        </ipv6>
                                        <ndp-proxy>
                                            <enabled>no</enabled>
                                        </ndp-proxy>
                                        <ip>
                                            <entry name="192.168.1.254/24"/>
                                        </ip>
                                        <lldp>
                                            <enable>no</enable>
                                        </lldp>
                                    </layer3>
                                </entry>
                            </ethernet>
                        </interface>
(一部省略)



APIの探し方


APIを使えるようになったところで、次はAPIの探し方について紹介します  

  • API Guide

PAN-OS® and Panorama™ API Guide
こちらはメーカードキュメントです  
後述する探し方もこのガイドに記載されていますが、基本的な記述ルールの他、サンプルもガイドの中で紹介されています

  • API ブラウザ

http://<FWのIPアドレス>/api  
PAシリーズの Web GUI を介してAPIを探すことができます  

  • Web GUI デバッグ

http://<FWのIPアドレス>/debug  
Web GUI と並行して利用します  
このページを開いた後に Web GUI を操作すると、対応するAPIが表示されます  



おわりに


いかがだったでしょうか。  
なぜ世の中でAPIが使用されているのか、APIとは何者なのか、簡単なサンプルを含めてふんわりと説明させていただきました。

いきなり大々的に自動化を進めるのはハードルが高いですが、API自体はそんなに怖くないなと思ってもらえたら嬉しいです。

今回紹介させていただいた通り、プログラミングに深く触れなくてもAPIは使用できます。  
ですので、今回挙げたサンプルなどから使えそうな題材が思いついたら是非チャレンジしてみてください。

次回は、実際に活用できるプログラムに落とし込んだ内容をご紹介したいと思います。


Koya Igarashi

Koya Igarashi

セキュリティ担当のセールスエンジニア その他、ネットワークやIP電話、ビデオ会議の製品も好きです 使用マイク オーディオテクニカ AT810X マランツプロ MPM-1000 ゼンハイザー SP20