5.4REST API セキュリティ

ネットワーク自動化が進むほど、API 資格情報は装置の特権パスワードと同等かそれ以上に強力になります。Catalyst Center の Intent API を叩けるトークンは、数百台の設定変更を1回のリクエストで実行できるからです。ENCOR ではこの領域を「API の使い方」ではなく、「このスクリプトのどこが危険か」「なぜ本番で 401 や 429 が出るのか」「証明書検証を無効化する verify=False は何を壊すか」という診断・是正として問われます。自動化の利便性と、資格情報・権限・流量の統制を両立させる判断が主題です。

5.4.1認証と認可（トークンと OAuth）

• 多くのコントローラ API は二段構えを取る：まず /dna/system/api/v1/auth/token のようなトークン発行エンドポイントへ Basic 認証でユーザ名/パスワードを送り、返ってきたトークンを以降のリクエストの X-Auth-Token（または Authorization: Bearer ...）ヘッダに載せる。トークンには有効期限があり、期限切れは 401 Unauthorized として現れる——毎回パスワードを送らずに済むのが利点である。
• OAuth 2.0 は、第三者アプリにパスワードを渡さずに限定的な権限を委譲するための標準。アクセストークンにはスコープ（許可される操作範囲）と短い有効期限を設定し、リフレッシュトークンで更新する。漏洩時の被害範囲がスコープと期限に限定されるのが本質的な利点で、「共有アカウントのパスワードをスクリプトに埋める」運用との決定的な差である。
• HTTP ステータスは診断の起点になる：401＝認証失敗/トークン期限切れ（再認証が必要）、403＝認証は成功したが権限不足（ロール/スコープの問題であり再認証しても解決しない）、404＝リソース/パス誤り、429＝レート制限超過、5xx＝サーバ側。401 と 403 の切り分けを誤ると、権限問題をトークン再取得で延々リトライすることになる。

5.4.2通信路の保護と資格情報の扱い

• API 通信は必ず HTTPS/TLS で行う。HTTP ではトークンや設定内容が平文で流れ、盗聴されたトークンはそのまま再利用（リプレイ）できてしまう。ラボでよく使われる verify=False（証明書検証の無効化）は、暗号化は残るが相手が本物かの検証を捨てるため、中間者攻撃（MITM）に対して無防備になる。正しい是正は検証の無効化ではなく、社内CA証明書を信頼ストアに追加することである。
• 資格情報をソースコードやリポジトリに埋め込まない。環境変数・シークレットストア（Vault 等）・CI のシークレット機能から実行時に読み込む。誤って push した資格情報は履歴に残るため、ローテーション（無効化と再発行）まで行わないと是正にならない。ログ出力にトークンやパスワードが混入しないようマスクすることも必須である。
• 最小権限を守る：自動化用アカウントには必要な API 操作だけを許すロールを与える。監視用スクリプトが読み取り専用ロールで足りるなら、設定変更権限を持たせてはならない。加えてアカウントを用途ごとに分離すれば、アカウンティングログから「どの自動化が何を変えたか」を追跡でき、漏洩時の影響範囲も限定できる。

5.4.3レート制限と堅牢な呼び出し

• レート制限は、コントローラを過負荷から守るために単位時間あたりのリクエスト数を制限する仕組み。超過すると 429 Too Many Requests が返り、多くの実装は Retry-After ヘッダで待機すべき秒数を示す。429 を無視して即座にリトライすると負荷を増やして状況を悪化させるため、指数バックオフ（待ち時間を段階的に延ばす）で再試行するのが正しい。
• 大量デバイスを扱うスクリプトは、1台ずつ逐次に叩くのではなく、フィルタやページング（limit/offset）を使って必要な範囲だけ取得し、可能ならバッチ API を使う。取得済みデータをキャッシュして無駄な再取得を避けることも、レート制限とコントローラ負荷の両方に効く。
• 冪等性と検証も安全性の一部：変更系（POST/PUT/DELETE）は再実行時の影響を考え、失敗時に中途半端な状態が残らないようにする。実運用前には読み取り専用の呼び出しで対象を確認し、変更は限定範囲から段階的に広げる。エラー時はステータスコードとレスポンスボディの両方を記録し、原因を推測ではなく応答から特定する。

あなたはチームが書いた Catalyst Center 用の在庫収集スクリプトをレビューしています。処理は、スクリプト冒頭に USER = "admin" と PASS = "Cisco123" を定数として書き、requests.post(url, auth=(USER, PASS), verify=False) でトークンを取得し、そのトークンで全 500 台のデバイスを1台ずつ GET /dna/intent/api/v1/network-device/{id} で取得、エラーが返っても即座に同じ要求を再送する、というものです。本番投入後、途中から大量の 429 が返り、さらに運用ログにトークンがそのまま出力されていることが判明しました。ここで「コントローラの性能不足だからリクエスト間隔を固定 1 秒にする」という対処は表層的です。まず 429 はレート制限超過の明示的シグナルであり、正しい対処は Retry-After ヘッダに従い指数バックオフでリトライすること、そして根本的には1台ずつではなく、フィルタとページング（limit/offset）で必要な範囲をまとめて取得するか、バッチ API を使って呼び出し回数そのものを減らすことです。即時リトライは負荷を増幅し、制限をさらに踏む悪循環を生みます。次に verify=False は証明書検証を無効化するもので、通信自体は暗号化されるものの相手が本物のコントローラかを検証しないため、経路上の攻撃者が偽サーバとしてトークンと管理者資格情報を丸ごと収集できます。是正は検証の無効化ではなく、社内 CA の証明書を信頼ストアに登録して verify を有効に戻すことです。三点目のハードコードされた資格情報は、リポジトリに入った時点で履歴から消しても漏洩は取り消せないため、該当アカウントのパスワード/トークンをローテーションした上で、環境変数やシークレットストアから実行時に読み込む形へ変更します。同時に、この収集スクリプトは読み取りしか行わないのですから、admin（設定変更権限を持つ）ではなく読み取り専用ロールの専用アカウントに切り替えるべきで、これが最小権限の実践です。最後にログのマスク処理を入れてトークンが平文で残らないようにします。この5つの是正——バックオフ／呼び出し削減／証明書検証の回復／資格情報の外出しとローテーション／最小権限の専用アカウント——は、どれも「API を動かす」ためではなく「壊れ方と漏れ方を設計する」ための判断です。

5.4.4この節のまとめ

• HTTPS/TLS を必須にし、証明書検証を無効化しない（verify=False は暗号化を残したまま MITM に無防備になる）。是正は社内CAの信頼登録
• 認証はトークン／OAuth 2.0（スコープと短い有効期限で漏洩時の被害を限定）。401＝再認証・403＝権限是正・429＝バックオフと切り分ける
• 資格情報はコードに埋めず実行時に読み込み、漏洩時はローテーション。自動化アカウントは最小権限（読み取り用途に変更権限を与えない）で用途ごとに分離する