把握していないAPIは五つの保安の空白を作ります
運用中のAPIをすべて把握していなければ、組織は何を守るべきかという前提から誤ります。文書にないテスト用API、以前のVersion、内部連携、一時的なEndpointが動き続けていても、保安点検・パッチ・観測・事故対応・廃棄の対象からは抜け落ちることがあります。OWASP API9:2023は、こうしたInventoryとRetirementの管理の不在が古いAPI Versionを放置し、機微情報の露出やシステム侵害の危険を高めると説明します。[1] NISTも、正確なInventoryがなければ組織のAPI全体を一貫して守ることは難しいと見ています。とくに文書化されていない、または正常な点検手続きを経ていないAPIをShadow APIとし、置き換えられたが完全に除去されていないAPIをZombieまたはDeprecated APIとして説明します。[2]
第一に、保護範囲から抜け落ちます。方針と点検はたいてい把握済みの資産を基準に設計されます。Inventoryにないアプリケーションは、適用対象の選定、変更の点検、脆弱性への対応、観測の範囲から漏れやすくなります。とくに内部・Debug・Testの目的で作られたEndpointが別の経路で運用環境に残っていると、正式なAPIより弱い手続きしか経ていない場合があります。[2]
第二に、古いVersionが生き残ります。新しいVersionを配布したからといって以前のVersionが自動的に消えるわけではありません。既存のConsumerが残っている、あるいは廃棄の責任者がいなければ、以前のEndpointが呼ばれ続けます。古いVersionは現在の開発・点検の流れから外れ、Patchと方針の改善を受けにくくなります。[1]
第三に、どのデータがどこへ流れるかがわからなくなります。API HostとPathだけを把握しても十分ではありません。どのデータがやり取りされ、外部の組織や第三者サービスへ渡るのか、その流れがいまも必要かまで把握する必要があります。OWASPは第三者APIと交換するデータ、役割、機微度、業務上の必要性をInventoryに含めるよう勧めます。[1]
第四に、事故が起きても責任者を見つけにくくなります。APIは存在するのに現在の責任者がいなければ、誰が遮断・修正・廃棄を決めるのかが不明確になります。Repositoryの過去の作成者と現在の運用責任者は別人であることがあります。チーム名だけが記録されていても、そのチームが責任を受諾していなければOwnerが指定されたとは見なせません。
第五に、廃棄したはずのAPIが再び危険になります。文書から削除した、あるいは最近Trafficがないという理由だけで廃棄が終わったわけではありません。DNS、Load Balancer、Runtime Route、Serverless Function、Message Consumer、配布Manifestのうち一つでも残っていれば再び呼ばれます。廃棄は「見えない」ではなく、もはや到達も実行もできないというEvidenceで確認します。
API Inventoryは四層を照合します
API InventoryはURLを一度集めて作った表計算ではありません。何を作ると宣言したか、実際に何が配布されたか、Runtimeで何が観測されたか、誰がどの目的で責任を負うかを継続して照合する運用Registerでなければなりません。NISTも、宣言された仕様とLive TrafficをReconciliationし、「配布されているもの」と「配布されるべきもの」の差を見つけるよう勧めます。[2] 各層は異なる問いに答えます。
四層のEvidenceは一か所に集まり、正規化と相関の確認を経ます。そこで安定したAPI Identityを作り、EvidenceとConfidenceを併せて残します。その結果がAPI Registerです。Registerは各APIをManaged、Shadow候補、Orphan候補、Zombie候補に分け、Manage・Migrate・Retire・Verifyのいずれかへ送ります。
どの一層も単独で完全なSource of Truthにはなれません。OpenAPI文書はHTTP APIの宣言を記述しますが、実際の配布の有無や文書にないEndpointの不在までは証明しません。2026年8月21日時点の最新の公式OpenAPI Versionは3.2.0です。[3] 同様にGateway Logは、そのGatewayを通ったTrafficだけを示します。別のGateway、直接露出したOrigin、内部RPC、Message Broker、観測期間に呼ばれなかったEndpoint、Telemetryが欠けた経路は見えません。したがってScannerやDiscovery製品の結果も一つのObservation Sourceとして扱います。NISTが仕様・Runtime・所有権・Live Trafficを併せて照合するよう求めている点から見て、単一の道具が100%完全なAPI Inventoryを作ると考えるのは妥当でないというのが本稿の実務的な結論です。[2]
層 | 答えるべき問い | 主なEvidence |
|---|---|---|
| Declared | 何を作り運用すると決めたか | OpenAPI・AsyncAPI・.proto・GraphQL Schema・WSDL、Repository、Catalog、Route定義、Code |
| Deployed | 実環境に何が配布され到達可能か | Gateway Route、Load Balancer、DNS、Kubernetes、Service Mesh、Serverless、Runtime Route、Broker・Topic・Queueの設定 |
| Observed | 実際にどの呼び出しやメッセージが観測されたか | Access Log、Trace、Network Observation、Runtime Log、Broker Metric、First Seen、Last Seen |
| Governed | 誰がなぜ責任を負い、どの状態で管理するか | Owner、Business Purpose、Data Sensitivity、Authentication Category、Exposure、Version、Lifecycle、Retirement |
サービスの前段でリクエストを分類・防御 — リクエストと遮断記録から防御ルールを調整し、証明書とアクセス制御も管理します。
REST APIだけをInventoryに入れてはなりません
APIをHTTP MethodとURL Pathだけで正規化すると、REST以外のInterfaceが抜けます。Interfaceの種類ごとにDeclared Evidenceと推奨されるInventoryの単位が異なります。
HTTP・RESTはOpenAPI、Route Code、Framework AnnotationがDeclared Evidenceで、Host ScopeとMethod、正規化したPath、VersionがInventoryの単位です。GraphQLはSchema、SDL、Introspection SnapshotがEvidenceで、EndpointとOperation Type、重要なField・Mutationが単位です。gRPCはProtocol Bufferの.protoがEvidenceで、Fully Qualified ServiceとRPC Method、Versionが単位です。Message-driven APIはAsyncAPI、Broker Config、Producer・Consumer CodeがEvidenceで、Broker ScopeとChannel・Topic・Queue、Operation、Message Typeが単位です。SOAPはWSDLとService ConfigurationがEvidenceで、ServiceとOperation、Versionが単位です。WebSocketはAsyncAPIまたは別のContractがEvidenceで、Connection EndpointとMessage Operationが単位です。
OpenAPIはHTTP APIのための仕様で、Message-driven APIにはAsyncAPIのような別の形式を使います。gRPCは一般に.protoファイルへServiceとRPC Methodを宣言します。[3] この差は単なる形式の問題ではありません。GraphQLは一つのURLの後ろに多数のQueryとMutationが存在します。Message-drivenのシステムはHTTP Endpointなしでも機微なデータを扱います。Inventoryの単位を技術の方式に合わせて定めなければ、「Hostは把握しているが実際のOperationは把握していない」状態になります。
四層の不一致は何を意味するのか
層のあいだの不一致は、それ自体が結論ではなく調査の出発点です。下の表の三列目は、実務で最も頻繁に出る性急な判定を書き留めたものです。
ObservedとLifecycleは必ず別のフィールドでなければなりません。observed_stateはactive、dormant、unseen、unknownのいずれかです。lifecycle_stateはactive、deprecated、retiring、retiredのいずれかです。最近呼び出しがないことは観測の状態にすぎず、廃棄の意思決定や技術的な除去を証明しません。
発見された状態 | 一次的な読み | すぐに下してはならない結論 | 次の行動 |
|---|---|---|---|
| 四層が一致 | 管理中のAPIである可能性が高い | 安全だという意味ではない | 現在のOwner・Lifecycle・Evidenceを再確認 |
| DeployedまたはObservedにあるがDeclared・Governedにない | Shadow候補 | 発見と同時に悪性または不正なAPIと断定 | 配布元・目的・Ownerを確認して登録または除去 |
| APIは存在するが責任を受諾したOwnerがいない | Orphan候補 | Repositoryの作成者が現在のOwnerだと断定 | 業務責任者と技術責任者を別々に指定 |
| Deprecated・RetirementのEvidenceがあるのにDeployedまたはObservedに残る | Zombie候補 | 最近のTrafficが少ないという理由だけでZombieと判定 | Consumer・Route・Runtime・廃棄日程を確認 |
| DeclaredにあるがDeployed・Observedにない | 計画中、廃棄済み、文書の古さ、または観測の空白 | Shadowと判定 | 配布履歴と文書の最新性を確認 |
| Deployedにあるが観測されない | Dormant APIまたは観測の空白 | Trafficがないので廃棄済みと判定 | Observation WindowとTelemetry Coverageを検証 |
| 観測されたが配布元を見つけられない | 未知のRouteまたはSource Mappingの失敗 | ログの誤りとして自動的に無視 | DNS・Network・Runtime・Proxyの経路まで遡る |
| GovernedではRetiredなのにDeployedに残る | 廃棄手続きの失敗の可能性 | 呼び出しがないので問題ないと判断 | 到達可能性の除去とConsumer Migrationを確認 |
ShadowとOrphan、Zombieをどう区別するのか
この三つの用語は、Sourceと組織によって範囲が変わります。NISTは、文書化されていない、または正常な開発・点検の手続きを経ていない内部・Debug・Test・Ad hoc APIをRogueまたはShadow APIとして説明します。また、置き換えられたがConsumerの未移行や責任の不在によって完全に除去されていないAPIをZombieまたはDeprecated APIとして説明します。Orphanについては、Reconciliationの勧告にorphaned endpointが列挙されるものの、本稿で検討した当該文書に独立した定義は示されていません。[2] 以下の用語定義は、その説明の上に本稿の実務的な判定基準を重ねたものです。
三つの分類は互いに排他的ではありません。文書にないAPIにOwnerもいなければShadowでありOrphanです。廃棄対象のAPIがOwnerなしで残っていればZombieでありOrphanです。分類は自動削除の命令ではなく、調査を要する運用状態です。
- Shadow API
- Shadow APIとは、DeployedまたはObservedのEvidenceがあるのに承認されたDeclared・Governed Recordと結び付いていないAPIです。古いSpec一つやOwnerの一時的な無応答は判定の根拠になりません。
- Orphan API
- Orphan APIとは、存在するものの、変更・事故対応・廃棄を決める責任者が指定され受諾された状態にないAPIです。過去の作成者の退職や一度の連絡失敗だけで判定しません。
- Zombie API
- Zombie APIとは、Deprecated・Retirement・Replacementの意図が確認されているのに、なお配布され、あるいは到達・呼び出しが可能なAPIです。最近のTrafficが少ないことは判定の根拠になりません。
API Registerの最小Schema
URLだけを保存するRegisterではReconciliationを行えません。少なくとも十のグループのフィールドが要ります。OWASPもHostごとのEnvironment、Network Access、Versionと、第三者サービスの役割・交換データ・機微度をInventoryに含めるよう勧めます。[1] NISTはSpecification、Ownership、Runtime Informationを併せて管理し、Live Trafficと照合することを求めます。[2]
一つのRecordの姿はこうです。api_idがapi:fulfillment:inventory-sync:v1なら、identityには名前inventory-sync、directionはprovided、protocol_styleはgrpc、interface_keyはfulfillment.InventorySyncService、versionはv1が入ります。declaredにはspec_type protobufと.protoファイルのspec_ref、repository_ref、spec_digest、declared_atが入ります。deployedには環境production、exposure internal、runtime_ref、deployed_version、deployment_state running、last_deployed_atが入ります。observedにはservice_mesh_traceやruntime_logのようなobservation_sources、first_seen_at、last_seen_at、observation_window、observation_confidence、observed_stateが入ります。governedにはaccountable_ownerとtechnical_owner、owner_attested_at、business_purpose、business_criticality、data_classification、authentication_category、expected_access、lifecycle_state、deprecation_at、retirement_target、replacement_refが入ります。reconciliationにはstatusとfindings、evidence_refs、checked_at、next_review_atが入り、securityにはrecord_classification、export_policy、credential_material_presentが入ります。
authentication_categoryには認証方式の範疇だけを記します。Token、Secret、Private Key、Cookieの値、Connection StringをRegisterへ複製してはなりません。
グループ | 最小フィールド | 目的 |
|---|---|---|
| Identity | api_id、name、direction、protocol_style、interface_key、version | 異なるSourceのRecordを同じAPIへ結び付ける |
| Declared | spec_type、spec_ref、repository_ref、spec_digest、declared_at | 期待されるContractと変更履歴の確認 |
| Deployed | environment、exposure、runtime_ref、deployed_version、deployment_state、last_deployed_at | 実際に到達可能なRuntimeの把握 |
| Observed | observation_sources、first_seen_at、last_seen_at、observation_window、observation_confidence、observed_state | 何がいつどのSourceで観測されたかの記録 |
| Ownership | accountable_owner、technical_owner、owner_attested_at | 業務責任と技術責任、確認時点の分離 |
| Purpose & Data | business_purpose、business_criticality、data_classification、data_flows | APIの必要性とデータ上の危険の判断 |
| Access Context | authentication_category、expected_access、exposure | Credentialそのものではなく接続方式と想定Caller範囲の記録 |
| Lifecycle | lifecycle_state、deprecation_at、retirement_target、replacement_ref | Versionの入れ替えと廃棄の追跡 |
| Reconciliation | reconciliation_status、findings、evidence_refs、checked_at、next_review_at | 不一致、根拠、後続点検の管理 |
| Register Security | record_classification、export_policy、credential_material_present | Inventory自体の機微度とExportの統制 |
初めてInventoryを作るときに閉じる範囲
初めてAPI Inventoryを作るときは十六の項目で範囲を閉じます。Public・Partner・Internal APIをすべて調査範囲に入れたか。Productionだけでなく、Staging・Test・Preview・Legacyの環境も含めたか。提供するAPIと外部から消費するAPIを両方含めたか。HTTP・RESTだけでなくGraphQL・gRPC・SOAP・WebSocket・Message-driven APIを含めたか。APIをどの単位で識別するかを決めたか。Spec、Repository、Catalog、Route CodeなどのDeclared Sourceを収集したか。DNS、Load Balancer、Kubernetes、Serverless、Runtime RouteなどのDeployed Sourceを収集したか。Log、Trace、Network、BrokerなどのObserved SourceとObservation Windowを記録したか。同一APIのEnvironment・Version・Aliasを正規化したか。業務責任者と技術責任者を分けて指定したか。Business Purpose、Data Sensitivity、Data Flow、Exposureを分類したか。Deprecated・Retiring・Retiredの状態とReplacementを記録したか。Shadow・Orphan・Zombieの候補を自動削除せず調査Queueへ送ったか。Registerの接続権限・Export方針・監査記録を設定したか。Credential MaterialがRegisterに含まれていないことを確認したか。次のReconciliation Triggerと点検の責任者を決めたか。
監視から復旧・改善までつながる運用 — サービス指標とアラートを基準に対応し、変更履歴と事後報告を次の改善につなげます。
変更のたびにRegisterを更新します
Inventoryは初期の調査よりその後の維持のほうが難しいものです。変更が起きたときにRegisterも併せて更新されるようTriggerを定めておきます。
点検の周期をすべてのAPIに同じく適用する理由はありません。外部露出、高いデータ機微度、変更の頻度、業務上の重要度が高いAPIはより速いReconciliationが要ります。逆に変更が少なく隔離されたAPIでも、OwnerとLifecycleのEvidenceが永久に有効なわけではありません。
Trigger | 照合する層 | 自動または手動の確認 |
|---|---|---|
| Spec・Schema・.protoの変更 | Declared ↔ Governed | Version、Owner、Lifecycle、影響範囲 |
| Repository Merge | Declared ↔ Deployed | Routeの追加・削除が配布Manifestと一致するか |
| Deploy・Rollback | Deployed ↔ Declared | 配布Versionと宣言Versionの差 |
| DNS・LB・Gateway・Kubernetes・Serverlessの変更 | Deployed ↔ Governed | 新しい露出経路と承認済みExposureの差 |
| 新しいRuntime Traffic・Traceの観測 | Observed ↔ Declared・Deployed | 未登録のInterfaceまたは想定外のCaller |
| 組織改編・Team Ownershipの変更 | Governed ↔ 全体 | Ownerがいまも責任を受諾しているか |
| Deprecation・Sunset Dateの到来 | Governed ↔ Deployed・Observed | 廃棄対象がなお配布・呼び出しされているか |
| 定期Attestation | 四層すべて | Purpose、Sensitivity、Version、Owner、Evidenceの最新性 |
発見から管理・廃棄までの八段階
第一段階は発見です。新しいAPI候補とともに、発見のSource、時刻、Environment、原Evidenceを保存します。「APIが発見された」と「APIの正体を知っている」は別の状態です。
第二は正規化です。異なるSourceでは同じAPIが違う形で表されます。RESTはMethodと正規化したPath、Host Scopeで、GraphQLはEndpointとOperation Type、重要なFieldで、gRPCはFully Qualified ServiceとMethodで、Message-drivenはBroker ScopeとChannel・Topic・Queue、Operationで揃えます。EnvironmentとVersionはIdentityから分離して比較できるようにします。
第三は相関の確認です。Declared・Deployed・Observed Recordが同じAPIを指すかを結びます。自動照合の結果にはConfidenceを残し、互いに矛盾するEvidenceを黙って上書きしません。
第四はOwnerの割り当てです。業務上の必要性を判断するaccountable_ownerと、実装・運用を担うtechnical_ownerを区別します。現在の責任者がいなければOrphan候補として分類しEscalationします。Ownerがいないという理由だけで即座に削除すると、なお使っているConsumerや業務を止めることになります。
第五は分類です。提供・消費の方向、Public・Partner・InternalのExposure、Business Purpose、Data Classificationと外部のData Flow、Authentication Category、VersionとLifecycle、Shadow・Orphan・Zombie候補かどうかを確認します。
第六は管理または移行の判断です。正常に必要なAPIならRegister、Spec、Owner、観測の範囲へ組み入れます。重複や老朽化したAPIならConsumer Migration、Replacement、Retirement Planを作ります。
第七は廃棄の実行です。廃棄は文書から消す作業ではありません。呼び出しConsumerの移行、RouteとDNSの除去、Runtime Resourceの停止、Credential・権限・連携関係の廃棄、Spec・Catalog・運用文書の更新、観測Sourceでの想定外の呼び出しの確認、Rollback・例外計画の終了を併せて確認します。
第八は廃棄の検証です。last_seenだけで廃棄の完了を宣言しません。Deployed Evidenceから到達可能性が取り除かれ、Governed RecordがRetiredとして承認され、必要なConsumer Migrationが終わったというEvidenceが要ります。
API Inventory自体も機微な資産です
よくできたAPI Inventoryは攻撃者にも有用です。内部のHostとEnvironment、Version、Serviceの名前、Owner、認証の範疇、Data Classification、外部のData Flow、Retirementの状態が集まれば、組織の攻撃面を説明する地図に近づきます。Registerと公開API文書を同じものとして扱ってはなりません。
八つを守ります。役割ごとの最小権限で接続を制限します。照会の権限とExportの権限を分けます。Exportには承認、監査記録、保存期間を置きます。Public DocumentationとInternal Registerを分けます。Token・Secret・Private KeyなどのCredential Materialは保存しません。必要ならSecret Managerの非機微なReferenceだけを結びます。API Recordと添付のEvidenceにData Classificationを適用します。外部への共有版からは内部のRuntime ReferenceとOwnerの情報を取り除きます。
OWASPはAPI文書を権限のある利用者にのみ提供するよう勧め、OpenAPIも文書の一部を接続権限に応じて隠すSecurity Filteringを明示します。[1]
API Inventoryの完了条件
API Inventoryは、すべてのURLを一度集めたからといって終わりません。十一の問いにEvidenceで答えられる必要があります。何が存在するか。どこに配布されているか。どのProtocolとVersionか。最近何が観測されたか。誰が責任を負うか。なぜ必要か。どのデータを扱うか。誰に露出すべきか。現在のLifecycleは何か。いつどう廃棄するか。四層は互いに一致しているか。
どのSpecも、Gateway Logも、Scannerも、この問いのすべてに単独では答えられません。API Inventoryの実体は一覧ではなく、不一致を見つけ続けて解消する運用の過程です。Inventoryが十分に整い最新の状態で保たれてこそ、各APIの脅威とデータ・露出の条件に合った統制を決められます。その次の段階は、六つのAPI保安統制を比較した上位の文書が扱います。
