BizGuard：AI プログラミングアシスタントにビジネスセキュリティゲートを追加する

BizGuard はオープンソースの検証プロジェクトです。AI プログラミングアシスタントがコードを変更する前に、その変更がシステム内で見落とされがちなビジネスルールに抵触していないかをチェックします。

Claude Code や Codex などのプログラミングアシスタントと組み合わせて使用できます。アシスタントがコードを書き、BizGuard が重要なルールが破られた際に追跡可能なブロック結論を提供します。これは本番向けセキュリティ製品ではなく、人間の判断を代替するものでもありません。

何を解決するのか？

AI は要件に沿ってコードを変更するのは得意ですが、あなたのシステムに「触れてはいけない」ルールがあることを必ずしも知りません。さらに厄介なのは、これらのルールがコメントに書かれていないことが多いことです。例えば、クーポンは一度だけ利用できる、台帳の状態は一貫していなければならない、外部に返すデータフィールドを勝手に削除してはいけない、などです。

例を挙げると、AI がクーポン利用ロジックを変更する際、「コードを簡素化する」ために冪等キーのチェックを削除してしまうことがあります。冪等キーは「このリクエストの一意の番号」と理解できます。これがあれば、重複クリックやネットワーク再試行によって同じクーポンが二重に利用されることはありません。コードはコンパイルできるかもしれませんし、通常のテストも通るかもしれませんが、ユーザーが重複送信した場合に二重利用が発生する可能性があります。

従来の LLM コードレビューは、事後的に別の AI に「ここにリスクがあるか」を推測させるようなものです。役に立ちますが、結果は確率的です。一方 BizGuard は、変更が次のステップに進む前に、明確なビジネスルールを実行可能な Policy（ポリシー）として、構文木チェック（AST、プログラム構造に基づくものでプレーンテキストではない）と固定ルールを用いて決定的な結論を導き出します。同じ入力はオフラインでリプレイ可能で、結論がモデルのその場の判断に依存することはありません。

Related MCP server: Architect-to-Product (A2P)

なぜこのプロジェクトを作るのか？

複雑な業務システムには多くのビジネス不変条件、つまり「どのように変更しても常に成立しなければならない」制約が潜んでいます。例えば：

• 冪等性：重複リクエストによって二重に課金・利用・出荷されてはいけない；

• 台帳の一貫性：取引状態と台帳記録が互いに矛盾してはいけない；

• DTO 互換性：DTO はサービス間で受け渡しされるデータ構造であり、外部公開フィールドを静かに壊してはいけない。

これらの知識は、過去の障害事例、インターフェース契約、チーム文書、複数のサービスに散在していることが多いです。既存の CodeRabbit などのソリューションは主に事後的な LLM レビューに依存しており、手がかりを見つけるには適していますが、隠れた不変条件を毎回確実に識別できるわけではありません。

BizGuard のアプローチは、重要な不変条件を Policy に整理し、AST 検証、影響分析、証拠チェーンによって意思決定を支えることです。次の 3 つの基本原則に従います：

• 決定性：結論はオフラインでリプレイ可能；

• 証拠チェーン：各 BLOCK はルール、変更、関連証拠に遡ることができる；

• 未知を安全と偽らない：情報が不完全な場合は CHECK_INCOMPLETE または REQUIRE_APPROVAL を返し、勝手に ALLOW としない。

技術アーキテクチャ

プロジェクトは P0 から P5 まで段階的に構築されます。ここでの「P」はフェーズ番号であり、順番に手動で操作することを要求するものではありません。

flowchart LR
    P0[P0：3 个 Java 脱敏 fixture 仓库\n语义 catalog] --> P1[P1：领域契约\n黄金基准]
    P1 --> P2[P2：知识 Hub\n混合检索]
    P2 --> P3[P3：跨服务影响图谱\n8 类节点 · 真 BFS]
    P3 --> P4[P4：Context Compiler\n8 个 MCP Tool]
    P4 --> P5[P5：四态决策 · 审批 · CI\n5 组消融]
    P5 --> D[带证据的安全结论]

• P0：coupon-core、coupon-contract、merchant-service の 3 つの匿名化された Java fixture リポジトリと、ビジネス機能・ルール・責任者を記述したセマンティックカタログを提供。

• P1：ドメイン契約を検証可能なゴールデンベースラインとして固定し、ルールが実装とともにドリフトするのを防ぐ。

• P2：知識 Hub がガバナンスされたチーム知識を集約。ハイブリッド検索がセマンティックベクトルとキーワード結果を組み合わせる。凍結された評価セットの Recall@5=1.0 は、その固定された小さなセット内で上位 5 件の結果がターゲットをカバーしていることを示すだけであり、本番環境での一般的な再現率を表すものではない。

• P3：組織、デプロイ、コード、インターフェース、データ、メッセージ、ランタイム、ビジネスの合計 8 種類のノードを含むクロスサービス影響グラフを構築。実際の BFS（幅優先探索）を使用して最短影響パスを見つけ、パスに沿って証拠を返す。動的境界を確認できない場合は明示的に未知としてマーク。

• P4：Context Compiler がタスク、リポジトリ、ベースラインバージョン、ルール、影響、必須テスト項目を読み取り専用のコンテキストパックにコンパイル。8 つの MCP Tool を通じて Agent が呼び出し可能。

• P5：4 状態の意思決定に集約し、承認ワークフローと CI 再チェックに接続。5 組のオフラインリプレイ可能なアブレーション対照を提供：Naive Baseline、Rules Only、RAG Only、Context、Full。

4 状態の意味は非常に明確です：ALLOW（続行可）、ALLOW_WITH_TESTS（指定されたテストを補完すれば続行可）、REQUIRE_APPROVAL（人間の確認が必要）、BLOCK（重大な違反を検出、ブロック）。旧チェックパイプラインでチェックできないケースが発生した場合は明確に CHECK_INCOMPLETE を返し、「自動的に通過させない」結果にマッピングします。

プロジェクト構造

biz-guard/
├── src/bizguard/        # 核心：规则、决策、图谱、检索、CLI 与 CI
├── agents_mcp/          # MCP 协议适配层，供 AI 编程助手调用
├── fixtures/            # 三个脱敏 Java 微服务 fixture 与辅助编译脚本
├── sample/              # Python 示例代码与可复现的 diff
├── policy/              # 业务不变量与策略注册表
├── registry/            # 领域契约登记数据
├── knowledge/           # 已发布知识、ADR 与检索素材
├── bench/               # 黄金基准、决策 fixture、五组消融任务
├── tests/               # 自动化测试
├── scripts/             # Demo、安装验证和 benchmark 脚本
└── docs/                # 架构决策记录

Demo：同じ変更、2 つの結果

プロジェクトルートディレクトリで実行：

./scripts/demo.sh

このスクリプトは、「ネイティブ Coding Agent 対照グループ」（オフラインで決定的な scripted シミュレーションベースライン）が変更を一見合理的と判断して通過させ、その後 BizGuard が同じ diff をチェックして BLOCK を返すことをデモします。これは実際の Claude Code や Codex の能力の測定ではありません。benchmark の --live モードで実際の Agent コマンドを設定した場合のみ、実際の Agent が実行されます。

違反サンプルを直接確認することもできます：

bizguard check --diff sample/diffs/diff_violation_1.diff

この diff は IdempotencyStore.check(idempotency_key) を削除しています。BizGuard は BLOCK を出力し、「削除された冪等チェック」を finding/evidence として返します。そのため、「なぜブロックされたのか」を追跡でき、単なるブラックボックスの「不合格」ではありません。

クイックスタート

環境要件

• Python 3.12+

• Java 17（Java fixture のコンパイル/検証用）

git clone https://github.com/PureBlueFrank/biz-guard.git
cd biz-guard

# 常规安装
pip install -e .

# 运行当前工作区的全部测试（当前可收集 259 个）
pytest

オフライン環境では、まず仮想環境または内部パッケージソースでビルド依存関係 hatchling を準備してから、次を使用します：

pip install --no-build-isolation -e .

pip install -e . はデフォルトで分離されたビルド環境を作成し、オフライン時には hatchling のダウンロードを試みる可能性があります。

一般的な CLI

以下のコマンドは、現在のディレクトリがプロジェクトルートであることを前提としています。prepare にはタスク、関連リポジトリ、ベースラインバージョンを指定する必要があります。impact は実際の fixture グラフに基づいてパスと証拠を返します。

# 编译 Agent 可读的上下文包
bizguard prepare --task "检查优惠券状态字段变更" \
  --repos coupon-core coupon-contract \
  --base-revisions bench/fixtures/phase3-revisions.yaml --json

# 检查 unified diff 是否违反 Policy
bizguard check --diff sample/diffs/diff_violation_1.diff

# 分析跨服务影响
bizguard impact analyze \
  --diff bench/fixtures/phase3/dto-status.diff \
  --repos fixtures/java-microservices \
  --revision-set bench/fixtures/phase3-revisions.yaml --format json

# 搜索受治理的团队知识
bizguard knowledge search --query "优惠券核销必须使用幂等键" \
  --scope coupon_redemption --revision semantic-seed-v1 \
  --roles engineering --json

8 つの MCP Tool

MCP（Model Context Protocol）は、AI アシスタントが外部機能を呼び出すための標準インターフェースです。BizGuard は以下の 8 つのツールを提供します：

1. prepare_change：読み取り専用の Context Pack をコンパイル；

2. search_team_knowledge：権限のあるチーム知識を検索；

3. explain_symbol：インデックス化されたシンボルとそのグラフ証拠を説明；

4. analyze_impact：影響パス、未知の境界、必須テスト項目を分析；

5. validate_patch：unified diff を決定的に検証；

6. get_required_tests：Policy に基づいて実行すべきテストを特定；

7. request_approval：現時点では承認スキーマのみを提供し、承認レコードは作成しない；

8. get_change_decision：4 状態の集約決定、証拠、テスト、承認者を返す。

インストールのクローズドループ検証

./scripts/verify_install.sh --offline

このスクリプトはローカル診断と CI スロー再チェックを検証し、デフォルトでクロスサービス DTO 変更 fixture を使用します。

誠実な声明と制限

• BizGuard はオープンソースの検証プロジェクトであり、本番ブロックに使用できることが検証されたシステムではありません。

• Java サポートは 3 つの匿名化された fixture リポジトリのみをカバーしており、完全な Java エコシステムアナライザーではありません。

• オフライン benchmark の Agent トラックは scripted/ヒューリスティックベースラインです。--live を渡して実際の Agent コマンドを設定した場合のみ、実際の Agent が実行されます。

• 検索のターゲット埋め込みモデルは智譜（Zhipu）の embedding-3 です。オフライン時はローカルの語彙検索にフォールバックし、フォールバックを明示的に示します。この結果は開発とデモに適しており、実際の埋め込みと同等の本番受け入れと見なすことはできません。

• Policy で保護された diff は、メモリ内で現在の fixture ベースに適用された後に AST 検証が行われます。ワークスペースは変更されません。diff を適用できない場合やルールがカバーしていない場合、システムは安全性を推測しません。

参加とフィードバック

貢献ガイド を読み、issue や PR を通じて新しいビジネス不変条件、fixture、再現可能なケースについて議論してください。