こんにちは！APIファーストでの開発、進んでいますか？
「仕様書を書いてからコードを書く」というアプローチは非常に強力ですが、ちょっと待ってください。そのOpenAPI定義書、セキュリティの穴だらけになっていませんか？
「パスワードのハッシュ値がレスポンスに含まれていた」
「認証（Authorization）が必須なはずのエンドポイントに、セキュリティ定義が漏れていた」
これらを本番リリース後や、ひどい場合はペネトレーションテスト（脆弱性診断）で指摘されて冷や汗をかく……なんて現場を、私は数え切れないほど見てきました。
だからこそ、開発の初期段階で検知する「シフトレフトなセキュリティ対策」が不可欠です。今回は、OpenAPI定義書のセキュリティを自動で監査・担保するための「静的解析ツール」の導入方法を、優しく、かつ現場の知見をたっぷり込めて解説します。これをマスターすれば、あなたの書くAPIの安全性は劇的に跳ね上がりますよ！
—
1. なぜAPI定義書の「静的解析」が必要なのか？
APIファースト開発において、OpenAPI（旧Swagger）の定義書は、開発チーム全員の「契約書（ソース・オブ・トゥルース）」です。
しかし、この契約書自体にセキュリティ上の不備があったらどうでしょう？
- 過度なデータ露出（Excessive Data Exposure）: クライアントに見せる必要のない内部IDやフラグがスキーマに含まれている。
- 認証の欠落（Missing Authentication）: 重要なエンドポイントに `security` スキーマが設定されていない。
コードを書き終えてからこれらを直すのは、設計図を無視して建てた家の壁を壊して配管を直すようなものです。コードを書く前、あるいはCI/CDパイプラインに乗せた瞬間に、機械的にチェックする仕組み（静的解析）を最初に入れてしまいましょう。
—
2. 今回導入する最強のツール：Spectral
今回紹介するのは、OpenAPI/AsyncAPI向けの柔軟なJSON/YAMLリンターである「Spectral（スペクトル）」です。
世界中の多くのテック企業が、APIの品質・セキュリティゲートとして採用しているデファクトスタンダードのツールです。ルールのカスタマイズ性が高く、独自のセキュリティポリシーを簡単に組み込めます。
インストールはこれだけ！
Node.js環境があれば、グローバルにインストールするのも一瞬です（プロジェクトごとにローカルインストールするのがベストプラクティスですが、今回は手軽に試しましょう）。
npmを使ってグローバルインストール
npm install -g @stoplight/spectral-cli
インストールできたら、バージョンを確認してみましょう。
spectral –version
これで準備は完了です。
—
3. 最重要！セキュリティLintの基礎セットアップ
Spectralの真骨頂は、「OAS（OpenAPI Standard）ルールセット」に加え、セキュリティに特化したルールを適用できる点です。
プロジェクトのルートディレクトリに、設定ファイルである `.spectral.yaml` を作成しましょう。ここに「どんなルールで監査するか」を定義します。
`.spectral.yaml` の作成
以下の設定をコピーして、プロジェクトのルートに置いてください。
.spectral.yaml
Stoplight Spectralのセキュリティ監査設定ファイル
1. OpenAPIの公式推奨ルール（OAS ruleset）をベースとして継承する
extends: [“spectral:oas”]
2. プロジェクト固有の厳格なルールを追加・上書きする
rules:
# すべてのエンドポイントにセキュリティ（認証）が定義されているかチェック
operation-security-defined:
description: “すべてのAPIオペレーションには、何らかのセキュリティ（認証）定義が必須です。”
severity: error # 違反した場合はビルドを落とすレベルのエラーにする
given: $.paths[][get,post,put,delete,patch]
then:
field: security
function: truthy
# 危険なHTTPメソッド（TRACEなど）の使用を禁止する
no-trace-methods:
description: “セキュリティリスク（XST攻撃など）を避けるため、TRACEメソッドの使用は禁止です。”
severity: error
given: $.paths[].trace
then:
function: falsy
# レスポンスに ‘password’ などの機密フィールドが含まれていないか（簡易チェック）
no-password-in-response:
description: “レスポンススキーマに ‘password’ フィールドを含めてはいけません。”
severity: warn # 警告レベル
given: $.paths[].responses[].content[‘application/json’].schema..properties
then:
property: password
function: falsy
この設定ファイルにより、「認証の付け忘れ」「TRACEメソッドの排除」「パスワードのうっかり露出」を自動で検知できるようになります。
—
4. 精度高い「Hello World」的動作確認
それでは、わざとセキュリティ上の不備を含んだ「ダメなOpenAPI定義書」を用意して、Spectralが正しく検知できるかテストしてみましょう。
テスト用の定義書：`openapi-sample.yaml`
openapi: 3.0.3
info:
title: 脆弱性テスト用API
version: 1.0.0
paths:
/users:
get:
summary: ユーザー一覧取得
# 【不備1】ここに security が定義されていない！
responses:
‘200’:
description: 成功
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
password:
type: string # 【不備2】パスワードが含まれている！
trace:
summary: デバッグ用TRACE
responses:
‘200’:
description: OK # 【不備3】TRACEメソッドを使っている！
どうですか？このYAMLには、先ほど設定したルールにひっかかる「地雷」が3つも埋め込まれています。
監査を実行してみる！
ターミナルを開き、以下のコマンドを実行します。
spectral lint openapi-sample.yaml
【実行結果のイメージ】
C:\work\openapi-sample.yaml
11:5 error operation-security-defined すべてのAPIオペレーションには、何らかのセキュリティ（認証）定義が必須です。 paths./users.get
21:21 warn no-password-in-response レスポンススキーマに ‘password’ フィールドを含めてはいけません。 paths./users.get.responses.200.content[application/json].schema.items.properties.password
27:5 error no-trace-methods セキュリティリスク（XST攻撃など）を避けるため、TRACEメソッドの使用は禁止です。 paths./users.trace
✖ 3 problems (2 errors, 1 warning)
見事に見つけてくれました！
このように、人間が見逃しがちな規約違反やセキュリティリスクを、コンソール上で一瞬にしてあぶり出すことができます。
—
5. 先輩エンジニアからの実践アドバイス：CI/CDへの組み込み
この静検知ツールは、手元で実行するだけではもったいないです。GitHub ActionsなどのCI/CDパイプラインに組み込み、PR（プルリクエスト）の段階で自動チェックするようにしましょう。
.github/workflows/api-security-check.yml の例
name: OpenAPI Security Audit
on:
pull_request:
paths:
- ‘openapi.yaml’
jobs:
lint:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Run Spectral Lint
uses: stoplightio/spectral-action@v3
with:
file_spec: ‘openapi.yaml’
これを行っておけば、セキュリティ的にNGなAPI定義書がmainブランチにマージされることを物理的に防げます。「あ、ごめん、認証つけ忘れてた！」というレビューのやり取りすら不要になりますよ。
—
まとめ
今回は、Swagger/OpenAPIの静的解析ツール「Spectral」を使ったセキュリティ監査の基本を解説しました。
- APIファーストのセキュリティは設計段階（シフトレフト）から始める
- Spectralを使って、認証の抜けや機密データの露出を自動検知する
- CI/CDに組み込んで、マージ前に機械的なチェックを強制する
これを導入するだけで、あなたのチームのAPIセキュリティレベルは一段も二段も引き上げられます。ぜひ今日の業務から試してみてください。あなたの開発ライフライがより安全で、快適なものになることを応援しています！