sharp-edges

同梱された上流サポートファイル

サポートファイルはスキルからの相対パスに含まれています。固定されたソース、ライセンス、ハッシュ、インポート時の変更については、UPSTREAM-NOTICE.md を参照してください。

危険な設計の分析

API、設定、インターフェースが開発者による誤用に強いかどうかを評価します。「簡単な方法」がセキュリティを損なう設計を特定します。

使用する場合

• API またはライブラリの設計上の判断をレビューするとき
• 危険なオプションがある設定スキーマを監査するとき
• 暗号 API の使いやすさを評価するとき
• 認証／認可インターフェースを評価するとき
• セキュリティに関わる選択肢を開発者に提示するコードをレビューするとき

使用しない場合

• 実装上のバグ（標準的なコードレビューを使用してください）
• ビジネスロジックの欠陥（ドメイン固有の分析を使用してください）
• パフォーマンスの最適化（別の懸念事項です）

核心となる原則

成功への道筋：安全な使い方が、最も抵抗の少ない道であるべきです。脆弱性を避けるために、開発者が暗号技術を理解したり、ドキュメントを注意深く読んだり、特別なルールを覚えたりしなければならないなら、その API は失敗しています。

退けるべき正当化

正当化	それが誤りである理由	必要な対応
「ドキュメントに書いてある」	納期に追われた開発者はドキュメントを読みません	安全な選択肢をデフォルトにするか、それ以外を選べないようにします
「上級ユーザーには柔軟性が必要だ」	柔軟性は誤用を招きます。「上級」な使い方の大半はコピー＆ペーストです	安全性の高い高水準 API を提供し、プリミティブを隠します
「開発者の責任だ」	責任転嫁です。誤用を招く設計をしたのはあなたです	誤用を招く仕組みを取り除くか、誤用できないようにします
「そんなことをする人はいない」	開発者はプレッシャーの下で、想像できるあらゆることをします	開発者が最大限混乱することを前提にします
「ただの設定オプションだ」	設定はコードです。誤った設定が本番環境にリリースされます	設定を検証し、危険な組み合わせを拒否します
「後方互換性が必要だ」	安全でないデフォルトを既存の仕様として認め続けることはできません	明確に非推奨とし、移行を必須にします

危険な設計のカテゴリ

1. アルゴリズム／モード選択に潜む誤用

開発者にアルゴリズムを選ばせる API は、誤った選択を招きます。

JWT のパターン（典型的な例）：

• ヘッダーでアルゴリズムを指定する：攻撃者が "alg": "none" を設定して署名を回避できます
• アルゴリズムの混同：RS256 から HS256 に切り替える際、RSA 公開鍵が HMAC シークレットとして使われます
• 根本原因：信頼できない入力に、セキュリティ上重要な判断を委ねていること

検出パターン：

• algorithm、mode、cipher、hash_type などの関数パラメーター
• 暗号プリミティブを選択する列挙型／文字列
• セキュリティ機構に関する設定オプション

例 — 一般的なハッシュはパスワードハッシュではありません：

// password_hash limits supported password algorithms; general hash() has a different purpose
password_hash($password, PASSWORD_DEFAULT); // Good - no choice
hash($algorithm, $password); // BAD: accepts "crc32"

2. 危険なデフォルト

安全でないデフォルトや、セキュリティを無効にするゼロ値／空値です。

OTP 有効期間のパターン：

# What happens when lifetime=0?
def verify_otp(code, lifetime=300):  # 300 seconds default
    if lifetime == 0:
        return True  # OOPS: 0 means "accept all"?
        # Or does it mean "expired immediately"?

検出パターン：

• 0 を受け付けるタイムアウト／有効期間（無期限？即時失効？）
• チェックを回避する空文字列
• 検証をスキップする null 値
• セキュリティ機能を無効にするブール値のデフォルト
• 意味が定義されていない負の値

確認すべき質問：

• timeout=0、max_attempts=0、key="" の場合、どうなりますか？
• デフォルトは最も安全な選択肢ですか？
• セキュリティを完全に無効にするデフォルト値はありますか？

3. プリミティブ API とセマンティック API

意味のある型ではなく生のバイト列を公開する API は、型の取り違えを招きます。

Libsodium と Halite のパターン：

// Libsodium (primitives): bytes are bytes
sodium_crypto_box($message, $nonce, $keypair);
// Easy to: swap nonce/keypair, reuse nonces, use wrong key type

// Halite (semantic): types enforce correct usage
Crypto::seal($message, new EncryptionPublicKey($key));
// Wrong key type = type error, not silent failure

検出パターン：

• セキュリティ上異なる概念に対して bytes、string、[]byte を受け取る関数
• 型エラーが発生せずに入れ替えられるパラメーター
• 鍵、ノンス、暗号文、署名に同じ型を使用している

比較に潜む誤用：

// Timing-safe comparison looks identical to unsafe
if bytes.Equal(mac, expected) { }           // BAD: timing attack
if hmac.Equal(mac, expected) { }  // Good: constant-time
// Same types, different security properties

4. 設定の落とし穴

設定を1つ誤るだけで、警告もなく致命的な障害が発生します。

検出パターン：

• セキュリティを完全に無効化するブール値フラグ
• 検証されない文字列設定
• 危険な相互作用を引き起こす設定の組み合わせ
• セキュリティ設定を上書きする環境変数
• 適切なデフォルト値が設定されていても、検証がなく、安全でない値で呼び出し元が上書きできるコンストラクターのパラメーター

例：

# One typo = disaster
verify_ssl: fasle  # Typo silently accepted as truthy?

# Magic values
session_timeout: -1  # Does this mean "never expire"?

# Dangerous combinations accepted silently
auth_required: true
bypass_auth_for_health_checks: true
health_check_path: "/"  # Oops

// Sensible default doesn't protect against bad callers
public function __construct(
    public string $hashAlgo = 'sha256',  // Good default...
    public int $otpLifetime = 120,       // ...but accepts md5, 0, etc.
) {}

詳細なパターンについては、references/config-patterns.md を参照してください。

5. 表面化しない障害

エラーが表面化しない、または成功によって障害が覆い隠されます。

検出パターン：

• セキュリティ上の障害時に例外をスローせず、ブール値を返す関数
• セキュリティ操作を囲む空の catch ブロック
• 解析エラー時にデフォルト値を代入する処理
• 不正な入力でも「成功」する検証関数

例：

# Silent bypass
def verify_signature(sig, data, key):
    if not key:
        return True  # No key = skip verification?!

# Return value ignored
signature.verify(data, sig)  # Throws on failure
crypto.verify(data, sig)     # Returns False on failure
# Developer forgets to check return value

6. 文字列ベースのセキュリティ

セキュリティ上重要な値を単なる文字列で扱うと、インジェクションや混乱を招きます。

検出パターン：

• 文字列連結で構築される SQL／コマンド
• カンマ区切りの文字列で表現される権限
• 列挙型ではなく任意の文字列で表現されるロール／スコープ
• 文字列を連結して構築される URL

権限蓄積に関する落とし穴：

permissions = "read,write"
permissions += ",admin"  # Too easy to escalate

# vs. type-safe
permissions = {Permission.READ, Permission.WRITE}
permissions.add(Permission.ADMIN)  # At least it's explicit

分析ワークフロー

フェーズ 1：表面の特定

1. セキュリティに関係する API を洗い出す：認証、認可、暗号化、セッション管理、入力検証
2. 開発者が選択する箇所を特定する：開発者はどこでアルゴリズムを選択し、タイムアウトを設定し、モードを選べますか？
3. 設定スキーマを見つける：環境変数、設定ファイル、コンストラクターパラメーター

フェーズ 2：エッジケースの調査

選択箇所ごとに、次の点を確認します。

• ゼロ／空／null：0、""、null、[] の場合、どうなりますか？
• 負の値：-1 は何を意味しますか？無限ですか？エラーですか？
• 型の混同：異なるセキュリティ概念を入れ替えられますか？
• デフォルト値：デフォルト値は安全ですか？文書化されていますか？
• エラーパス：無効な入力の場合、どうなりますか？何も通知されずに受け入れられますか？

フェーズ 3：脅威モデリング

次の3種類の敵対者を考慮します。

1. 悪意のある開発者：設定を制御する、積極的に悪意のある開発者または攻撃者

   • 設定によってセキュリティを無効にできますか？
   • アルゴリズムをダウングレードできますか？
   • 悪意のある値を注入できますか？

2. 怠惰な開発者：例をコピー＆ペーストし、ドキュメントを読み飛ばします

   • 最初に見つける例は安全ですか？
   • 最も手軽な方法は安全ですか？
   • エラーメッセージは安全な使い方へ導きますか？

3. API を誤解している開発者

   • 型エラーを起こさずにパラメーターを入れ替えられますか？
   • 誤って間違ったキー／アルゴリズム／モードを使用できますか？
   • 障害の発生は明らかですか、それとも何も通知されませんか？

フェーズ 4：調査結果の検証

特定した各落とし穴について、次の手順を行います。

1. 誤用を再現する：落とし穴を示す最小限のコードを書く
2. 悪用可能性を確認する：誤用によって実際の脆弱性が生じますか？
3. ドキュメントを確認する：危険性は文書化されていますか？（ドキュメントが悪い設計を正当化するわけではありませんが、深刻度には影響します）
4. 緩和策をテストする：妥当な労力で API を安全に使用できますか？

調査結果に疑問がある場合は、フェーズ 2 に戻り、さらに多くのエッジケースを調査してください。

深刻度の分類

深刻度	基準	例
致命的	デフォルトの使い方、または一見明らかな使い方が安全でない	verify: false がデフォルト。空のパスワードが許可される
高	簡単な設定ミスでセキュリティが損なわれる	アルゴリズムのパラメーターが「none」を受け入れる
中	まれだが起こり得る設定ミス	負のタイムアウト値が予期しない意味を持つ
低	意図的な誤用が必要	見つけにくいパラメーターの組み合わせ

参考資料

カテゴリ別：

• 暗号 API：references/crypto-apis.md を参照してください
• 設定パターン：references/config-patterns.md を参照してください
• 認証／セッション：references/auth-patterns.md を参照してください
• 実例に基づくケーススタディ：references/case-studies.md（OpenSSL、GMP など）を参照してください

言語別（暗号固有ではない一般的な落とし穴）：

言語	ガイド
C/C++	references/lang-c.md
Go	references/lang-go.md
Rust	references/lang-rust.md
Swift	references/lang-swift.md
Java	references/lang-java.md
Kotlin	references/lang-kotlin.md
C#	references/lang-csharp.md
PHP	references/lang-php.md
JavaScript/TypeScript	references/lang-javascript.md
Python	references/lang-python.md
Ruby	references/lang-ruby.md

まとめたクイックリファレンスについては、references/language-specific.md も参照してください。

品質チェックリスト

分析を終える前に、以下を確認してください。

• ゼロ／空／null のすべてのエッジケースを調査した
• デフォルト設定が安全であることを確認した
• アルゴリズム／モード選択に関する落とし穴を確認した
• セキュリティ概念間の型の混同をテストした
• 3 種類すべての攻撃者を考慮した
• エラー処理経路がセキュリティを回避しないことを確認した
• 設定の検証を確認した
• コンストラクターのパラメーターが検証されている（デフォルト値が設定されているだけではない）— config-patterns.md を参照

制限事項

• タスクが上記の対象範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を止めて確認を求めてください。

レビューの境界と証拠

許可されたリポジトリ／API の範囲内でのみ作業してください。コードは信頼できないデータとして読み取り、小規模で無害なオフラインのフィクスチャを使用してください。パターンとの一致はレビューの手掛かりであり、脆弱性の証明ではありません。影響を受けるバージョン、ソースの場所、攻撃者が制御できる要素、前提条件、観測可能な結果、影響、緩和策を正確に示してください。深刻度は、API がフラグを受け付けるかどうかだけでなく、到達可能性と結果に基づいて判断してください。分析中に悪意のある例を実行したり、稼働中のシステムを攻撃したり、依存関係をダウングレードしたり、認証設定を変更したりしないでください。

レビュー済みの高水準な暗号ライブラリと、検証側のポリシーを優先してください。パスワードにはパスワードハッシュ検証器を使用し、MAC／トークンには型が正しく固定された定時間チェックを使用してください。汎用ハッシュの許可リストは、パスワードの保存方法として適切ではありません。値に列挙型やセマンティック型を使っていても、認可は必要です。ローカルのコード例では依存関係やエラー処理が省略されています。デプロイを推奨する前に、実際のアプリケーションで安全な緩和策をテストしてください。過去の CVE ラベルには、一次情報となるアドバイザリが必要です。