# セキュリティ設計書

## 概要

本ドキュメントは、InvenTreeシステムのセキュリティ設計について記載する。InvenTreeはDjango REST Frameworkをベースとした在庫管理システムであり、多層的なセキュリティ対策を実装している。本設計書では、認証・認可、通信セキュリティ、データ保護、入出力対策、監査ログについて詳述する。

## 認証設計

### 認証方式

InvenTreeは複数の認証方式をサポートしており、ユーザーの利用環境に応じた柔軟な認証が可能である。

| 認証方式 | 説明 | 実装箇所 |
| --- | --- | --- |
| セッション認証 | Django標準のセッションベース認証 | `rest_framework.authentication.SessionAuthentication` |
| APIトークン認証 | カスタムトークンによるAPI認証（有効期限・無効化対応） | `users.authentication.ApiTokenAuthentication` |
| Basic認証 | HTTP Basic認証 | `rest_framework.authentication.BasicAuthentication` |
| OAuth2認証 | OAuth2プロバイダーによる認証 | `oauth2_provider.backends.OAuth2Backend` |
| LDAP認証 | LDAPディレクトリサービスとの連携認証 | `django_auth_ldap.backend.LDAPBackend`（オプション） |
| SSO認証 | django-allauthによるソーシャルログイン | `allauth.account.auth_backends.AuthenticationBackend` |
| リモートユーザー認証 | プロキシサーバー経由のヘッダーベース認証 | `InvenTree.middleware.InvenTreeRemoteUserMiddleware` |
| マジックリンク認証 | django-sesameによるワンタイムリンク認証 | `sesame.backends.ModelBackend` |

### APIトークン認証の詳細

APIトークンは以下の特徴を持つ：

- **トークン形式**: `inv-{ランダム文字列}-{作成日}` 形式のカスタムプレフィックス付きトークン
- **有効期限**: デフォルト365日、カスタム設定可能
- **無効化機能**: `revoked`フラグによる即座の無効化
- **最終利用日追跡**: `last_seen`フィールドによる利用状況監視
- **トークン秘匿化**: 表示時は中間部分をマスク（`inv-xxxx****xxxx-YYYYMMDD`形式）

### 多要素認証（MFA）

InvenTreeはdjango-allauth MFAを利用した多要素認証をサポートする。

| MFA方式 | 説明 |
| --- | --- |
| TOTP | 時間ベースのワンタイムパスワード（Google Authenticator等） |
| リカバリーコード | バックアップ用の静的コード |
| WebAuthn | FIDO2/パスキーによる生体認証・セキュリティキー |

MFAの強制設定は `LOGIN_ENFORCE_MFA` グローバル設定により制御可能。

### セッション管理

| 項目 | 設定値 | 備考 |
| --- | --- | --- |
| セッション有効期限 | Django標準設定に準拠 | カスタマイズ可能 |
| セッション固定化対策 | 実装済み | django-allauthによるセッション管理 |
| セッションCookie SameSite | 設定可能（Lax/Strict/None） | `INVENTREE_COOKIE_SAMESITE`で制御 |
| セッションCookie Secure | 本番環境で自動有効化 | DEBUG=Falseで有効 |
| ユーザーセッション追跡 | 有効 | `allauth.usersessions`によるDB管理 |

### パスワードポリシー

Django標準のパスワードバリデーターを使用：

- `UserAttributeSimilarityValidator`: ユーザー属性との類似性チェック
- `MinimumLengthValidator`: 最小長チェック
- `CommonPasswordValidator`: 一般的なパスワードの拒否
- `NumericPasswordValidator`: 数字のみのパスワード拒否

### ログイン試行制限

django-allauthのレート制限機能により、ブルートフォース攻撃を防止：

- デフォルト: 5回/分のログイン失敗でレート制限
- `INVENTREE_LOGIN_ATTEMPTS`設定でカスタマイズ可能

## 認可設計

### 権限体系

InvenTreeはロールベースのアクセス制御（RBAC）を実装している。

| ロール | 権限 | 説明 |
| --- | --- | --- |
| admin | 全モデルへのフルアクセス | ユーザー・グループ・プラグイン・レポート等の管理 |
| part_category | 部品カテゴリの管理 | 部品カテゴリ・パラメータテンプレートの操作 |
| part | 部品の管理 | 部品・BOM・価格・サプライヤー部品の操作 |
| stock_location | 在庫場所の管理 | 在庫ロケーション・タイプの操作 |
| stock | 在庫アイテムの管理 | 在庫アイテム・追跡・テスト結果の操作 |
| build | 製造オーダーの管理 | ビルドオーダー・ビルドライン・ビルドアイテムの操作 |
| purchase_order | 購買オーダーの管理 | 購買オーダー・発注明細の操作 |
| sales_order | 販売オーダーの管理 | 販売オーダー・出荷の操作 |
| return_order | 返品オーダーの管理 | 返品オーダー・明細の操作 |

各ロールは以下の権限を個別に設定可能：
- `can_view`: 閲覧権限
- `can_add`: 追加権限
- `can_change`: 変更権限
- `can_delete`: 削除権限

### アクセス制御

REST Framework権限クラスによる多層的なアクセス制御：

| 権限クラス | 説明 |
| --- | --- |
| `IsAuthenticated` | 認証済みユーザーのみアクセス可能 |
| `ModelPermission` | Djangoモデル権限に基づくアクセス制御 |
| `RolePermission` | InvenTreeロールに基づくアクセス制御 |
| `InvenTreeTokenMatchesOASRequirements` | OAuth2スコープによるアクセス制御 |
| `IsSuperuserOrSuperScope` | スーパーユーザーまたは管理者スコープ必須 |
| `GlobalSettingsPermissions` | グローバル設定の変更はスタッフのみ |

### OAuth2スコープ

OAuth2トークンはきめ細かなスコープ制御をサポート：

- `read`: 読み取り専用アクセス
- `staff`: スタッフレベルアクセス
- `superuser`: 管理者レベルアクセス
- 各ロール・モデルに対応したきめ細かなスコープ

## 通信セキュリティ

| 項目 | 対策 |
| --- | --- |
| HTTPS | 本番環境では必須（`INVENTREE_SITE_URL`でhttps://指定） |
| HSTS | 設定により有効化可能 |
| Secure Cookie | 本番環境で自動有効化（`SESSION_COOKIE_SECURE`） |
| X-Forwarded-Proto | プロキシ環境での対応（`INVENTREE_USE_X_FORWARDED_PROTO`） |

### CORS設定

Cross-Origin Resource Sharingの制御：

| 設定項目 | 説明 |
| --- | --- |
| `CORS_ALLOW_ALL_ORIGINS` | 全オリジン許可（DEBUGモードのみ推奨） |
| `CORS_ALLOWED_ORIGINS` | 許可するオリジンのホワイトリスト |
| `CORS_ALLOWED_ORIGIN_REGEXES` | 許可するオリジンの正規表現パターン |
| `CORS_ALLOW_CREDENTIALS` | 認証情報の送信許可 |
| `CORS_URLS_REGEX` | CORS適用対象URL（`/api/`, `/auth/`, `/media/`, `/plugin/`, `/static/`） |

## データセキュリティ

### 暗号化

| 対象 | 暗号化方式 |
| --- | --- |
| 通信 | TLS 1.2以上（HTTPS） |
| パスワード | Django標準ハッシュ（PBKDF2-SHA256） |
| セッションデータ | Djangoセッションフレームワーク（署名付き） |
| OIDCキー | RSA 4096ビット秘密鍵 |

### 機密情報管理

**SECRET_KEY管理**:
1. 環境変数 `INVENTREE_SECRET_KEY` で直接指定
2. ファイルパス `INVENTREE_SECRET_KEY_FILE` で指定
3. デフォルトファイル `secret_key.txt` からの読み込み
4. 存在しない場合は100文字のランダムキーを自動生成

**データベース接続情報**:
- 環境変数または`config.yaml`で管理
- パスワードは平文で保存されるため、適切なファイル権限管理が必要

**APIトークン**:
- データベースに保存（表示時はマスク処理）
- 有効期限と無効化機能による制御

### バックアップセキュリティ

- GPG暗号化オプション（`DBBACKUP_GPG_RECIPIENT`設定）
- 外部ストレージ（S3等）へのバックアップ対応

## 入出力対策

| 脅威 | 対策 |
| --- | --- |
| XSS | django-markdownifyによるHTML出力サニタイズ、SVGファイルのbleachサニタイズ |
| SQLインジェクション | Django ORMによるパラメータ化クエリ |
| CSRF | Django CSRFミドルウェア、SameSite Cookie設定 |
| クリックジャッキング | X-Frame-Optionsミドルウェア（`XFrameOptionsMiddleware`） |
| パストラバーサル | ファイルパス検証、メディアファイルの適切な配置 |
| オープンリダイレクト | allauth CustomLoginFormによるリダイレクト検証 |

### SVGサニタイズ

アップロードされたSVGファイルはbleachライブラリにより以下の処理を実施：

- 許可されたHTML要素のみ保持（`ALLOWED_ELEMENTS_SVG`で定義）
- 許可された属性のみ保持（`ALLOWED_ATTRIBUTES_SVG`で定義）
- JavaScriptイベントハンドラの除去
- CSSインジェクション防止（`CSSSanitizer`使用）

### 入力バリデーション

- Django REST Frameworkシリアライザーによる入力検証
- カスタムバリデーター（`InvenTree/validators.py`、各アプリの`validators.py`）
- URLバリデーション（追加スキーム対応: `EXTRA_URL_SCHEMES`）

## CSRF対策

| 設定項目 | 値 |
| --- | --- |
| CSRFヘッダー名 | `X-CSRFTOKEN` |
| CSRFクッキー名 | `csrftoken` |
| CSRF信頼オリジン | `INVENTREE_TRUSTED_ORIGINS`設定で管理 |
| SameSite設定 | Lax/Strict/None（設定可能） |

## 監査ログ

| ログ種別 | 記録内容 | 保持期間 |
| --- | --- | --- |
| エラーログ | アプリケーションエラー（error_report） | 設定依存 |
| 認証ログ | ログイン成功・失敗、SSO認証エラー | structlogによる記録 |
| APIアクセスログ | リクエスト情報（django_structlog） | 設定依存 |
| 在庫追跡ログ | StockItemTracking（在庫移動履歴） | 永続 |
| トークン利用ログ | APIトークンの最終利用日 | 永続 |

### 構造化ログ

structlogによる構造化ログ出力：

- JSON形式またはコンソール形式選択可能
- タイムスタンプ、ログレベル、イベント情報を含む
- ファイル出力オプション（`INVENTREE_WRITE_LOG`）
- OpenTelemetryトレーシング対応（`INVENTREE_TRACING_ENABLED`）

### Sentry統合

エラー追跡サービスSentryとの統合：

- 本番環境での例外自動報告
- サンプリングレート設定可能
- 環境タグ（testing, docker, debug, remote, commit）の自動付与

## ミドルウェアスタック

セキュリティ関連ミドルウェアの適用順序：

1. `SecurityMiddleware` - Djangoセキュリティヘッダー
2. `XForwardedForMiddleware` - プロキシIPアドレス処理
3. `SessionMiddleware` - セッション管理
4. `UserSessionsMiddleware` - ユーザーセッション追跡
5. `CsrfViewMiddleware` - CSRF保護
6. `CorsMiddleware` - CORS処理
7. `AuthenticationMiddleware` - 認証処理
8. `InvenTreeRemoteUserMiddleware` - リモートユーザー認証
9. `AccountMiddleware` - allauth認証
10. `XFrameOptionsMiddleware` - クリックジャッキング対策
11. `AuthRequiredMiddleware` - 認証必須チェック
12. `Check2FAMiddleware` - MFA強制チェック
13. `OAuth2TokenMiddleware` - OAuth2トークン処理
14. `InvenTreeHostSettingsMiddleware` - ホスト設定検証

## ホスト設定検証

`InvenTreeHostSettingsMiddleware`による以下の検証：

- アクセスURLと`SITE_URL`設定の一致確認
- `CSRF_TRUSTED_ORIGINS`との整合性チェック
- プロトコル（HTTP/HTTPS）の検証（`SITE_LAX_PROTOCOL_CHECK`で緩和可能）

## 備考

### 推奨セキュリティ設定（本番環境）

1. `DEBUG = False` を設定
2. `INVENTREE_SITE_URL`をhttps://で設定
3. `ALLOWED_HOSTS`を適切に制限
4. `CSRF_TRUSTED_ORIGINS`を設定
5. `SECRET_KEY`を安全に管理
6. データベース接続にSSL使用
7. MFAを有効化（`INVENTREE_MFA_ENABLED = True`）
8. ログインレート制限を設定
9. 定期的なバックアップ実施

### セキュリティ関連設定ファイル

| ファイル | 説明 |
| --- | --- |
| `config.yaml` | メイン設定ファイル |
| `secret_key.txt` | Django SECRET_KEY |
| `oidc.pem` | OIDC用RSA秘密鍵 |
| `plugins.txt` | プラグイン定義 |

### 関連コードファイル

| ファイル | 説明 |
| --- | --- |
| `InvenTree/settings.py` | Django設定（セキュリティ設定含む） |
| `InvenTree/middleware.py` | カスタムミドルウェア |
| `InvenTree/permissions.py` | 権限クラス定義 |
| `InvenTree/sanitizer.py` | 入力サニタイズ |
| `users/authentication.py` | 認証クラス |
| `users/models.py` | ユーザーモデル・APIトークン |
| `users/permissions.py` | 権限チェック関数 |
| `users/ruleset.py` | ロールセット定義 |
