# セキュリティガイド

マーケットプレイス版 AGENTIC STAR のセキュリティ構成と、本番環境に向けた強化手順を解説します。

## 初期構成の方針

マーケットプレイス版は**最小コストで導入可能な構成**がデフォルトです。全コンポーネントが単一レプリカ（replica=1）で構成されており、購入後にセキュリティ・可用性要件に応じて段階的にスケールアップできます。

## ゼロトラスト通信アーキテクチャ

AGENTIC STAR は、ゼロトラストセキュリティモデルに基づく通信アーキテクチャを採用しています。

marketplace-agent namespace 内の Pod には Envoy サイドカープロキシが自動注入され、アウトバウンド通信は Envoy を経由して ExtAuth Service（外部認可サービス）による認可制御を受けます。

| コンポーネント                     | 役割                                                     |
| --------------------------- | ------------------------------------------------------ |
| **Envoy Injection Webhook** | Pod 作成時に Envoy サイドカーコンテナを自動注入する MutatingWebhook        |
| **Envoy サイドカー**             | 各 Pod 内でアウトバウンド通信をインターセプトし、ExtAuth Service に認可リクエストを送信 |
| **ExtAuth Service**         | 認可ポリシーに基づき通信の許可/拒否を判定する外部認可サービス                        |

## セキュリティ構成レベル

AGENTIC STAR では、セキュリティと可用性の要件に応じて 3 つの構成レベルを定義しています。

| レベル         | 名称          | replica | FailurePolicy | AntiAffinity | PDB | ゼロトラスト保証    |
| ----------- | ----------- | ------- | ------------- | ------------ | --- | ----------- |
| **Level 1** | 初期構成（デフォルト） | 1       | Ignore        | なし           | なし  | ベストエフォート    |
| **Level 2** | 推奨構成        | 2       | Fail          | あり           | あり  | 保証あり        |
| **Level 3** | 本番構成        | 3+      | Fail          | あり           | あり  | 保証あり + 高可用性 |

### ゼロトラスト保証レベルの違い

- **ベストエフォート** — 正常時は Envoy 経由の通信が保証されますが、Webhook 障害時にサイドカー未注入の Pod が起動する可能性があります
- **保証あり** — Webhook 障害時は Pod 作成自体がブロックされるため、サイドカー未注入の状態は発生しません

### 各レベルの推奨用途

| レベル         | 推奨用途             | 説明                                      |
| ----------- | ---------------- | --------------------------------------- |
| **Level 1** | 開発環境、PoC、機能検証    | コスト最適化を優先。セキュリティ要件が厳しくない環境向け            |
| **Level 2** | 本番環境の最小構成        | ゼロトラスト通信が保証される最小構成。本番環境での利用を開始する際の推奨レベル |
| **Level 3** | ミッションクリティカルな本番環境 | 高可用性を備えたゼロトラスト保証構成。サービスの継続性が重要なワークロード向け |

## 初期構成（Level 1）の制約事項

初期構成は**コスト最適化を優先**しており、以下の制約があります。本番環境での利用には Level 2 以上へのアップグレードを強く推奨します。

### 単一レプリカ構成のリスク

| コンポーネント                      | 初期構成              | 障害時のリスク          |
| ---------------------------- | ----------------- | ---------------- |
| **ExtAuth Service**          | replica=1, PDB 無効 | ゼロトラスト認可が停止      |
| **Envoy Injection Webhook**  | replica=1, PDB 無効 | サイドカー未注入 Pod が起動 |
| **NGINX Ingress Controller** | replica=1         | 全外部アクセスが停止       |
| **Keycloak（認証基盤）**           | replica=1         | ユーザー認証が不可        |
| **Gate Services（ルーティング）**    | replica=1         | API 経路が停止        |

### Envoy Injection Webhook の制約

初期構成では `failurePolicy: Ignore` が設定されています。Webhook Pod が障害やノードメンテナンスにより停止した場合、サイドカーなしで起動した Pod は認可制御をバイパスして外部サービスと直接通信できる状態になります。この状態は Pod が再起動されるまで継続します。

### NetworkPolicy 未適用

初期構成では NetworkPolicy が適用されていません。クラスター内の任意の Pod から任意のサービスへの通信が可能な状態です。

## コンポーネント別セキュリティ推奨値

### セキュリティ基盤

**ExtAuth Service**

| 設定項目                      | Level 1 | Level 2 | Level 3 |
| ------------------------- | ------- | ------- | ------- |
| `replicaCount`            | 1       | 2       | 3       |
| `autoscaling.minReplicas` | 1       | 2       | 3       |
| `pdb.enabled`             | false   | true    | true    |
| `pdb.minAvailable`        | —       | 1       | 1       |

**Envoy Injection Webhook**

| 設定項目                             | Level 1 | Level 2  | Level 3  |
| -------------------------------- | ------- | -------- | -------- |
| `webhook.replicaCount`           | 1       | 2        | 2        |
| `webhook.pdb.enabled`            | false   | true     | true     |
| `webhook.pdb.minAvailable`       | —       | 1        | 1        |
| `webhook.mutating.failurePolicy` | Ignore  | **Fail** | **Fail** |

> **危険**
>
> `failurePolicy: Fail` に変更する場合、Webhook のレプリカ数を必ず 2 以上にしてください。単一レプリカで `Fail` に設定すると、Webhook 障害時にすべての Pod 作成がブロックされます。

### 認証・ルーティング

**Keycloak**

| 設定項目              | Level 1 | Level 2 | Level 3 |
| ----------------- | ------- | ------- | ------- |
| `replicas`        | 1       | 2       | 3       |
| JDBC-ping クラスタリング | 不要      | 有効（自動）  | 有効（自動）  |

> **注記**
>
> Keycloak は replicas=2 以上で JDBC-ping によるクラスタリングが自動有効化されます。セッション共有が行われるため、1 台の障害時でも認証セッションが継続します。

**NGINX Ingress Controller**

| 設定項目                       | Level 1 | Level 2 | Level 3 |
| -------------------------- | ------- | ------- | ------- |
| `autoscaling.minReplicas`  | 1       | 2       | 3       |
| `autoscaling.maxReplicas`  | 5       | 5       | 10      |
| `autoscaling.targetCPU`    | 70%     | 70%     | 70%     |
| `autoscaling.targetMemory` | 80%     | 80%     | 80%     |

**Gate Services**

| 設定項目                      | Level 1 | Level 2 | Level 3 |
| ------------------------- | ------- | ------- | ------- |
| `autoscaling.minReplicas` | 1       | 2       | 2       |

### アプリケーション

**Agent Executor / AgenticAI Admin / AgenticAI ExtAPI**

| 設定項目                      | Level 1 | Level 2 | Level 3 |
| ------------------------- | ------- | ------- | ------- |
| `autoscaling.minReplicas` | 1       | 2       | 2       |

### データストア

**Qdrant（ベクトル DB）**

| 設定項目                   | Level 1 | Level 2 | Level 3          |
| ---------------------- | ------- | ------- | ---------------- |
| `replicaCount`         | 1       | 1       | 3（cluster: true） |
| `cluster`              | false   | false   | true             |
| `loadBalancer.enabled` | false   | false   | false            |
| `dashboard.enabled`    | false   | false   | false            |

> **危険**
>
> `loadBalancer.enabled` および `dashboard.enabled` は、本番環境では必ず `false` にしてください。有効化すると Qdrant への外部アクセスが可能になり、ベクトルデータの漏洩リスクがあります。

**MongoDB**

| 設定項目                    | Level 1 | Level 2 | Level 3 |
| ----------------------- | ------- | ------- | ------- |
| `podAntiAffinityPreset` | soft    | soft    | hard    |

### 監視基盤

**Prometheus**

| 設定項目                           | Level 1 | セキュリティ推奨   |
| ------------------------------ | ------- | ---------- |
| `securityContext.runAsNonRoot` | true    | 維持（変更不要）   |
| `securityContext.runAsUser`    | 1000    | 維持（変更不要）   |
| `securityContext.fsGroup`      | 2000    | 維持（変更不要）   |
| `retention`                    | 30d     | 監査要件に応じて延長 |
| `storage`                      | 50Gi    | データ量に応じて増量 |

**Loki**

| 設定項目               | Level 1 | セキュリティ推奨           |
| ------------------ | ------- | ------------------ |
| `auth_enabled`     | false   | 本番環境では `true` を検討  |
| `retention_period` | 7d      | 監査要件に応じて延長（30d 以上） |
| `storage`          | 10Gi    | ログ量に応じて増量          |

## NetworkPolicy によるネットワーク分離

初期構成では NetworkPolicy が含まれていません。クラスターのセキュリティ要件に応じて、以下の NetworkPolicy の適用を推奨します。

> **前提条件**
>
> NetworkPolicy の動作には、CNI プラグイン（Calico / Cilium 等）の対応が必要です。AGENTIC STAR の AKS クラスタは Calico が有効化されており、NetworkPolicy をそのまま適用できます。

### Qdrant アクセス制限

Qdrant にはベクトル化されたデータが格納されており、不正アクセスによるデータ漏洩を防ぐためアクセス元を制限します。

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: qdrant-allow-authorized-only
  namespace: qdrant
spec:
  podSelector:
    matchLabels:
      app: qdrant
  policyTypes:
    - Ingress
  ingress:
    # namespace 内通信（クラスター P2P）
    - from:
        - podSelector: {}
    # 許可された外部 namespace からのアクセス
    - from:
        - namespaceSelector:
            matchLabels:
              name: agent-executor
      ports:
        - port: 6333
          protocol: TCP
        - port: 6334
          protocol: TCP
```

> **ヒント**
>
> Qdrant Helm chart の `networkPolicy.enabled: true` と `networkPolicy.allowedNamespaces` を設定することで、同等の NetworkPolicy を Helm 経由で適用することも可能です。

### データベースアクセス制限

PostgreSQL へのアクセスを必要なコンポーネントのみに制限します。

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: restrict-postgresql-access
  namespace: autonomous-agent
spec:
  podSelector:
    matchLabels:
      app: postgresql
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: agent-executor
        - namespaceSelector:
            matchLabels:
              name: agenticai-admin
        - namespaceSelector:
            matchLabels:
              name: gate-services
      ports:
        - port: 5432
          protocol: TCP
```

### ExtAuth Service へのアクセス制限

ExtAuth Service は認可制御の中核であるため、Envoy サイドカーからのみアクセスを許可します。

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: extauth-service-allow-envoy-only
  namespace: proxy-system
spec:
  podSelector:
    matchLabels:
      app: extauth-service
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              sidecar: envoy
```

### 監視基盤のアクセス制限

Prometheus / Loki などの監視基盤へのアクセスを制限し、メトリクス・ログデータの漏洩を防ぎます。

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: prometheus-allow-internal-only
  namespace: observability
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: prometheus
  policyTypes:
    - Ingress
  ingress:
    # Grafana / Alertmanager からのアクセス
    - from:
        - podSelector: {}
    # Alloy からの Remote Write
    - from:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              app.kubernetes.io/name: alloy
      ports:
        - port: 9090
          protocol: TCP
```

## TLS / SSL 設定

初期構成では自己署名証明書が使用されています。本番環境ではカスタムドメインと正規 SSL 証明書の設定が必要です。

ドメインの取得、DNS 設定、SSL 証明書の設定手順については[ドメイン設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/guide/domain-guide.md)を参照してください。

## アップグレード手順

### Level 1 → Level 2（推奨構成）

#### Step 1: ExtAuth Service の values 上書きファイルを作成

```yaml
# security-upgrade-values.yaml
# Level 2: 推奨構成（ゼロトラスト保証あり）

replicaCount: 2
autoscaling:
  minReplicas: 2

pdb:
  enabled: true
  minAvailable: 1

webhook:
  replicaCount: 2
  pdb:
    enabled: true
    minAvailable: 1
  mutating:
    failurePolicy: Fail
```

> **注記**
>
> AntiAffinity は Helm chart のデフォルト値（preferred）が自動的に適用されるため、明示的な上書きは不要です。

#### Step 2: 各コンポーネントのレプリカ数を引き上げ

以下の各コンポーネントの values ファイルで `minReplicas` を 2 以上に設定します。

```yaml
autoscaling:
  minReplicas: 2
```

対象コンポーネント:

- agent-executor
- agenticai-admin
- agenticai-extapi
- gate-services
- ingress-nginx
- librechat-auth（`replicas: 2`）

#### Step 3: Helm upgrade を実行

```bash
helm upgrade extauth-service ./extauth-service \
  -n proxy-system \
  -f current-values.yaml \
  -f security-upgrade-values.yaml
```

#### Step 4: 変更を確認

```bash
# Pod 分散配置の確認
kubectl get pods -n proxy-system -o wide

# PDB 作成の確認
kubectl get pdb -n proxy-system

# FailurePolicy の確認
kubectl get mutatingwebhookconfiguration envoy-injector-webhook \
  -o jsonpath='{.webhooks[0].failurePolicy}'
# 期待値: Fail

# Envoy 注入の動作確認
kubectl rollout restart deployment/agent-executor -n agent-executor
kubectl get pods -n agent-executor
# 期待値: 全 Pod が READY 2/2
```

### Level 2 → Level 3（本番構成）

#### Step 1: values 上書きファイルを作成

```yaml
# production-values.yaml
# Level 3: 本番構成（高可用性）

replicaCount: 3
autoscaling:
  minReplicas: 3

webhook:
  replicaCount: 2
```

#### Step 2: Helm upgrade を実行

```bash
helm upgrade extauth-service ./extauth-service \
  -n proxy-system \
  -f current-values.yaml \
  -f security-upgrade-values.yaml \
  -f production-values.yaml
```

#### Step 3: 変更を確認

```bash
# extauth-service の Pod が 3 台起動していること
kubectl get pods -n proxy-system -l app=extauth-service

# webhook の Pod が 2 台起動していること
kubectl get pods -n proxy-system -l app=envoy-injector-webhook
```

## 本番環境セキュリティチェックリスト

### ゼロトラスト通信

- ExtAuth Service のレプリカ数が 2 以上であること
- Envoy Injection Webhook のレプリカ数が 2 以上であること
- `failurePolicy` が `Fail` に設定されていること
- PDB が有効化されていること
- 全ワークロード Pod で Envoy サイドカーが注入されていること（READY 2/2）

### ネットワーク分離

- Qdrant へのアクセスが必要な namespace のみに制限されていること
- PostgreSQL へのアクセスが必要なコンポーネントのみに制限されていること
- ExtAuth Service へのアクセスが Envoy サイドカーからのみに制限されていること

### TLS / 証明書

- 自己署名証明書から CA 発行証明書に置き換えられていること
- 全 Ingress で SSL リダイレクトが有効であること（デフォルト有効）
- 証明書の自動更新が設定されていること

### データストア

- Qdrant の `loadBalancer.enabled` が `false` であること
- Qdrant の `dashboard.enabled` が `false` であること
- PostgreSQL の接続情報が Kubernetes Secret で管理されていること

### 可用性

- 各コンポーネントのレプリカ数が 2 以上であること
- PDB が有効化されていること
- AntiAffinity により Pod が異なるノードに分散されていること

### 監視・ログ

- Prometheus のメトリクス保持期間が監査要件を満たしていること
- Loki のログ保持期間が監査要件を満たしていること
- アラート通知が適切に設定されていること

## 用語集

| 用語                            | 説明                                                                               |
| ----------------------------- | -------------------------------------------------------------------------------- |
| **FailurePolicy: Ignore**     | Webhook 障害時も Pod 作成を続行する設定。サイドカーが注入されないまま Pod が起動するリスクがある                        |
| **FailurePolicy: Fail**       | Webhook 障害時は Pod 作成を拒否する設定。サイドカー未注入の Pod は起動しないが、Webhook 障害中は新規 Pod の作成がブロックされる  |
| **PodDisruptionBudget (PDB)** | ノードメンテナンスやアップグレード時に、最低限の Pod 数を保証する仕組み                                           |
| **Pod AntiAffinity**          | 同一ワークロードの Pod を異なるノードに分散配置するための設定                                                |
| **NetworkPolicy**             | Kubernetes 標準のネットワークアクセス制御機能。Pod 間の通信を Ingress / Egress レベルで制限する。CNI プラグインの対応が必要 |
