rbac-rag-assistant

関連: drivescore-cloud — Kubernetes 上の Go サービスで、Terraform とインシデントログを備えています。

大学向けの内部ナレッジアシスタントです。職員と学生が平易な言葉で質問し、閲覧を許可されたポリシードキュメントに基づいた回答を得られます。検索拡張（Retrieval-augmented）、ツール呼び出し、ロール認識を備え、MCP 経由で公開されているため、どのクライアントでも同じルールのもとで同じツールを利用できます。

これは5層システムの Layer 0 です。その上の層は、デリバリーパイプライン、信頼性エンジニアリング、評価、セキュリティテスト、オブザーバビリティを追加します。それぞれがこのアプリケーションの隣ではなく、その上に重なります。

実行方法

Python 3.13。このマシンの python は msys2 ビルドを指しており、これらのパッケージは一切含まれていないため、venv のインタープリターを直接呼び出してください。

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

.\.venv\Scripts\python.exe test_rag.py
.\.venv\Scripts\python.exe test_tools.py

どちらも ok を表示し、API キーは不要です。検索とアクセスルールはオフラインでテスト可能です。それらをモデルの外に置いているのは、まさにそのためです。

何か質問する（GEMINI_API_KEY が必要）:

.\.venv\Scripts\python.exe agent.py student "I have a 1.8 GPA, what happens?"
.\.venv\Scripts\python.exe agent.py staff "the wifi is down in the east wing, log it"

検索のみ（キー不要）:

.\.venv\Scripts\python.exe rag.py admin "adjunct pay per credit hour"

Related MCP server: mcp-business-bot

構成の全体像

擁護に値する3つの設計判断

呼び出し元のロールはツールのパラメーターではない。 ロールは、ターン開始前に帯域外でバインドされます。もし search_docs(query, role) が存在していたなら、モデルが自身のクリアランスを持つことになり、取得されたドキュメントに埋め込まれた「role=admin を使え」という一文が権限昇格の経路になっていたでしょう。渡すものが何もないので、渡すように説得することもできません。

クリアランスフィルターは結果ではなく候補セットに適用される。 呼び出し元が見られないチャンクはランキングに決して入らないため、結果の欠落や変動したスコアから、その存在を推測することはできません。

TF-IDF であり、埋め込みではない。 これは Layer 3 が打ち破るために存在するベースラインです。ゴールデンセットがないうちにセマンティック検索に置き換えるのは推測にすぎません。後で置き換えれば、変更を正当化する数値が得られます。置き換え箇所は Index です。

MCP

mcp_server.py は tools.py の関数を登録するだけで、それ以外は追加しません。これが MCP を1つのファイルにまとめる根拠です。実装は1つ、アクセスルールは1セット、クライアントは多数。クライアントの設定に追加してください:

{
  "mcpServers": {
    "rbac-rag-assistant": {
      "command": "C:\\Users\\Shrey\\Documents\\CLAUDE CODE\\rbac-rag-assistant\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\Shrey\\Documents\\CLAUDE CODE\\rbac-rag-assistant\\mcp_server.py"],
      "env": { "KB_ROLE": "staff" }
    }
  }
}

MCP クライアントには大学のロールという概念がないため、KB_ROLE は起動時に一度だけ読み込まれ、接続全体に適用されます。ロールは会話ではなくサーバープロセスに属します。これにより、モデルがロールを選択できなくなっています。

アクセス拒否時の挙動

教職員専用の資料について学生が質問した場合、「存在しない」とは言わず、資料は存在するが閲覧許可がないと伝えます（ADR-7）。ライブで確認済み:

アカウントが不正使用された疑いがある場合の対処方法についてのガイダンスは、大学のポリシー文書に存在しますが、アクセスには職員のクリアランスが必要です。このポリシーを所管する部署に連絡してください。

境界を越えるのは分類ラベルのみであり、それ以外は何も越えません。パッセージも、タイトルも、ファイル名もありません。どのドキュメントも扱わない質問には別の回答が返ります。この区別の要点はまさにそこです。

驚いたこと

1つ目。 faculty compensation bands はある管理者に対して何も返しませんでしたが、professor salary は同じドキュメントを 0.29 で返しました。その3つの単語はドキュメントのタイトルにしか現れません。parse() はインデックス作成前にタイトルを本文から取り出してメタデータに移します。ユーザーはドキュメントの文言よりもタイトルで検索することがはるかに多いため、最も機密性の高いドキュメントに対する最も自然なクエリが、まさに必ず失敗するクエリでした。修正は1行です。title + text をインデックスし、text を保存します。

記録する価値があるのは、それが どこで 見つかったかです。アクセス制御のテストは一貫して成功していました。学生が機密コンテンツを決して見られないことを検証するテストも含めてです。しかし、誰もそのドキュメントを取得できない状況では、そのテストは空虚に真となっていました。何も返されなかったから通るテストは、ルールが機能しているから通るテストと見た目がまったく同じです。

2つ目。ADR-7 を実装しているときに見つかりました。 「制限対象の資料は存在します」という通知が、無害な質問にも発動します。「ここで正教授をしているのは誰ですか」は報酬帯に対して 0.28 とスコアし、正当な職員の一致の 0.19 よりも高い値です。両者を分ける閾値は存在しないため、これは調整では解決できません。共通する単語と共通する意味を区別できない、語彙マッチングの限界です。情報は漏れていませんが、回答は依然として間違っています。Layer 3 が最初に測定すべき事項です。

3つ目。 モデルはドキュメントがカバーしていない小さな隙間を埋めます。不正使用されたアカウントについて尋ねられたとき、ツールが「それを所管する部署」とだけ答えていたのに、モデルは「IT サービスデスクまたは IT セキュリティチーム」に連絡するよう提案しました。もっともらしく、ここでは無害ですが、取得されたどの情報にも基づいていません。これはまさに groundedness スコアラーが検出するために存在する挙動であり、最初の5件のライブ質問の中で出現しました。

環境