CR-NEXUS-050: NPE (Nexus Protocol Engine) 詳細仕様

文書ID: CR-NEXUS-050 バージョン: 1.0 最終更新: 2025-12-28 ステータス: 承認済み 担当レイヤー: カーネル層

1. 概要

1.1 目的

NPE (Nexus Protocol Engine) は、NexusOSアーキテクチャにおけるカーネル層の中核コンポーネントであり、システム全体の安定性とセキュリティを保証する役割を担います。特に、LLMエージェントが処理するコンテキストから機密情報を検出・マスキングすることで、情報漏洩リスクを根本的に排除します。

1.2 設計思想

NPEは「セキュリティゲート」として機能し、以下の原則に基づいて設計されています：

  • Zero Trust: 全てのコンテキストは潜在的に機密情報を含むと仮定
  • Defense in Depth: 検出とマスキングの二段構えの防御
  • Fail-Safe: 誤検出（偽陽性）は許容、見逃し（偽陰性）は許容しない
  • Auditability: 全ての検出とマスキングは監査ログに記録

1.3 NexusOS内での位置づけ 

NexusOS 4層アーキテクチャ:
┌─────────────────────────────────┐
│ 4. アプリケーション層            │
├─────────────────────────────────┤
│ 3. シェル層 (Gradio UI, API)    │
├─────────────────────────────────┤
│ 2. システムサービス層            │
│    (Coder, Tester, Guardian)    │
├─────────────────────────────────┤
│ 1. カーネル層                   │
│    ┌─────────┬─────────┐        │
│    │   NPE   │   VCS   │ ← ここ │
│    └─────────┴─────────┘        │
└─────────────────────────────────┘

2. 機能要件

2.1 機密情報検出 (Context Scanner)

2.1.1 検出対象

NPEは以下のカテゴリの機密情報を検出する必要があります：

カテゴリ 検出対象 優先度 正規表現パターン
API認証情報 API_KEY, SECRET_KEY, ACCESS_KEY等 最高 ^\s*(?:[A-Z0-9_]+_)?(?:API\|SECRET\|ACCESS\|REFRESH)?_?KEY\s*=
認証トークン TOKEN, PASSWORD, AUTH等 最高 ^\s*(?:TOKEN\|PASSWORD\|PASS\|AUTH)_?[A-Z0-9_]*\s*=
AWS認証情報 AKIA/ASIA形式のアクセスキー 最高 AKIA[0-9A-Z]{16}, ASIA[0-9A-Z]{16}
暗号鍵 (PEM) RSA/EC/OPENSSH/PKCS#8秘密鍵 最高 -----BEGIN (?:RSA \|EC \|OPENSSH )?PRIVATE KEY-----
PII (メール) メールアドレス 高 [a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+
PII (電話) 電話番号 (日本・国際形式) 中 \b\d{2,4}[-\s]?\d{2,4}[-\s]?\d{3,4}\b

2.1.2 PEM鍵の詳細仕様

要件: 以下の全てのPEM形式を検出すること

  1. RSA秘密鍵 (PKCS#1) 
    -----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----
  2. EC秘密鍵 (SEC1) 
    -----BEGIN EC PRIVATE KEY-----
MHcCAQEEIIGlRHqO...
-----END EC PRIVATE KEY-----
  3. OpenSSH秘密鍵 
    -----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjE...
-----END OPENSSH PRIVATE KEY-----
  4. PKCS#8秘密鍵 (汎用形式) 
    -----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkq...
-----END PRIVATE KEY-----

実装パターン:

r'-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----'

注意: スペースの位置に注意

  • (?:RSA |EC |OPENSSH )? - アルゴリズム名の後ろにスペース
  • PRIVATE KEY - 常に含まれる

2.1.3 関数仕様: context_scanner() 

def context_scanner(code: str) -> str:
    """
    コンテキストをスキャンし、機密情報の有無を判定する。

    Args:
        code (str): スキャン対象のコード・テキスト

    Returns:
        str: 'safe' または 'sensitive'

    動作:
        1. _SENSITIVE_PATTERNS の全パターンに対してマッチングを実行
        2. 1つでもマッチした場合、即座に 'sensitive' を返す (早期リターン)
        3. 全パターンでマッチしない場合、'safe' を返す

    ログ:
        - 開始: "Context scan initiated..."
        - 検出: "RESULT: Sensitive pattern found. Match: '<最初の64文字>...'"
        - 安全: "RESULT: No sensitive patterns found."
    """

パフォーマンス要件:

  • 1KB以下のテキスト: 1ms以内
  • 10KB以下のテキスト: 10ms以内
  • 100KB以下のテキスト: 100ms以内

2.2 機密情報マスキング (Secure Context Builder)

2.2.1 マスキング戦略

情報種別 マスキング方法 保持する情報 理由
API Key [REDACTED_BY_NPE] キー名のみ デバッグ時にどのキーが問題か特定可能
AWS Key [REDACTED_AWS_KEY_BY_NPE] なし クラウドプロバイダーの特定を防ぐ
PEM鍵 [REDACTED_PEM_BY_NPE] ヘッダー・フッター 鍵の種類（RSA/EC等）は診断に有用
メール [user]@[REDACTED_DOMAIN] ユーザー名部分 システムアカウントの識別に有用
電話 090-[REDACTED]-5678 先頭・末尾の数桁 形式の検証に有用

2.2.2 関数仕様: secure_context_builder() 

def secure_context_builder(code: str) -> str:
    """
    機密情報をマスキング（匿名化）処理する。

    Args:
        code (str): マスキング対象のコード・テキスト

    Returns:
        str: マスキング済みのテキスト

    動作:
        1. 入力テキストをコピー (元のテキストは保持しない)
        2. 各パターンに対して正規表現置換を順次実行
        3. マスキング済みテキストを返す

    冪等性:
        - 同じ入力に対して常に同じ出力を返す
        - 既にマスキング済みのテキストを再度マスキングしても安全

    ログ:
        - 開始: "Masking sensitive data in context..."
    """

データ保護要件:

  • 元のテキスト（マスキング前）はメモリ上に残さない
  • マスキング処理は常に成功する（例外を発生させない）
  • 部分的なマスキング失敗時も、可能な限りマスキングを継続

3. 非機能要件

3.1 セキュリティ

  • SQ-1: マスキング前の機密情報をログに出力してはならない
  • SQ-2: マスキング前のテキストをファイルシステムに書き込んではならない
  • SQ-3: エラー発生時も、スタックトレースに機密情報を含めてはならない

3.2 パフォーマンス

  • PQ-1: 正規表現はコンパイル済みパターンを使用すること（将来的改善）
  • PQ-2: 大規模テキスト（1MB以上）は分割処理を検討すること
  • PQ-3: メモリ使用量は入力テキストの3倍以内に抑えること

3.3 監査可能性

  • AQ-1: 全ての検出イベントはlogger.warning()レベルで記録
  • AQ-2: 検出されたパターンの種類を識別可能にする
  • AQ-3: マスキング処理の開始をログに記録

4. テスト要件

4.1 単体テスト

ファイル: tests/npe/test_policies.py

カバレッジ目標: 100%

必須テストケース:

4.1.1 Context Scanner

  • ✅ AWS AKIA鍵の検出
  • ✅ AWS ASIA鍵の検出
  • ✅ PEM RSA秘密鍵の検出
  • ✅ PEM EC秘密鍵の検出
  • ✅ PEM PKCS#8鍵の検出
  • ✅ API_KEY環境変数の検出
  • ✅ SECRET_KEY環境変数の検出
  • ✅ PASSWORD環境変数の検出
  • ✅ TOKEN環境変数の検出
  • ✅ AUTH_TOKEN環境変数の検出
  • ✅ メールアドレスの検出
  • ✅ 電話番号の検出
  • ✅ 安全なコードは ‘safe’ を返す
  • ✅ コメントのみのコードは ‘safe’
  • ✅ 空文字列は ‘safe’

4.1.2 Secure Context Builder

  • ✅ AWS AKIA鍵のマスキング
  • ✅ AWS ASIA鍵のマスキング
  • ✅ API_KEY環境変数のマスキング
  • ✅ SECRET_KEY環境変数のマスキング
  • ✅ PASSWORD環境変数のマスキング
  • ✅ TOKEN環境変数のマスキング
  • ✅ PEM RSA鍵のマスキング（ヘッダー保持）
  • ✅ PEM EC鍵のマスキング（ヘッダー保持）
  • ✅ PEM PKCS#8鍵のマスキング（ヘッダー保持）
  • ✅ メールアドレスのマスキング
  • ✅ 電話番号のマスキング
  • ✅ 安全なコードは変更しない
  • ✅ 複数の機密情報を含むテキストの処理
  • ✅ 空文字列の処理

4.1.3 統合テスト

  • ✅ スキャン→マスキングのワークフロー
  • ✅ 安全なコードのワークフロー

4.2 セキュリティテスト

目的: 既知の機密情報パターンの検出漏れを防ぐ

テストデータ:

  • GitHub公開リポジトリから収集した実際の漏洩パターン
  • OWASP Top 10に記載された一般的な機密情報パターン

合格基準: 偽陰性率 0% (見逃しゼロ)

4.3 パフォーマンステスト

シナリオ:

  1. 10KB のコードファイル: 100回スキャン
  2. 100KB のログファイル: 10回スキャン
  3. 1MB のダンプファイル: 1回スキャン

合格基準: 95パーセンタイルで100ms以内

5. 実装詳細

5.1 モジュール構成 

src/nexuscore/npe/
├── __init__.py
├── policies.py          ← NPEのメイン実装
├── logger.py            ← NPE統合のロギング
└── engine.py            ← 将来的な拡張

5.2 依存関係

  • 標準ライブラリ: re (正規表現)
  • 内部モジュール: nexuscore.logging_standard
  • 外部ライブラリ: なし

5.3 ロギング仕様

ロガー名: nexuscore.npe.policies

ログレベル:

  • INFO: スキャン開始、安全判定
  • WARNING: 機密情報検出（最初の64文字のみ）
  • ERROR: 例外発生時（機密情報を含まない）

6. 将来の拡張

6.1 プラグイン機構

顧客独自の機密情報パターンを追加可能にする：

npe.register_pattern(
    name="custom_token",
    pattern=r'CUSTOM-[A-Z0-9]{32}',
    mask_replacement="[REDACTED_CUSTOM_TOKEN]"
)

6.2 機械学習ベースの検出

正規表現では検出困難なパターン（例：自然言語中のパスワード）を、MLモデルで検出。

6.3 リアルタイム監視

エディタ統合により、開発者がコードを書いている最中に機密情報を警告。

7. 参照

  • 実装ファイル: src/nexuscore/npe/policies.py
  • テストファイル: tests/npe/test_policies.py
  • 親仕様: NexusOS技術ホワイトペーパー（2025-12-28版）
  • 関連仕様:
    • CR-NEXUS-051 (エラー分類システム)
    • CR-NEXUS-052 (品質ゲート)

承認者: NexusCore開発チーム 次回レビュー日: 2026-03-28

This site uses Just the Docs, a documentation theme for Jekyll.