security-patterns

セキュリティパターン

堅牢なアプリケーションを構築するための包括的なセキュリティパターンです。各カテゴリーには個別のルールファイルがあり、必要に応じて rules/ から読み込まれます。

クイックリファレンス

カテゴリー	ルール	影響度	使用する場面
認証	upstream	CRITICAL	JWT トークン、OAuth 2.1/PKCE、RBAC/権限
多層防御	1	CRITICAL	多層セキュリティ、ゼロトラストアーキテクチャ
入力検証	2	HIGH	スキーマ検証（Zod/Pydantic）、出力エンコーディング、ファイルアップロード
OWASP Top 10	1	CRITICAL	インジェクション対策、認証の不備の修正
LLM の安全性	refs	HIGH	プロンプトインジェクション対策、出力ガードレール、コンテンツフィルタリング
PII マスキング	refs	HIGH	Presidio、Langfuse、LLM Guard による PII の検出／編集
スキャン	upstream	HIGH	依存関係の監査、SAST（Semgrep/Bandit）、シークレット検出
高度なガードレール	2	CRITICAL	NeMo/Guardrails AI バリデーター、レッドチーミング、OWASP LLM

合計：4 カテゴリーにわたる 6 個のルールファイル。「upstream」または「refs」と記されたトピックでは、ここには ork の差分のみを記載しています。基準と重要な判断はこのファイルに、傷跡とプロジェクト固有の判断は references/ork-delta.md に、ファーストパーティの情報源は Upstream coverage に記載しています。

クイックスタート

# Argon2id password hashing
from argon2 import PasswordHasher
ph = PasswordHasher()
password_hash = ph.hash(password)
ph.verify(password_hash, password)

# JWT access token (15-min expiry)
import jwt
from datetime import datetime, timedelta, timezone
payload = {
    'sub': user_id, 'type': 'access',
    'exp': datetime.now(timezone.utc) + timedelta(minutes=15),
}
token = jwt.encode(payload, SECRET_KEY, algorithm='HS256')

// Zod v4 schema validation
import { z } from 'zod';
const UserSchema = z.object({
  email: z.email(),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin']).default('user'),
});
const result = UserSchema.safeParse(req.body);

# PII masking with Langfuse
import re
from langfuse import Langfuse

def mask_pii(data, **kwargs):
    if isinstance(data, str):
        data = re.sub(r'\b[\w.-]+@[\w.-]+\.\w+\b', '[REDACTED_EMAIL]', data)
        data = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[REDACTED_SSN]', data)
    return data

langfuse = Langfuse(mask=mask_pii)

認証

OAuth 2.1、Passkeys/WebAuthn、JWT トークン、ロールベースのアクセス制御による安全な認証です。

JWT、OAuth 2.1/PKCE/DPoP、Passkeys/WebAuthn、RBAC、MFA の実装チュートリアルは、upstream でカバーされています（Upstream coverage を参照）。argon2-cffi を passlib より優先する判断の経緯を含む ork の差分は、references/ork-delta.md に記載されています。

重要な判断： Argon2id > bcrypt | アクセストークンは 15 分 | PKCE 必須 | Passkeys > TOTP > SMS

多層防御

単一障害点のない多層セキュリティアーキテクチャです。

ルール	説明
defense-layers.md	8 層のセキュリティアーキテクチャ（エッジからオブザーバビリティまで）

ゼロトラストとテナント分離の実装レシピ（テナントスコープのリポジトリ、RLS、テナントキー付きキャッシュ）は、upstream でカバーされています。不変の RequestContext パターンは references/request-context-pattern.md に、サニタイズされた監査ログは references/audit-logging.md に残されています。

重要な判断： 不変のデータクラスコンテキスト | クエリレベルでのテナントフィルタリング | LLM プロンプトに ID を含めない

sandbox.network.deniedDomains（CC 2.1.113+）

Bash/WebFetch の外向き通信より前に適用されるネットワーク層のブロックリストです。多層防御のため、フック層の DENY_PATTERNS と組み合わせてください。設定例：

"sandbox": {
  "network": {
    "deniedDomains": ["*.evil.com", "pastebin.com", "transfer.sh"]
  }
}

ワイルドカードをサポートしています（*.example.com、evil.com/*/malicious/*）。プラグインには src/settings/ork.settings.json に基本リストが含まれており、プロジェクト設定で拡張できます。用途：プロンプトインジェクションによるデータ流出先、既知の悪意あるレジストリ、監査を回避するペーストサービス。

sandbox.credentials (CC 2.1.187+)

サンドボックス化された Bash が認証情報のファイルやシークレットの環境変数を読み取るのをブロックします。sandbox.filesystem.denyRead と併用する多層防御です。スコープ間でマージされ（どのスコープからでも追加でき、削除はできません）、古い CC ではこのキーは無視されます。mode は deny、または CC 2.1.221 以降では mask です。設定例：

"sandbox": {
  "credentials": {
    "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
    "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
  }
}

ork には sandbox.credentials のベースライン設定が含まれていません。CC はプラグインの設定ファイルから permissions キーのみを読み取るため、以前 src/settings/ork.settings.json にあったブロックは効果がないものとして #3357 で削除されました。ユーザー設定または管理設定で設定してください（~/.aws/credentials、~/.ssh、~/.gnupg、~/.netrc、~/.npmrc に加え、git-push の認証を乗っ取る可能性のあるトークン環境変数を拒否します）。CLAUDE_CODE_SUBPROCESS_ENV_SCRUB と併用すると、サンドボックス化の有無にかかわらず、すべてのサブプロセスの認証情報を消去できます。

拒否ではなくマスキング。 CC 2.1.221 以降、Linux および WSL では、認証情報のファイルエントリに mode: "mask" を指定できます。サンドボックス化されたコマンドはセンチネルコピー（ファイル全体、または extract 正規表現でキャプチャされた範囲のみ）を読み取り、サンドボックスプロキシが送信時に実際の値へ置き換えます。macOS ではファイルのマスキングは deny にフォールバックするため、Mac では mode: deny と比べて利点はありません。より高度なオプションは CC 2.1.224 で追加されました。mode: deny に加えて、認証情報をマスキングし、コマンドが秘匿化された値を使って実行を継続できるようになりました。extract と onExtractNoMatch は構造化された環境変数の値からシークレットを取り出し、decode: "jwt" と maskClaims は指定された JWT クレームをマスキングし、awsPairs／sigv4 はマスキング後に AWS SigV4 リクエストへ再署名します。これらを使用できるかどうかは、次の 2 つの制約で決まります。

• sandbox.network.tlsTerminate が必要なため、CC が終端するトラフィックにのみ適用されます。
• ユーザー設定、管理設定、または --settings からのみ有効になります。プラグインに含まれる値や、プロジェクトの .claude/settings.json で設定された値は無視されるため、ork は拒否リストのようにこれらをベースライン設定として提供できません。運用担当者向けに説明を記載してください。有効になると期待して src/settings/ork.settings.json に追加しないでください。

末尾にスラッシュが付いた拒否パスは絶対に記述しないでください。 CC 2.1.223 までは、末尾が / の sandbox.filesystem 拒否エントリ（たとえば denyRead: "~/.aws/"）は、Linux と macOS で黙って回避できました。ルールは解析され、問題なしと報告されますが、何も保護しませんでした。これは 2.1.224 で修正されましたが、どちらの書き方でも保護されているように見えるため、引き続きこの形式は避けてください。ork が提供する値（~/.aws/credentials、~/.ssh/*、~/.gnupg/*）には、影響はありませんでした。

入力の検証

Zod v4 と Pydantic を使用して、信頼できない入力をすべて検証・サニタイズしてください。

ルール	説明
validation-input.md	Zod v4 と Pydantic によるスキーマ検証、型変換
validation-output.md	HTML のサニタイズ、出力エンコーディング、XSS の防止

高度なスキーマのレシピ（判別可能なユニオン、ファイルアップロードの検証、URL の許可リスト） と Zod v4 の API 全般は上流でカバーされています。Zod v4 と v3 の取り違えに関する注意事項は references/ork-delta.md に、型付きスキーマの例は scripts/validation-schemas.ts にあります。

主な決定事項： ブロックリストより許可リスト | 常にサーバー側で検証 | 拡張子ではなくマジックバイトを検証

OWASP Top 10

最も重大な Web アプリケーションのセキュリティリスクから保護します。

ルール	説明
supply-chain.md	ロックファイルの整合性、依存関係の混同、来歴、SBOM（A03:2025）

インジェクション対策（SQL／コマンド／SSRF）、認証の不備への対処（JWT アルゴリズムの混同、 CSRF、タイミング攻撃）、および脆弱な実装と安全な実装のデモは上流でカバーされています。 上流でのカバー範囲を参照してください。

主な決定事項： パラメーター化クエリのみを使用 | JWT アルゴリズムをハードコード | SameSite=Strict Cookie

LLM の安全性

コンテキストの分離や出力の検証など、LLM との統合におけるセキュリティパターンです。

リファレンス	説明
references/context-separation.md	コンテキスト分離のアーキテクチャ、禁止パターン
references/prompt-audit.md	プロンプトの監査、安全なプロンプトビルダー
references/output-guardrails.md	出力の検証パイプライン：スキーマ、根拠付け、安全性、サイズ
references/pre-llm-filtering.md	テナントスコープの検索、コンテンツの抽出
references/post-llm-attribution.md	決定論的な帰属（3 フェーズパターン）

主な決定事項： ID は LLM を経由せず、その周囲を流す | 帰属は決定論的に行う | すべてのプロンプトを監査する

コンテキストの分離（重大）

機密性の高い ID とデータは、LLM を経由せず、その周囲を流します。LLM に見せるのはコンテンツのみで、エンティティとの対応付けはその後、決定論的に行います。

# CORRECT: IDs bypass the LLM
context = {"user_id": user_id, "tenant_id": tenant_id}  # kept server-side
llm_input = f"Summarize this document:\n{doc_text}"       # no IDs in prompt
llm_output = call_llm(llm_input)
result = {"summary": llm_output, **context}               # IDs reattached after

出力の検証パイプライン

すべての LLM レスポンスは、ユーザーに届く前に、必ず 4 段階のガードレールパイプラインを通過する必要があります。

def validate_llm_output(raw_output: str, schema, sources: list[str]) -> str:
    # 1. Schema — does it match expected structure?
    parsed = schema.parse(raw_output)
    # 2. Grounding — are claims supported by source documents?
    assert_grounded(parsed, sources)
    # 3. Safety — toxicity, PII leakage, prompt leakage
    assert_safe(parsed, max_toxicity=0.5)
    # 4. Size — prevent token-bomb responses
    assert len(parsed.text) < MAX_OUTPUT_CHARS
    return parsed.text

PII のマスキング

LLM の可観測性パイプラインとログ記録における、PII の検出とマスキングです。

リファレンス	説明
references/presidio-integration.md	Microsoft Presidio のセットアップ、カスタム認識器
references/langfuse-mask-callback.md	Langfuse SDK のマスク実装

LLM Guard の匿名化／匿名解除と、Vault および structlog/loguru の編集プロセッサーについては上流で扱われています。上流でのカバー範囲を参照してください。

主な決定事項： エンタープライズ向けには Presidio を使用 | 型トークンに置き換える | 初期化時にマスクコールバックを使用する

スキャン

依存関係、コード、シークレットを対象とする自動セキュリティスキャンです。ツールのチュートリアル（npm audit、pip-audit、Trivy、Semgrep、Bandit、Gitleaks、TruffleHog、detect-secrets）は上流で扱われています。実行可能な社内パイプラインは scripts/scan-vulnerabilities.sh にあり、助言ではなく強制されるリポジトリのゲート（プッシュ前のセキュリティスイート、CI の gitleaks）は references/ork-delta.md に記録されています。

主な決定事項： シフトレフトのためにコミット前フックを使用 | 重大／高リスクの場合はブロック | Gitleaks + detect-secrets のベースライン

高度なガードレール

NeMo Guardrails、Guardrails AI のバリデーター、DeepTeam によるレッドチームテストを用いた、本番環境向けの LLM 安全対策です。

ルール	説明
guardrails-nemo.md	NeMo Guardrails、Colang 2.0 のフロー、Guardrails AI のバリデーター、多層検証
guardrails-llm-validation.md	DeepTeam によるレッドチームテスト（40 以上の脆弱性）、OWASP LLM Top 10 への準拠

主な決定事項： フローには NeMo、バリデーターには Guardrails AI を使用 | 毒性のしきい値は 0.5 | リリース前および四半期ごとにレッドチームテストを実施

上流の対象範囲（再記述しないでください）

これらのトピックは、ベンダーの内容を再記述するものとして、このスキルから削除されました。一次情報源を参照してください。ここに記載するのは、ork の差分（最低基準、問題点、独自の判断）のみです。 references/ork-delta.md。

トピック	一次情報源
JWT の実装とパスワードのハッシュ化（PyJWT、Argon2id）	https://pyjwt.readthedocs.io/ + https://argon2-cffi.readthedocs.io/
OAuth 2.1、PKCE、DPoP、Passkeys/WebAuthn のフロー	https://oauth.net/2.1/ + https://www.w3.org/TR/webauthn-3/ + https://github.com/duo-labs/py_webauthn
RBAC デコレーター、MFA/TOTP、レート制限、認証チェックリスト	OWASP Cheat Sheet Series：https://cheatsheetseries.owasp.org/（Authentication、Session Management、MFA）
ゼロトラストのテナント分離（テナントスコープのリポジトリ、RLS、テナントキー付きキャッシュ）	PostgreSQL RLS：https://www.postgresql.org/docs/current/ddl-rowsecurity.html + OWASP LLM08：https://genai.owasp.org/
Zod v4 API とバリデーションのレシピ（型変換、ユニオン、ファイル／URL スキーマ）	https://zod.dev（context7: /colinhacks/zod） + https://docs.pydantic.dev/
OWASP Top 10 の脆弱な例と安全な例（インジェクション、XSS、CSRF、JWT の混乱、タイミング）	https://owasp.org/Top10/ + https://cheatsheetseries.owasp.org/
LLM のプロンプトインジェクション対策と出力ガードレールのチュートリアル	OWASP LLM Top 10：https://genai.owasp.org/llm-top-10/
LLM Guard による PII のサニタイズ（Anonymize/Deanonymize/Vault）	https://protectai.github.io/llm-guard/
structlog/loguru によるログ記録前の秘匿化	https://www.structlog.org/ + https://loguru.readthedocs.io/
依存関係、シークレット、SAST のスキャンツール	https://semgrep.dev/docs/ + https://github.com/gitleaks/gitleaks + https://trufflesecurity.com/trufflehog + https://bandit.readthedocs.io/

管理対象フックの階層（CC 2.1.49）

プラグインの設定には、次の3段階の優先順位があります。

階層	ソース	上書き可能か
1. 管理対象（プラグインの settings.json）	プラグイン作成者がデフォルトを同梱	はい、ユーザーが可能
2. プロジェクト（.claude/settings.json）	リポジトリの設定	はい、ユーザーが可能
3. ユーザー（~/.claude/settings.json）	個人設定	最終的な決定権

OrchestKit に同梱されているセキュリティフックは管理対象のデフォルト設定です。ユーザーは無効にできますが、警告が表示されます。エンタープライズ管理者は、管理対象プロファイルを使って設定をロックできます。

CC 2.1.166 — 管理対象設定の適用に関する修正： 2.1.166 より前は、管理対象設定に無効な項目が1つあるだけで、残りの有効なポリシーすべてへの適用が無言で無効になっていました。たった1つのタイプミスで、セキュリティロックダウン全体が無効になる可能性がありました。管理対象プロファイルを利用する場合は 2.1.166 以降を必須とし、デプロイ前にファイルを検証してください。同じリリースでは、${VAR} 参照を使用した場合に allowedMcpServers／deniedMcpServers の述語が一致しない問題も修正されました。

CC 2.1.160 — 書き込み時の確認プロンプト： Claude Code は、シェルの起動ファイル（.zshenv、.zlogin、.bash_login、~/.config/git/）と、コード実行を許可するビルドツール設定（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/）に書き込む前に、acceptEdits の場合も確認を求めるようになりました。これらは多層防御のデフォルト設定として扱い、無条件で許可するのではなく、意図を持って承認してください。

権限ルールのセマンティクス（≥ 2.1.166）： allow／ask／deny ルールに、セキュリティ上重要な動作が追加されました。Read の deny はファイルを Glob／Grep から隠すようになり、deny のツール名では glob（"*" = デフォルトで拒否）が使えるようになりました。明示的な WebFetch(domain:…) は事前承認済みホストへの自動許可より優先され、他のセッションから中継された SendMessage には権限がなく、組織が管理するルールはセッション全体に適用されます。モデルの全容と推奨される基本設定の settings.json については、references/cc-permission-model.md を参照してください。

セッション間の返信は親に届く（CC 2.1.248）： サブエージェントが別のセッションに SendMessage を送信すると、返信はサブエージェントではなく親セッションの会話に届きます。サブエージェントは送信後に処理を続け、親が返信を読みます。セッション間の SendMessage／ListAgents は、Bedrock、Vertex、Foundry でも、テレメトリーが無効な場合でも機能します（CC 2.1.248）。

アンチパターン（禁止）

# Authentication
user.password = request.form['password']       # Plaintext password storage
response_type=token                             # Implicit OAuth grant (deprecated)
return "Email not found"                        # Information disclosure

# Input Validation
"SELECT * FROM users WHERE name = '" + name + "'"  # SQL injection
if (file.type === 'image/png') {...}               # Trusting Content-Type header

# LLM Safety
prompt = f"Analyze for user {user_id}"             # ID in prompt
artifact.user_id = llm_output["user_id"]           # Trusting LLM-generated IDs

# PII
logger.info(f"User email: {user.email}")           # Raw PII in logs
get_client().start_observation(name="llm", input=raw_prompt)  # Unmasked observability data

詳細ドキュメント

Read("references/<file>") で必要に応じて読み込みます。

ファイル	内容
ork-delta.md	削除された上流ドキュメントの繰り返し記述から救出された、Ork 固有の教訓とチーム内の決定事項
cc-permission-model.md	CC の allow／ask／deny ルールのセマンティクス（≥2.1.166）：Read-deny による Glob／Grep からの非表示、deny-glob、WebFetch の優先順位、セッション間認証、組織管理ルール
request-context-pattern.md	ID フローの不変リクエストコンテキスト
audit-logging.md	サニタイズ済み構造化ログ、コンプライアンス
context-separation.md	LLM コンテキスト分離アーキテクチャ
output-guardrails.md	出力検証パイプラインの実装
pre-llm-filtering.md	テナントスコープの検索、コンテンツ抽出
post-llm-attribution.md	決定論的な帰属パターン
prompt-audit.md	プロンプト監査パターン、安全なプロンプトビルダー
presidio-integration.md	Microsoft Presidio のセットアップ、カスタム認識器
langfuse-mask-callback.md	Langfuse SDK のマスク実装

関連スキル

• api-design-framework - API セキュリティパターン
• ork:rag-retrieval - テナントスコープの検索を必要とする RAG パイプラインのパターン
• llm-evaluation - 幻覚の検出を含む出力品質の評価

機能の詳細

authentication

キーワード： パスワード、ハッシュ化、JWT、トークン、OAuth、PKCE、パスキー、WebAuthn、RBAC、セッション 解決する課題：

• 最新の標準規格に準拠した安全な認証の実装
• 適切な有効期限を設定した JWT トークン管理
• PKCE フローを使用した OAuth 2.1
• パスキー／WebAuthn の登録とログイン
• ロールベースのアクセス制御

defense-in-depth

キーワード： 多層防御、セキュリティレイヤー、多層、リクエストコンテキスト、テナント分離 解決する課題：

• AI アプリケーションをエンドツーエンドで保護する方法
• 8 層のセキュリティアーキテクチャの実装
• 不変のリクエストコンテキストの作成
• クエリレベルでのテナント分離の確保

cc-subprocess-hardening (CC 2.1.98)

キーワード： サブプロセス、サンドボックス、PID 名前空間、環境変数の除去、スクリプト上限 解決する課題：

• 暴走するフックスクリプトを制限します：CLAUDE_CODE_SCRIPT_CAPS=100
• サブプロセスから認証情報を除去します：CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1
• Linux でサブプロセスをサンドボックス化するための PID 名前空間分離
• バックスラッシュエスケープや複合コマンドによる Bash 権限のバイパスを防止します

CC 2.1.128 — SDK ホストの「常に許可」の永続化：SDK ホストでユーザーが Bash 権限のプロンプトから「常に許可」を選択すると、セッション終了時に消えるのではなく、.claude/settings.local.json を通じて許可が永続化されるようになりました。SDK コンシューマーの .gitignore を監査し、.claude/settings.local.json が除外されていることを確認してください。このファイルをコミットすると、開発者ごとの Bash 認証許可が漏えいします。プロジェクトにコミットする .claude/settings.json に変更はありません。新しいエントリが追加されるのは、ユーザーのマシンにローカルなファイルのみです。

CC 2.1.169 — マネージド MCP の適用＋OTEL 証明書パスの信頼確認： 2 種類のポリシーバイパスが解消されました。エンタープライズの allowedMcpServers／deniedMcpServers ポリシーは、再接続時、IDE 形式の設定、インストール後最初のセッションにおける --mcp-config サーバー、リモート設定の読み込み前には適用されていませんでした。そのため、これらの経路に関する 2.1.169 より前のマネージド MCP 監査は不完全なものとして扱ってください。また、信頼されていないプロジェクト設定から、信頼確認なしに OTEL クライアント証明書のパスを設定できていました（クローンしたリポジトリから、攻撃者の証明書をテレメトリーに指定できました）。現在は信頼確認が必須です。どちらの修正も ork の下限バージョン（2.1.220）に含まれています。

CC 2.1.163 — ホームディレクトリの拒否ルールが $HOME を使った Bash 参照にも適用されるようになりました：この修正前は、Read(~/.ssh/**) のような拒否ルールで Read ツールはブロックされても、同じファイルに $HOME/.ssh/... 経由でアクセスする Bash コマンドはブロックされず、気付かれないままシークレットを読み取られるバイパスが可能でした。ホームディレクトリのシークレット（例：~/.aws/credentials、~/.ssh/*、~/.gnupg/*）を権限の拒否ルールで保護する場合は、CC の下限バージョンを >= 2.1.163 に固定してください。それより古いビルド（< 2.1.163）では Bash 経由のアクセスが可能なままです。ork の下限バージョンは現在 2.1.220 で、この修正はすでに含まれています。

input-validation

キーワード： スキーマ、検証、Zod、Pydantic、サニタイズ、HTML、XSS、ファイルアップロード 解決する課題：

• 入力をスキーマ（Zod v4、Pydantic）に照らして検証します
• 許可リストを使ってインジェクション攻撃を防止します
• HTML をサニタイズし、XSS を防止します
• マジックバイトを使ってファイルアップロードを検証します

owasp-top-10

キーワード： OWASP、SQL インジェクション、アクセス制御の不備、CSRF、XSS、SSRF 解決する課題：

• OWASP Top 10 の脆弱性を修正します
• SQL インジェクションとコマンドインジェクションを防止します
• CSRF 対策を実装します
• 認証の不備を修正します

llm-safety

キーワード： プロンプトインジェクション、コンテキスト分離、ガードレール、ハルシネーション、LLM 出力 解決する課題：

• プロンプトインジェクション攻撃を防止します
• コンテキスト分離を実装します（LLM の周囲に ID を配置）
• ガードレールパイプラインで LLM 出力を検証します
• LLM 後の帰属を決定的に行います

pii-masking

キーワード： PII、マスキング、Presidio、Langfuse、マスキング処理、GDPR、プライバシー 解決する課題：

• LLM パイプライン内の PII を検出してマスキングします
• マスキングを Langfuse のオブザーバビリティと統合します
• ログ記録前のマスキング処理を実装します
• GDPR に準拠したデータ処理を行います