Kubernetes運用で一番つらい事故は、クラスタが壊れるよりも「本来防げたはずのミスがそのまま本番へ入る」ことです。たとえば、latest タグのイメージが本番に入り再現不能になる、resources 未設定でノードが詰まる、privileged コンテナが混入する。これらは人の注意力だけに依存すると必ず再発します。

そこで有効なのが Admission Policy（入場制御）です。本記事では Kyverno を使って、現場で本当に運用できるポリシー群を段階導入する手順をまとめます。単なる「denyの例」ではなく、監査→警告→強制の移行、例外管理、CI連携まで含めて解説します。

1. なぜKyvernoなのか

OPA Gatekeeper も強力ですが、Kyvernoは以下の特徴があり、初期導入が比較的スムーズです。

• YAML中心で書ける（Rego学習コストを後回しにしやすい）
• validate / mutate / generate / verifyImages を一貫して扱える
• PolicyReportにより違反可視化がしやすい
• Pod SecurityやSupply Chain対策との相性が良い

「まずルールを回し始める」目的なら、Kyvernoは現実的な選択肢です。

2. 先に決めるべき設計原則

導入前に、以下だけは先に決めておきます。

1. 導入フェーズ: Audit → Enforce を基本にする
2. 責任分界: プラットフォームチームが共通ポリシー、各チームがアプリ固有例外
3. 例外の期限: 永久例外は禁止。期限付きで必ず棚卸し
4. 観測性: 違反数・対象Namespace・上位違反ルールをダッシュボード化

この原則なしにルールだけ増やすと、運用が破綻します。

3. 最小導入手順（30〜60分）

3.1 Kyvernoのインストール

1
2
3
4
5
6
7
8
9

helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update

helm upgrade --install kyverno kyverno/kyverno \
  -n kyverno --create-namespace \
  --set admissionController.replicas=2 \
  --set backgroundController.replicas=2 \
  --set cleanupController.replicas=1 \
  --set reportsController.replicas=1

本番では可用性のため、admission/backgroundは最低2レプリカ推奨です。

3.2 まずはAuditモードで3ルール

最初に効くルールは、次の3つです。

• イメージタグに latest を禁止
• CPU/Memory requests/limits必須
• privileged: true を禁止

例: latest タグ禁止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-latest-tag
spec:
  validationFailureAction: Audit
  background: true
  rules:
    - name: validate-image-tag
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "latestタグは禁止です。固定タグまたはdigestを使用してください。"
        foreach:
          - list: "request.object.spec.containers"
            deny:
              conditions:
                any:
                  - key: "{{ element.image }}"
                    operator: Matches
                    value: ".*:latest$"

3.3 レポートで現状把握

1
2
3

kubectl get policyreport -A
kubectl get clusterpolicy
kubectl describe clusterpolicy disallow-latest-tag

導入直後は違反が大量に出るのが普通です。ここで「Kyvernoが厳しすぎる」と判断しないでください。違反は“見えていなかった負債”です。

4. 実務で効くルールセット（具体例）

4.1 リソース未設定防止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-resources
spec:
  validationFailureAction: Audit
  rules:
    - name: check-resources
      match:
        any:
          - resources:
              kinds: ["Pod"]
      validate:
        message: "全コンテナにrequests/limitsを設定してください。"
        pattern:
          spec:
            containers:
              - resources:
                  requests:
                    cpu: "?*"
                    memory: "?*"
                  limits:
                    cpu: "?*"
                    memory: "?*"

4.2 特権設定防止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-privileged
spec:
  validationFailureAction: Enforce
  rules:
    - name: no-privileged
      match:
        any:
          - resources:
              kinds: ["Pod"]
      validate:
        message: "privilegedコンテナは禁止です。"
        pattern:
          spec:
            containers:
              - securityContext:
                  =(privileged): "false"

4.3 Digest固定の推奨（Supply Chain）

本来は digest 固定が理想です。移行期は Audit で始め、違反率が下がってから Enforce に切り替えます。

5. AuditからEnforceへ移行する基準

「何となく」で切り替えると炎上します。次の客観指標を使うと安全です。

• 直近14日で対象ポリシー違反率が5%未満
• 主要Namespace（prod/stg/shared）で違反ゼロ
• 例外申請フロー（Issue/PRテンプレート）が整備済み
• 当番がトラブル時に切り戻し手順を理解している

validationFailureAction を一括で上げるのではなく、ルール単位・Namespace単位で段階化するのがポイントです。

6. 例外運用のテンプレート

ポリシー導入で最も壊れるのは「例外管理」です。おすすめは以下。

• 例外は PolicyException で明示
• 期限（例: 14日）を必須にする
• チケット番号をannotationで必須化
• 期限切れを毎日バッチで通知

例外YAMLに expires と owner を必須化すると、放置率が一気に下がります。

7. CIに組み込んで“本番前に落とす”

クラスタ投入時に拒否されるより、PR段階で検知される方が開発体験は良いです。kyverno-cli をCIで実行します。

1

kyverno apply policies/ -r manifests/ --audit-warn

GitHub Actions例:

1
2
3
4

- name: Validate manifests with Kyverno
  run: |
    kyverno version
    kyverno apply ./policies -r ./k8s --audit-warn

これで「マージ後に初めて失敗する」パターンを減らせます。

8. よくある障害と対処

症状1: 正常なPodまで拒否される

• match条件が広すぎる可能性
• exclude で kube-system や監視系を一時除外
• まずAuditで影響範囲を確認してからEnforceへ

症状2: Admission timeoutでデプロイ遅延

• Kyvernoコンポーネントのリソース不足を確認
• policy数が多い場合、ルール統合とmatch最適化
• API Serverとのネットワーク遅延確認

症状3: レポートは出るが改善が進まない

• 違反上位3ルールに絞ってKPI化
• チーム別に違反件数を見える化
• 例外を期限付きに強制

9. 運用を続けるためのダッシュボード指標

最低限、以下を可視化してください。

• ルール別違反件数（7日移動平均）
• Namespace別違反件数
• Audit と Enforce の比率
• 期限切れ例外の件数
• deploy失敗要因のうちpolicy起因の割合

これを見ないと、ポリシーは「導入しただけ」で止まります。

10. 実践ロードマップ（最初の4週間）

• Week 1: Kyverno導入、3ルールをAuditで開始
• Week 2: 違反上位を改善、例外テンプレート導入
• Week 3: 一部NamespaceでEnforce化
• Week 4: CI連携完了、SLOに違反率を組み込み

4週間で「人頼みのレビュー文化」から「仕組みで防ぐ文化」へ移行できます。

まとめ

Kyverno導入の本質は、Kubernetesを縛ることではなく、再発するミスを設計で減らすことです。

• 最初はAuditで可視化
• 指標を持って段階的にEnforce
• 例外は期限付きで管理
• CIに前倒し検知を組み込む

この4点を守れば、ポリシーは“開発を止める壁”ではなく“事故を減らすガードレール”になります。まずは latest 禁止とリソース必須の2ルールから始めて、違反データを見ながら育てていきましょう。

CI/CD の事故は、ビルドが失敗することより「漏えいしても気づけない鍵」が残り続けることのほうが深刻です。特に AWS_ACCESS_KEY_ID のような長期シークレットを GitHub Secrets に保存し続ける運用は、便利ですがリスクが高いです。

本記事では、GitHub Actions の OIDC（OpenID Connect）連携を使って、長期鍵を使わずに AWS へデプロイする実践手順をまとめます。単なる設定紹介ではなく、最小権限・ブランチ制限・監査ログ設計まで含めて、明日から本番投入できる形で説明します。

1. まず何が危険なのか：長期シークレット運用の限界

従来構成では、次のような問題が起きます。

• Secret が漏れても検知が遅い（CIログ、誤コミット、権限の広いメンバー）
• ローテーションが後回しになる
• 1つの鍵で複数環境へアクセスできてしまう
• 「誰のどの workflow 実行が何をしたか」が追いにくい

OIDC 連携では、GitHub が発行する短命トークンを信頼し、AWS 側で一時認証情報を払い出します。つまり、保管する鍵そのものを減らすのが最大の価値です。

2. 全体アーキテクチャ

基本フローは以下です。

1. GitHub Actions ジョブが OIDC トークンを取得
2. AWS IAM の OIDC プロバイダとロール信頼ポリシーで検証
3. 条件に一致したジョブだけ AssumeRoleWithWebIdentity
4. 一時クレデンシャルで S3/CloudFront/ECR/ECS へデプロイ

ポイントは「GitHub 側の workflow 制御」だけでなく、AWS 側で repo・branch・workflow を強制することです。

3. AWS 側の初期設定（OIDC Provider + IAM Role）

3.1 OIDC Provider を作成

CLI 例（すでに存在する場合はスキップ）:

1
2
3
4

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

3.2 信頼ポリシーを厳密化する

以下のように sub と aud を必ず絞ります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:ref:refs/heads/main"
        }
      }
    }
  ]
}

sub を repo:org/repo:* のように広く取りすぎると、意図しない workflow からも引き受ける可能性があり危険です。

3.3 デプロイ権限ポリシーを分離する

「ロール1個に全部盛り」は避けます。

• deploy-web-prod-role: S3同期 + CloudFront invalidation
• deploy-api-prod-role: ECR push + ECS update
• read-only-audit-role: CloudWatch Logs / Describe 系のみ

環境別（dev/stg/prod）にロールを分離すると、誤デプロイ時の被害半径が大きく減ります。

4. GitHub Actions workflow 実装

最小サンプル:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

name: deploy-web
on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/deploy-web-prod-role
          aws-region: ap-northeast-1

      - name: Build
        run: |
          npm ci
          npm run build

      - name: Upload to S3
        run: aws s3 sync ./dist s3://example-prod-web --delete

      - name: Invalidate CloudFront
        run: aws cloudfront create-invalidation --distribution-id E123456 --paths "/*"

重要なのは permissions.id-token: write を明示する点です。これがないと OIDC トークンを取得できません。

5. 事故を防ぐための実務ルール

5.1 branch protection と environment protection を組み合わせる

• main 直push禁止
• 必ず PR + 1 approval
• production environment には Required reviewers を設定
• 夜間デプロイを禁止したい場合は手動承認ステップを入れる

5.2 workflow ファイル改変の監査

.github/workflows/*.yml の変更は CODEOWNERS で必ずレビュアー固定にします。

1

.github/workflows/*  @platform-team

5.3 self-hosted runner の扱い

OIDC を導入しても、runner 自体が侵害されると意味が薄れます。

• runner をプロジェクト共有にしない（専用化）
• ジョブ後にワークディレクトリをクリーン
• egress 制限をかける
• runner グループを環境ごとに分離

6. トラブルシューティング

症状1: Not authorized to perform sts:AssumeRoleWithWebIdentity

確認ポイント:

1. aud が sts.amazonaws.com になっているか
2. sub が実際の実行 ref と一致しているか（タグ実行でハマりやすい）
3. permissions.id-token: write が設定されているか
4. Role ARN の typo がないか

症状2: main 以外で偶発的にデプロイされた

• workflow の on.push.branches 見直し
• IAM 信頼ポリシー sub を main 固定へ
• 環境保護ルール（Required reviewers）追加

症状3: デプロイは通るが操作が一部失敗

これは IAM 権限不足の可能性が高いです。CloudTrail の eventName と errorCode を見て、必要最小限のアクションだけ追加します。闇雲に * を付けないこと。

7. 段階的な移行計画（既存運用からの切替）

実務では一気に切り替えず、以下の順が安全です。

1. OIDC ロールを作成（既存シークレットは残す）
2. staging workflow だけ OIDC に切替
3. 1週間監視（失敗率・デプロイ時間・CloudTrail）
4. production を OIDC 化
5. 最後に長期シークレットを削除

削除前に「どの workflow がどの secret を参照しているか」を grep で確認しておくと事故が減ります。

1

git grep -n "AWS_ACCESS_KEY_ID\|AWS_SECRET_ACCESS_KEY" .github/workflows

8. 監査ログ設計：何を見れば安全性が上がるか

最低限、次をダッシュボード化すると運用しやすいです。

• AssumeRoleWithWebIdentity 実行回数（日次）
• 失敗イベント数（権限エラー/条件不一致）
• production deploy 実行者（workflow + sha + actor）
• 1回のデプロイで変更された主要リソース数

CloudTrail + CloudWatch Logs Insights での簡易クエリ例:

1
2
3
4
5

fields @timestamp, userIdentity.sessionContext.sessionIssuer.userName, eventName, errorCode
| filter eventSource = "sts.amazonaws.com"
| filter eventName = "AssumeRoleWithWebIdentity"
| sort @timestamp desc
| limit 50

まとめ

OIDC は「設定が新しいから導入する」ものではなく、長期鍵を削減して事故確率を下げるための運用設計です。導入時にやるべきことはシンプルで、次の3つに集約できます。

1. IAM 信頼ポリシーを repo/branch 単位で厳密化する
2. workflow 側で id-token 権限と環境保護を設定する
3. CloudTrail で AssumeRole の監査を継続する

ここまで実施すれば、CI/CD のセキュリティは「頑張って守る」状態から、「漏えいしにくい仕組みで守る」状態へ進化します。まずは staging 1本から置き換えるのがおすすめです。

FastAPI は実装が速い反面、認証・認可を最小構成のまま本番に出してしまい、後からセキュリティ事故に発展するケースが少なくありません。特に「JWT を入れたから安全」という誤解は危険です。

本記事では、開発速度を落とさずに本番で耐える認証基盤を作るための設計を、コード例と運用手順込みで解説します。

1. 認証と認可を分離して設計する

最初に押さえるべきは責務分離です。

• 認証（Authentication）: 誰かを確認する
• 認可（Authorization）: 何をしてよいか判定する

この2つを混ぜると、実装も監査も破綻します。FastAPI では dependency を分け、get_current_user と require_permission を独立させるのが基本です。

2. JWT は「短命 + リフレッシュ + 失効管理」で使う

アクセストークンを長寿命にすると、漏えい時の被害が大きくなります。実運用では以下が標準です。

• Access Token: 5〜15分
• Refresh Token: 7〜30日
• Refresh Token は DB 保存し、ローテーション時に旧トークンを失効

sub だけでなく、jti（トークンID）や scope を持たせると管理しやすくなります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from datetime import datetime, timedelta, timezone
import jwt

ALGORITHM = "HS256"


def create_access_token(user_id: str, scopes: list[str], secret: str) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "scope": " ".join(scopes),
        "iat": int(now.timestamp()),
        "exp": int((now + timedelta(minutes=10)).timestamp()),
        "jti": "generated-uuid"
    }
    return jwt.encode(payload, secret, algorithm=ALGORITHM)

3. 鍵管理とローテーション

秘密鍵を .env に固定して数年運用するのは典型的な事故パターンです。最低限、次を実施します。

• KMS/Vault など外部シークレット管理を利用
• kid をヘッダに持たせ、複数鍵を並行運用
• 鍵ローテーション手順を runbook 化

ローテーションの要点:

1. 新鍵を追加（検証側は新旧どちらも受理）
2. 発行側を新鍵へ切替
3. 旧鍵の有効期限を過ぎたら削除

この手順にすると、無停止で切替できます。

4. FastAPI Dependencyで認可を明示化

ロジック中で if user.role == "admin" を乱立させると、抜け漏れが起こります。権限チェックは dependency 化し、ルート定義に明示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from fastapi import Depends, HTTPException, status


def require_permission(required: str):
    def checker(user=Depends(get_current_user)):
        if required not in user.permissions:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="insufficient permissions"
            )
        return user
    return checker


@router.delete("/projects/{project_id}")
def delete_project(
    project_id: str,
    user=Depends(require_permission("project:delete"))
):
    ...

ルート単位で要件が見えるため、レビュー効率と監査性が上がります。

5. RBAC/ABAC の使い分け

小規模なら RBAC（role-based）で十分ですが、顧客単位データや組織階層があると ABAC（属性ベース）を併用した方が安全です。

• RBAC: admin, editor, viewer
• ABAC: tenant_id, resource_owner_id, department

実務では「ロールで粗く許可し、属性で絞る」が扱いやすいです。

6. マルチテナントで必須の防御

マルチテナント API では、ID 推測よりもテナント境界漏れが主要リスクです。対策は次の通りです。

• すべての DB クエリに tenant_id 条件を必須化
• 管理者 API でも境界を明示的に超える操作だけ許可
• 監査ログに tenant_id, actor_id, resource_id を残す

SQLAlchemy でも repository 層で共通フィルタを強制すると漏れを減らせます。

7. 監査ログを設計段階で入れる

認証系は障害後に「誰が何をしたか」が必要になります。後付けだと間に合いません。最低限、次を記録します。

• ログイン成功/失敗（IP, user-agent, reason）
• 権限エラー（403）
• 重要操作（削除、権限変更、請求情報更新）
• トークン失効・再発行

フォーマットは JSON 構造化に統一し、SIEM や OpenSearch に流せる形にしておくと分析が速いです。

8. レート制限とブルートフォース対策

パスワード認証がある場合、レート制限なしは危険です。slowapi などを使い、ログイン系エンドポイントに制限を入れます。

1
2
3
4
5
6
7
8
9

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.post("/auth/login")
@limiter.limit("5/minute")
def login(...):
    ...

さらに次を組み合わせると強化できます。

• 失敗回数に応じた遅延（progressive delay）
• CAPTCHA（必要時のみ）
• 異常IP/ASN の遮断

9. よくある実装ミス

ミスA: 署名検証はしているが aud/iss 未検証

結果:

• 他システム向けトークンを誤受理

対処:

• issuer/audience を厳格検証
• 想定外クレームは拒否

ミスB: refresh token の使い回しを検知しない

結果:

• 漏えい時に長期間乗っ取られる

対処:

• ローテーション時に旧トークン失効
• 再利用検知時はセッション全失効

ミスC: 認可チェックが一部エンドポイントで抜ける

結果:

• 水平権限昇格

対処:

• dependency ベースで強制
• 重要ルートにセキュリティテスト追加

10. テスト戦略（必須）

認証はユニットテストだけでなく、統合テストで権限境界を確認します。

• 有効トークン/期限切れ/改ざんトークン
• role ごとのアクセス可否
• tenant 越境アクセス拒否
• refresh token 再利用検知

pytest では fixture で role 別トークンを用意し、回帰を防ぎます。

11. 障害時 runbook（最低限）

インシデント時に迷わないよう、次を文書化しておきます。

1. 鍵漏えい疑い時の全トークン失効手順
2. 認証基盤障害時のフェイル動作（許可しすぎを防ぐ）
3. 監査ログの検索手順
4. 関係者通知テンプレート

特に「認証サーバーが落ちたとき、API をどうするか」は事前に決めておく必要があります。

12. 導入チェックリスト

• access token は短寿命（<=15分）
• refresh token は DB 管理 + ローテーション
• 鍵ローテーション手順がある
• ルート単位で認可 dependency が明示されている
• tenant 境界を DB レイヤーで強制している
• 監査ログ（認証/認可/重要操作）を構造化保存
• レート制限と異常検知がある
• 権限境界の統合テストがある

FastAPI の認証・認可は、フレームワーク機能だけでは守り切れません。トークン寿命設計、鍵運用、境界強制、監査、テスト、runbookまで含めて初めて、本番で信頼できるセキュリティ基盤になります。

MCP（Model Context Protocol）は、LLM と外部ツールを接続する強力な仕組みです。便利な一方で、本番運用では「権限の過剰付与」「監査不能」「障害時の暴走」が起きやすく、設計を誤ると一気にリスクが跳ね上がります。

本記事では、MCP サーバーを業務利用する前提で、安全性・可観測性・運用性を満たす設計パターンをまとめます。PoC から本番へ上げる際のチェックリストとして使える構成にしています。

1. MCP本番運用で先に決めるべきこと

最初に決めるべきは、技術スタックではなく「権限境界」です。

• どのエージェントが、どのツールを使えるか
• 書き込み系操作（作成・更新・削除）の承認方式
• 外部送信（メール、投稿、通知）の監査ルール
• 失敗時の停止条件（fail-open か fail-closed か）

ここを決めずに実装を始めると、あとから制約を入れられず、結果として運用停止になります。

2. 推奨アーキテクチャ：Control Plane と Tool Plane の分離

MCP 構成は最低でも2層に分けると安全です。

1. Control Plane: 認証、認可、監査、レート制御
2. Tool Plane: 実際のツール実行（DB、GitHub、Browser、Messaging）

2-1. なぜ分離するのか

Tool 実装に認可ロジックを埋め込むと、ツール追加のたびにセキュリティ品質がブレます。Control Plane で一元化すれば、ポリシー変更時も1箇所で反映できます。

2-2. リクエストフロー例

1
2
3
4

Agent -> MCP Gateway(Control Plane)
      -> Policy Engine (allow/deny, scope check)
      -> Tool Adapter (Tool Plane)
      -> Audit Logger

deny の場合も必ず監査ログに記録し、試行の痕跡を残します。

3. 認可設計：RBACだけでは足りない

本番では RBAC（役割）に加えて ABAC（属性）を使うと事故が減ります。

• RBAC: writer, reviewer, admin
• ABAC: 時間帯、環境（prod/staging）、対象リポジトリ、操作種別

例:

• staging では write 可、prod は read のみ
• 23:00〜08:00 の外部送信を自動 deny
• delete は人間承認トークン必須

このルールを YAML 等で宣言的に持つと、監査とレビューが容易になります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

policies:
  - name: deny-night-send
    when:
      action: message.send
      time_between: ["23:00", "08:00"]
    effect: deny

  - name: allow-read-docs
    when:
      action: docs.read
      env: ["prod", "staging"]
    effect: allow

4. 書き込み操作のガードレール

削除や公開投稿など不可逆操作は、二段階に分けます。

1. Planフェーズ: 何を変更するか差分提示
2. Applyフェーズ: 承認トークン付きで実行

4-1. Git操作の安全化

• main 直 push 禁止（PR 経由のみ）
• commit message に実行主体IDを埋め込む
• 重要ディレクトリは CODEOWNERS レビュー必須

これにより「誰が」「なぜ」「どの差分を」適用したか追跡できます。

5. 可観測性：最低限必要な監査ログ項目

MCP の障害は、アプリログだけでは追えません。次を構造化ログで保存します。

• request_id
• agent_id / session_id
• tool_name
• action（read/write/delete/send）
• policy_decision（allow/deny）
• latency_ms
• result（success/failure）
• redacted_input_hash

入力本文を丸ごと保存すると個人情報漏えいリスクが高いので、ハッシュ化・マスキングが原則です。

6. 障害設計：MCPが壊れても全体を止めない

6-1. Circuit Breaker を必ず入れる

下流ツール（例: GitHub API）が遅延した際、MCP 全体が巻き込まれないようにします。

• 連続失敗 N 回で open
• cool-down 後に half-open
• 成功確認後に close

6-2. タイムアウト予算

MCP リクエストは複数ツールを跨ぐため、全体予算を先に決めます。

• 全体: 10 秒
• 認可: 500ms
• ツール実行: 7 秒
• ログ書き込み: 1 秒

予算超過時は中断し、部分成功を明示するレスポンスを返すほうが、黙って待つより運用しやすいです。

7. 実運用チェックリスト（導入前に必須）

セキュリティ

• デフォルト deny（明示 allow のみ）
• 外部送信系に承認フローあり
• APIキー/トークンのローテーション手順あり
• 監査ログの改ざん防止（WORM/署名）

信頼性

• タイムアウト・再試行・サーキットブレーカ設定済み
• ツールごとのレート制限あり
• 障害時の degraded mode 定義済み
• 週次で復旧訓練（ゲームデイ）実施

運用

• Runbook とオンコール体制がある
• 重大操作の通知先が明確
• 監査レポートを定期出力できる
• ポリシー変更はPRレビュー必須

8. PoCから本番へ上げるときの移行手順

おすすめは次の4段階です。

1. Read-only段階: 読み取り専用ツールのみ許可
2. 限定Write段階: staging への書き込みのみ解放
3. 承認付きProd段階: prod 書き込みは人間承認必須
4. 自動化段階: 低リスク操作だけ自動承認

この順序なら、事故を起こさず運用知見を溜められます。

まとめ

MCP は「つなげる技術」ですが、本番では「制御する技術」に重心があります。成功する導入の共通点は次の3つです。

• 権限境界を最初に設計する
• 監査可能な実行経路を持つ
• 障害時に安全側へ倒れる設計にする

AI エージェント活用は今後さらに広がります。だからこそ、機能追加より先に運用設計を固めることが、長期的な速度と安全性を両立する最短ルートです。今日から始めるなら、まずは「default deny + 監査ログ項目定義」この2つを先に確定してください。

9. 監査レビューを回すための実務フロー

ログを取って終わりでは意味がありません。週次または隔週で、次の観点で監査レビューを実施します。

• deny された操作のうち、正当要求だったものはないか
• 承認付き操作で承認理由が空欄になっていないか
• 失敗率の高いツールに設計欠陥がないか
• 夜間・休日の危険操作が発生していないか

監査レビューはセキュリティ部門だけでなく、実際に運用する開発チームが同席することで改善速度が上がります。ポリシーは「守らせるもの」ではなく「運用と一緒に育てるもの」と捉えるのが重要です。

10. 導入初期に決めておくべきSLO

MCP 基盤にも SLO を置くと、感覚論で運用しなくて済みます。例として以下が扱いやすいです。

• 正常リクエスト成功率: 99.5%以上
• ポリシー判定レイテンシ p95: 300ms 以下
• 重大操作の監査ログ欠損率: 0%
• 障害発生時の検知時間: 5分以内

このSLOをダッシュボード化し、週次で逸脱をレビューするだけで、MCP運用の成熟度は大きく上がります。PoC段階から数値を持っておくと、本番移行時の説得材料としても有効です。

補足として、導入時は「全ツール同時公開」を避け、1ツールずつトラフィックを段階開放するのが安全です。障害発生時の切り戻し対象が明確になり、原因分析時間を大幅に短縮できます。

セルフホストランナーは高速で柔軟です。特定ツールチェーンや社内ネットワーク接続が必要な環境では、ほぼ必須といえます。一方で、設定を誤ると CI/CD が攻撃経路になります。

近年のインシデントでは、依存パッケージ汚染だけでなく「Actions workflow の権限過多」「fork 由来PRでの秘密情報流出」「ランナー残存データ」が問題化しています。

本記事では、セルフホストランナーを安全に運用するための防衛策を、設計レイヤごとに整理します。

脅威モデルを先に定義する

まず守る対象を明確にします。

• リポジトリのソースコード
• Secrets（クラウド鍵、署名鍵、トークン）
• 配布物の完全性（改ざん防止）
• 社内ネットワーク接続経路

攻撃経路は主に次です。

1. 悪意ある PR が workflow を悪用
2. Marketplace Action の supply chain 汚染
3. ランナー上に残る credential / build artifact
4. 過剰な GITHUB_TOKEN 権限

この4点を潰す設計が防御の中心になります。

1. ランナーは「使い捨て」を前提にする

長寿命ランナーは便利ですが、攻撃後の残留リスクが高いです。可能ならジョブ単位で破棄できる ephemeral 構成を採用します。

• Kubernetes + Actions Runner Controller
• VMテンプレートから都度起動
• ジョブ終了後に完全破棄

少なくとも /tmp と workspace を確実に消去し、Docker layer cache の共有範囲を制御してください。

2. workflow 権限を最小化する

permissions: write-all は禁止レベルです。workflowごとに最小権限を明記します。

1
2
3
4

permissions:
  contents: read
  pull-requests: write
  id-token: write

特に id-token: write は OIDC 連携に必要ですが、不要ジョブで許可しないこと。権限漏れがクラウド侵害に直結します。

3. fork PR の実行ポリシーを分離する

外部 fork からの PR で secrets を使うジョブを実行しない設計が必須です。

推奨:

• pull_request イベント: テストのみ、secrets 無し
• pull_request_target: 原則禁止、必要なら厳格レビュー
• デプロイ系は push（保護ブランチ）だけ

また、workflow_run を使って「検証済み成果物だけを次段へ渡す」2段構成にすると安全性が上がります。

4. Action の固定と検証

uses: actions/checkout@v4 のようなタグ指定だけでは、将来更新の影響を受けます。高リスク工程では commit SHA 固定を検討します。

1

- uses: actions/checkout@8ade135a... # SHA pin

加えて、許可済み Action の allowlist を組織ポリシー化します。無制限に Marketplace Action を使わせると監査不能になります。

5. Secrets 管理は OIDC 中心へ

長期固定鍵を GitHub Secrets に置く運用は、漏洩時の被害が大きいです。クラウド連携は OIDC フェデレーションに移行し、短命トークンを発行します。

利点:

• 鍵配布不要
• 期限短い
• リポジトリ/ブランチ条件で絞れる

AWS なら role trust policy に sub 条件を入れ、「main ブランチの release workflow だけ許可」といった制御が可能です。

6. ネットワーク分離と出口制御

セルフホストランナーが社内フラットネットワークに直結している構成は危険です。ランナー専用サブネットを作り、次を実施します。

• egress allowlist（必要ドメインのみ）
• 社内DBへの直接接続禁止
• 管理プレーンと実行プレーン分離

「CIだから社内に近いほど便利」は短期的発想です。侵害前提で最小到達範囲に設計します。

7. 監査ログと改ざん検知

必要なログ:

• workflow 実行者
• 使用ランナーID
• 取得したクラウド権限
• 成果物ハッシュ

さらに、リリース成果物に SBOM と署名（cosign / sigstore）を付与し、配布前検証を自動化します。これで supply chain の追跡性が大きく向上します。

8. 実装チェックリスト（そのまま使える）

• セルフホストランナーは ephemeral 運用
• workflow permissions を最小権限化
• fork PR と deploy workflow を分離
• 高リスク Action は SHA pin
• OIDC による短命認証へ移行
• ネットワーク egress 制限
• artifact 署名と SBOM 生成
• 監査ログを90日以上保持

9. 段階導入プラン（4週間）

• Week1: 権限棚卸し、write-all 排除
• Week2: fork PR ポリシー分離、allowlist導入
• Week3: OIDC移行、固定鍵削減
• Week4: ephemeral runner 化、署名/SBOM実装

一気に変えると運用停止リスクがあるため、週単位で区切るのが現実的です。

まとめ

セルフホストランナーは強力ですが、セキュリティ設計を誤ると CI/CD が最も危険な入口になります。ポイントは「最小権限」「使い捨て」「短命認証」「監査可能性」の4つです。

まずは permissions の最小化と fork PR 分離から始めてください。ここを押さえるだけでも、供給網リスクは大幅に下げられます。

実運用での検知ルール例（SIEM連携）

防御策を実装しても、検知が弱いと侵害を見逃します。次のイベントを SIEM 側で高優先度アラート化してください。

• 深夜帯の workflow 権限変更
• 普段使わないランナーラベルでのジョブ実行
• release workflow で未知の Action 呼び出し
• OIDC 経由で想定外クラウドロールを取得

検知時には自動で repository dispatch を使い、該当リポジトリのデプロイを一時停止する仕組みを入れると被害拡大を防げます。

インシデント対応Runbookの最小構成

供給網インシデントは初動が遅れると致命傷になります。Runbook には最低限次を含めます。

1. 影響範囲特定（対象リポジトリ、workflow、artifact）
2. 該当 Secrets/Role の無効化
3. ランナー群の全廃棄と再構築
4. 直近リリース成果物のハッシュ再検証
5. 監査ログ保全と関係者通知

この手順を平時に演習しておくことで、実際の障害時に迷いを減らせます。

組織導入で効くポリシー

• 新規 workflow はセキュリティレビュー必須
• Action 追加時はリスク評価テンプレート提出
• 重要リポジトリは branch protection + required review を強制
• セルフホストランナーの管理責任者を明確化

技術対策だけでは継続しません。責任分界とレビュー手順を運用ルール化することが、防御の持続性を高めます。

まとめ（運用視点）

最終的に重要なのは「侵害されないこと」ではなく「侵害されても被害を限定し、速く復旧できること」です。セルフホストランナーを使うなら、最初からゼロトラスト前提で設計し、検知・対応まで含めた体制を整えてください。

最後に

現場では「便利だから後で固める」が最も危険です。セルフホストランナーは導入初日から最小権限と隔離を前提に設計し、定期監査で逸脱を戻す運用を続けてください。

追加の運用Tip

新しいリポジトリを作るたびに同じ議論をしないため、テンプレートリポジトリへ安全な workflow 雛形を同梱しておくと効果的です。初期状態を安全側に固定するだけで、運用負荷と事故率の両方を下げられます。

継続的な棚卸しを習慣化してください。

FastAPI は開発速度が高く、PoC から本番まで一気に進めやすいフレームワークです。しかし、早く作れることと安全に運用できることは別問題です。実際の障害は、コードの正しさよりも運用の隙から発生します。

本記事では、FastAPI を本番で安心して運用するためのハードニング手順を、実装可能な形でまとめます。対象は「すでにAPIが動いているが、運用強度を上げたい」チームです。

1. 入口防御：TLS、ヘッダ、レート制限

TLS終端とForwardedヘッダ

ロードバランサ配下で動かす場合、X-Forwarded-For と X-Forwarded-Proto の扱いを明確にします。誤るとクライアントIPが取れず、監査も制限も機能しません。

1
2
3
4
5

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(TrustedHostMiddleware, allowed_hosts=["api.example.com", "*.example.com"])

allowed_hosts をワイルドにしすぎると Host Header Injection の温床になります。

セキュリティヘッダ

最低限次を返します。

• Strict-Transport-Security
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy

APIでも無関係ではありません。管理画面やドキュメントUIを守る意味があります。

レート制限

ブルートフォースと突発負荷に備え、IPまたはAPIキー単位でレート制限を設定します。

• 認証系: 5 req/min
• 通常API: 60 req/min
• 高負荷検索: 20 req/min

Redis バックエンド方式にして、アプリ再起動でカウンタが失われないようにします。

2. 認証・認可の落とし穴を塞ぐ

JWT検証の必須項目

exp だけ見て通す実装は危険です。少なくとも次を検証します。

• iss（発行者）
• aud（想定利用先）
• nbf（有効開始）
• kid に基づく鍵ローテーション

認可は「エンドポイント単位」ではなく「リソース単位」

/users/{id} のアクセス時に、path パラメータの id とトークンの主体を照合しない事故は頻発します。FastAPI の dependency で統一的に実施します。

1
2
3

def authorize_user_resource(current_user, target_user_id: str):
    if not (current_user.is_admin or current_user.user_id == target_user_id):
        raise HTTPException(status_code=403, detail="forbidden")

3. 入出力の安全化：Pydanticだけでは不十分

Pydantic は型安全に強いですが、ビジネス制約は別で実装が必要です。

• 文字列長上限
• 許可文字セット
• SQL/NoSQLインジェクションの危険文字
• HTML/Markdown サニタイズ

特に検索APIやエクスポートAPIは、クエリ文字列が巨大化しやすく DoS の入口になります。max_length を必ず定義してください。

4. 性能ハードニング：ワーカ・DB・タイムアウト

Uvicorn/Gunicorn 構成

CPUコア数に応じて worker を決めます。目安は workers = 2 * core + 1 から開始し、実測で調整。

1

gunicorn app.main:app -k uvicorn.workers.UvicornWorker --workers 5 --bind 0.0.0.0:8000 --timeout 30

DB接続プール

asyncpg や SQLAlchemy async engine のプール上限を設定しないと、ピーク時に接続飽和します。

• min: 5
• max: 30（DB性能と相談）
• pool timeout: 5s

タイムアウト戦略

上流・下流の timeout を揃えないと、雪崩障害が発生します。

• 外部API呼び出し: connect 1s / read 3s
• DBクエリ: statement timeout 2s（重処理は別キュー）
• API全体: 10s で fail fast

5. 例外設計と障害時の挙動

本番障害では「500が出ること」より「500の意味が不明」なことが問題です。エラーレスポンス形式を固定し、trace_id を必ず返します。

1
2
3
4
5
6
7

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "unexpected error",
    "trace_id": "8f3d..."
  }
}

内部例外はそのまま返さず、ログ側に stack trace を記録。ユーザーには安全な文言のみ返却します。

6. 可観測性：ログ・メトリクス・トレース

構造化ログ

JSON ログを標準化し、次を必須項目にします。

• timestamp
• level
• service
• trace_id
• user_id（可能なら）
• endpoint
• latency_ms

メトリクス

最低限:

• RPS
• エラー率（4xx/5xx）
• P50/P95/P99 latency
• DB遅延
• 外部API失敗率

トレース

OpenTelemetry で endpoint → service → DB をつなぐと、障害切り分けが劇的に速くなります。

7. デプロイ戦略：壊さずに出す

推奨は Blue/Green か Canary。FastAPI 単体の問題より、周辺設定差異が事故の原因になります。

リリース前チェックリスト:

1. DB migration の後方互換性
2. 依存ライブラリ脆弱性スキャン
3. load test（代表3API）
4. rollback 手順の実行確認
5. feature flag で段階有効化

8. 運用で効くインシデント訓練

月1回、次の擬似障害を実施すると運用強度が上がります。

• DB遅延 3秒化
• 外部API 30% 失敗
• メモリリーク発生
• JWT鍵ローテーション失敗

重要なのは、復旧時間だけでなく「誰が何を見て判断したか」を記録することです。Runbook の更新まで含めて初めて訓練が完結します。

9. すぐ使える最小ハードニングチェック

• Host ヘッダ制限
• JWT iss/aud/exp/nbf 検証
• 全エンドポイントに認可 dependency
• 外部API timeout/retry/circuit breaker
• JSON 構造化ログ + trace_id
• P95 latency 監視とアラート
• rollback 手順が5分で実行可能

この 7 項目が揃うだけで、障害時の被害規模は大きく下がります。

まとめ

FastAPI は高速開発の武器ですが、本番運用では「早く作る」より「安全に壊れる」設計が重要です。入口防御、認証認可、性能制御、観測性、リリース運用をセットで整備すれば、チームは安心して機能開発に集中できます。

もし何から始めるか迷うなら、まずは trace_id 付きの構造化ログと timeout 統一から着手してください。最小の投資で、運用の見通しが一気に良くなります。

10. セキュアな開発フローを維持するためのCI設定

本番ハードニングはコードだけでなく、CI フローで担保する必要があります。推奨するジョブは次の通りです。

1. 依存脆弱性スキャン（pip-audit / osv-scanner）
2. SAST（bandit など）
3. 型チェック（mypy）
4. 負荷テストのスモーク（k6）
5. OpenAPI 差分チェック（破壊的変更検出）

特に OpenAPI 差分チェックは有効です。意図しないレスポンス変更を早期に検知でき、フロントエンド障害を防げます。

11. バックアップと復旧を設計に含める

API 運用は「壊れない」ではなく「壊れても戻せる」が現実的です。最低限次を決めておきます。

• DB バックアップ頻度（例: 15分ごと増分、日次フル）
• 復旧目標（RTO/RPO）
• 復旧手順の担当と実行順

復旧訓練をしていないバックアップは、存在しないのと同じです。四半期に一度は検証環境でリストア演習を行ってください。

12. 監査対応を見据えたログ保全

B2B API では監査要件が後から増えることが多いです。最初から次を満たす設計にしておくと後で困りません。

• 監査ログとアプリログを分離
• 重要操作（権限変更、削除、課金操作）の証跡保存
• ログ保持期間の明確化（例: 180日）
• 改ざん検知（WORM ストレージや署名）

「誰が、いつ、何をしたか」を追えることは、障害解析だけでなく法務リスク低減にも直結します。

最終まとめ

FastAPI の本番運用は、フレームワーク知識だけでは足りません。セキュリティ、性能、可観測性、復旧性を一体で設計することが重要です。チェックリスト化し、CI と運用手順へ落とし込むことで、安定した開発速度を維持できます。