X Knowledge Agent

テーマ

OSS検証エンジン ​

X Knowledge Agent の最大の差別化要素です。ブックマーク内で共有されたOSSリポジトリの安全性と品質を自動検証し、AIレポートを生成します。

検証フロー概要 ​

mermaid
flowchart TD
    A["ブックマーク内の\nGitHub URL検出"] --> B["Step 1\nGitHub メタデータ収集"]
    B --> C["Step 2\nセキュリティ監査"]
    C --> D["Step 3\nDocker サンドボックス\nビルド & テスト"]
    D --> E["Step 4\nAI レポート生成"]
    E --> F["OSSReport\nレコード保存"]

    style A fill:#f9f,stroke:#333
    style F fill:#9f9,stroke:#333

Step 1: GitHub メタデータ収集 ​

GitHub API を使用してリポジトリのメタデータを収集します。

収集データ ​

mermaid
graph LR
    API["GitHub API"] --> Stars["スター数"]
    API --> License["ライセンス"]
    API --> Lang["主要言語"]
    API --> Contributors["コントリビューター数"]
    API --> LastCommit["最終コミット日"]
    API --> CI["CI設定の有無"]
    API --> Tests["テストの有無"]
    API --> Org["オーナー組織"]

API エンドポイント ​

データエンドポイント
リポジトリ情報GET /repos/{owner}/{repo}
コントリビューターGET /repos/{owner}/{repo}/contributors
ワークフローGET /repos/{owner}/{repo}/actions/workflows
ディレクトリ構造GET /repos/{owner}/{repo}/contents/

Step 2: セキュリティ監査 ​

静的解析によるセキュリティチェックを実施します。

チェック項目 ​

mermaid
flowchart TD
    A["ソースコード取得"] --> B["不可視文字検出"]
    A --> C["依存関係の脆弱性"]
    A --> D["install hooks 検査"]
    A --> E["ネットワーク呼び出し検出"]

    B -->|"Unicode BiDi,\nzero-width chars"| R["リスクスコア"]
    C -->|"npm audit,\npip-audit"| R
    D -->|"preinstall,\npostinstall"| R
    E -->|"fetch, axios,\nnet.connect"| R

検出対象の脅威 ​

脅威検出方法深刻度
不可視文字（BiDi攻撃）Unicode コードポイント検査Critical
依存関係の脆弱性npm audit / pip-auditHigh
悪意のある install hookspackage.json の scripts 検査High
不審なネットワーク呼び出しAST 解析 + パターンマッチMedium
minified/難読化コードエントロピー分析Medium
過剰な権限要求マニフェスト/設定ファイル検査Low

Step 3: Docker サンドボックスビルド & テスト ​

隔離環境でビルドとテストを実行します。詳細は OSSサンドボックス設計 を参照。

mermaid
sequenceDiagram
    participant Engine as 検証エンジン
    participant Docker as Docker Engine
    participant Container as サンドボックス

    Engine->>Docker: コンテナ作成（制限付き）
    Docker-->>Container: 起動
    Engine->>Container: リポジトリクローン
    Container->>Container: 依存関係インストール
    Container->>Container: ビルド実行
    Container->>Container: テスト実行
    Container-->>Engine: 結果（exit code, logs, screenshot）
    Engine->>Docker: コンテナ削除

判定基準 ​

結果条件
BUILD_SUCCESSビルドが正常に完了
BUILD_FAILビルドエラー
TEST_PASS全テストが通過
TEST_FAILテスト失敗あり
TIMEOUT5分以内に完了しなかった
NETWORK_VIOLATION許可されていないネットワーク通信を検出

Step 4: AI レポート生成 ​

収集した全データを Claude に渡し、人間が読みやすいレポートを生成します。

レポート内容 ​

  • リポジトリの概要と用途
  • セキュリティ評価サマリー
  • ビルド・テスト結果の解説
  • 推奨事項（使用可否、注意点）
  • 類似ツールとの比較（既存ナレッジがある場合）

安全性スコア計算 ​

メタデータから 0-100 のスコアを算出します。

スコアリングテーブル ​

要素ウェイトスコアリング基準
スター数20%0-10: 0pt, 10-100: 5pt, 100-1000: 8pt, 1000+: 10pt
ライセンス (OSI)15%MIT/Apache: 10, GPL: 7, None: 0
最終コミット20%<1ヶ月: 10, <6ヶ月: 7, <1年: 4, それ以外: 0
コントリビューター数15%1人: 3, 2-5人: 6, 5-20人: 8, 20人+: 10
CI設定10%あり: 10, なし: 0
テスト10%あり: 10, なし: 0
著名組織10%メジャー組織: 10, その他: 5

判定閾値 ​

mermaid
graph LR
    Score["安全性スコア"] --> High["50以上\n✅ VERIFY"]
    Score --> Mid["30-49\n⚠️ CAUTION"]
    Score --> Low["30未満\n🚫 DANGER"]

    style High fill:#4caf50,color:#fff
    style Mid fill:#ff9800,color:#fff
    style Low fill:#f44336,color:#fff
スコア範囲判定アクション
50 以上VERIFYサンドボックスでの検証を続行
30 - 49CAUTION警告付きで検証。レポートに注意事項を強調
30 未満DANGER検証を中止。危険フラグを立てる

出力例 ​

json
{
  "repoUrl": "https://github.com/example/tool",
  "repoOwner": "example",
  "repoName": "tool",
  "stars": 1250,
  "license": "MIT",
  "language": "TypeScript",
  "securityScore": 78,
  "securityVerdict": "VERIFY",
  "buildResult": "BUILD_SUCCESS",
  "testResult": "TEST_PASS",
  "usageNotes": "高品質なTypeScriptライブラリ。CI/CDも整備されており、安全に使用可能。"
}