# セキュリティガードレール
このMCPサーバーには、事故を防ぐための複数のセキュリティ機構が組み込まれています。
## 1. 機能フラグによる制御
### デフォルトで無効な操作
| 操作 | 環境変数 | リスク |
|------|----------|--------|
| Gmail送信 | `GMAIL_SEND_ENABLED` | 誤送信、なりすまし |
| Gmail削除 | `GMAIL_DELETE_ENABLED` | データ損失 |
| Gmailラベル変更 | `GMAIL_MODIFY_LABELS_ENABLED` | 整理の混乱 |
| Drive削除 | `DRIVE_DELETE_ENABLED` | データ損失 |
| Calendar書き込み | `CALENDAR_WRITE_ENABLED` | 予定の誤作成 |
### 有効化の方法
`.env` ファイルで明示的に有効化:
```bash
# 例: Gmailのラベル変更を有効化
GMAIL_MODIFY_LABELS_ENABLED=true
```
### 本番環境での推奨設定
```bash
# 読み取り専用モード
GMAIL_READONLY=true
GMAIL_SEND_ENABLED=false
GMAIL_DELETE_ENABLED=false
GMAIL_MODIFY_LABELS_ENABLED=false
DRIVE_WRITE_ENABLED=false
DRIVE_DELETE_ENABLED=false
CALENDAR_READ_ENABLED=true
CALENDAR_WRITE_ENABLED=false
```
## 2. Dry-Run モード
Calendar の作成・更新は、デフォルトで **dry-run モード** で動作します。
### 動作
```typescript
// dryRun: true (デフォルト)
calendar_create_event({
event: { summary: "会議", startISO: "...", endISO: "..." }
})
// → { planned: { summary: "会議", ... } } // 計画のみ返却、実際には作成されない
// dryRun: false
calendar_create_event({
event: { summary: "会議", startISO: "...", endISO: "..." },
dryRun: false
})
// → { created: { id: "xxx", url: "..." } } // 実際に作成
```
### 設定
```bash
# dry-run をデフォルトにする（推奨）
CALENDAR_DRY_RUN_DEFAULT=true
# dry-run を無効にする（危険）
CALENDAR_DRY_RUN_DEFAULT=false
```
## 3. フォルダ制限 (Allowlist)
Drive/Sheets/Docs の操作対象フォルダを制限できます。
### 設定
```bash
# 許可するフォルダIDをカンマ区切りで指定
DRIVE_ALLOWLIST_FOLDERS=folder-id-1,folder-id-2
```
### 動作
- 空の場合: すべてのフォルダにアクセス可能
- 設定されている場合: 指定フォルダ以外への書き込み操作はブロック
### 推奨
Service Account 運用時は **必ず設定** してください。
## 4. 監査ログ
### 記録内容
すべてのツール呼び出しは `logs/audit-YYYY-MM-DD.jsonl` に記録されます:
```json
{
"timestamp": "2024-01-15T10:30:00.000Z",
"level": "info",
"tool": "gmail_search_messages",
"action": "search",
"args": { "query": "is:unread", "maxResults": 10 },
"result": "success",
"duration_ms": 234
}
```
### 機密情報のマスク
以下のフィールドは自動的にマスクされます:
- password
- token
- secret
- apiKey / api_key
- accessToken / access_token
- refreshToken / refresh_token
- privateKey / private_key
- credential
### ログの確認
```bash
# 今日のログを確認
cat logs/audit-$(date +%Y-%m-%d).jsonl | jq .
# エラーのみ抽出
cat logs/audit-*.jsonl | jq 'select(.level == "error")'
# 特定ツールの使用状況
cat logs/audit-*.jsonl | jq 'select(.tool == "calendar_create_event")'
```
## 5. エラーハンドリング
### Google API エラーの変換
```
400 Bad Request → 入力パラメータエラー
401 Unauthorized → 認証エラー（トークン期限切れなど）
403 Forbidden → 権限エラー
404 Not Found → リソースが見つからない
429 Too Many Requests → レート制限
500+ Server Error → Google側のエラー
```
### ユーザーへのフィードバック
エラーは構造化されたJSONで返却:
```json
{
"error": {
"name": "GoogleAPIError",
"message": "File not found: abc123",
"code": "GOOGLE_API_ERROR_404",
"details": { ... }
}
}
```
## 6. 認証情報の保護
### .gitignore
以下は必ず Git 管理から除外:
```
.env
.secrets/
logs/
*.pem
*.key
credentials.json
token.json
service-account.json
```
### ファイル権限
```bash
chmod 600 .secrets/*
```
### 環境変数での設定
機密情報は `.env` ファイルではなく、環境変数で直接設定することも可能:
```bash
export OAUTH_CLIENT_ID=xxx
export OAUTH_CLIENT_SECRET=xxx
```
## 7. スコープの最小化
デフォルトで使用されるスコープ:
| スコープ | 説明 | リスク |
|----------|------|--------|
| `gmail.readonly` | メール読み取り | 低 |
| `drive` | ファイル操作 | 中 |
| `spreadsheets` | スプレッドシート操作 | 中 |
| `documents` | ドキュメント操作 | 中 |
| `calendar` | カレンダー操作 | 中 |
### 不要なスコープの削除
`.env` で必要なスコープのみ指定:
```bash
GOOGLE_SCOPES=https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/calendar.readonly
```
## チェックリスト
- [ ] 破壊的操作のフラグを確認
- [ ] Dry-run がデフォルトになっているか確認
- [ ] Service Account 運用時は `DRIVE_ALLOWLIST_FOLDERS` を設定
- [ ] `.secrets/` のパーミッションを確認
- [ ] ログディレクトリが適切に保護されているか確認
- [ ] 不要なスコープを削除
- [ ] 定期的にログを監査
