brevio-core

brevio-core

コーディングエージェントがマージ前に繰り返すミスを検出します。モデル呼び出しも API キーも不要なプルリクエストゲートです。

これを .github/workflows/brevio-core.yml として保存します。

name: brevio-core
on:
  pull_request:
  merge_group:
permissions:
  contents: read
  pull-requests: write     # the comment on the pull request
  security-events: write   # the upload to code scanning
jobs:
  brevio-core:
    name: brevio-core
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          fetch-depth: 0
      - uses: Brevio-Ventures/[email protected]
        with:
          sarif: true

エージェントが書いたコードでレビュー時に繰り返し見つかる問題を検出します。

• ソースコードに書き込まれたシークレット、入力に対する eval、外部データへの any キャスト。
• @ts-ignore で隠された型エラー、捕捉されたまま破棄される例外。
• エンドツーエンドテストの固定スリープ、alt テキストのない画像、キーボードでは操作できないクリックハンドラー。

API キーもモデルも不要です。scan、エージェントフック、MCP サーバーはネットワークを使わず、何も送信しません。

これらは、AST やデータフローの分析ではなく、変更によって追加された行を対象とする行単位のパターンチェックです。カタログには123のルールがあります。brevio-core scan がチェックするのはスキャン対象の8ルールで、残りの115ルールはドキュメント化されており、レビューやエージェント向けに記載されていますが、このパッケージにはまだスキャナーがありません。各検出結果から、検出内容、理由、悪い例と良い例を説明するルールページに移動できます。

インストールせずに実行する

バージョン0.6.0、Python 3.10以降、実行時依存関係はありません。リポジトリで、変更によって追加された行をスキャンします。

uvx [email protected] scan --diff

pipx run --spec brevio-core==0.6.0 brevio-core scan --diff

または、インストールしてから同じように実行します。

pip install brevio-core==0.6.0

brevio-core scan --diff

または、GitHub リリースから brevio-core.pyz をダウンロードし、ビルド元を確認して、任意の python3 で実行します。

gh attestation verify brevio-core.pyz --repo Brevio-Ventures/brevio-core
python3 brevio-core.pyz scan --diff

ファイル全体をスキャンするには、ファイル名を指定するか、現在のフォルダーを対象にする場合は何も指定しません。

brevio-core scan

1ステップでセットアップする

brevio-core init --dry-run

--dry-run は、brevio-core init が書き込む内容を差分として表示し、何も書き込みません。init は、上記のようなプルリクエスト用ワークフロー（このリリースに固定）、AGENTS.md 内のエージェントルールのブロック、ベースラインを書き込み、初回のローカル実行で何も検出されないようにします。--with precommit,hook,mcp を指定すると、pre-commit の設定、エージェントフック、MCP サーバーの設定が追加されます。書き込み前に確認を求め（--yes を指定すると確認を省略します）、既存ファイルは上書きせず、書き込んだ内容を .brevio/init.json に記録します。brevio-core init --undo は、書き込み後に変更されていない内容を削除します。

検出結果のある既存リポジトリに導入する

brevio-core baseline                 # record the findings the repository has now in .brevio/baseline.json
brevio-core scan                     # report only the findings that are not in the baseline
brevio-core scan --fail-on none      # report them but never fail, for a trial week
brevio-core scan --fail-on all       # leave the baseline out: every finding fails

ベースラインの各エントリには、行番号ではなくファイル、ルール、行のテキストのハッシュが記録されるため、行を移動しても新たな検出結果にはなりません。このファイルをコミットしてください。修正後に baseline を再実行すると、修正済みのエントリが削除されます。ファイルには1行につき1エントリがソート順で記録されるため、エントリを追加するブランチ同士でもスムーズにマージできます。

理由を添えて検出結果を1件無視する

// brevio-core: ignore R9.2 -- the generated client has no type for this field
// @ts-ignore

コメントは対象行またはその直前の行に記述すると、その行の該当ルールを無視します。-- reason がない場合は無視されず、そのコメントと存在しないルール ID についてスキャン時に警告されます。サマリー行には無視された件数が表示され、SARIF ではそれぞれが理由付きの抑制として記録されます。これはコードスキャンで表示されます。

ゲートを無視できるのは人間だけです。エージェントフックと MCP ツールは無視コメントを決して受け付けず（--forbid-ignores）、差分スキャンでは、変更によって追加された無視コメントとベースラインエントリをそれぞれ検出結果として報告します。レビュー担当者が --allow-new-suppressions で許可するまでは、「新しい抑制：人によるレビューが必要」と表示されます。

プルリクエスト向けのレポート

brevio-core scan --diff origin/main --format markdown は、ルール、ファイル、行、理由を記載した Markdown テーブル形式で検出結果を出力します。ジョブのサマリーやプルリクエストのコメントに利用できます。--rules-url BASE を指定すると、各ルール ID から、BASE の後ろに ID を付けたルールページにリンクします。リポジトリ内のパスと行はエスケープされるため、ファイル名によってメンションやリンクが追加されることはありません。

チーム向けに設定する

リポジトリのルートに brevio-core.toml を置き、独自の設定が必要なフォルダーにも同じファイルを置きます。ファイルには、ルートからそのファイルのフォルダーまでの設定が順に適用され、最も近いファイルの設定が優先されます。

extends = "policy/brevio-core.toml"   # an org policy, read first (see below)
select = ["R9", "R13.1"]              # the rules that run: an ID, a group or a glob (default: every rule)
ignore = ["R6.3"]                     # rules that do not run
exclude = ["generated/**", "*.pb.ts"] # paths not scanned, relative to this file's folder
level = "warn"                        # the level of every rule (default: error)

[rules."R13.1"]
level = "error"                       # the level of one rule

[[overrides]]
paths = ["legacy/**"]                 # relative to this file's folder
ignore = ["R9.1"]                     # rules that do not run on these paths
rules = ["R9"]                        # the rules the level applies to (default: every rule)
level = "warn"

より近いファイルの設定では select と ignore が置き換えられます。exclude と [[overrides]] は累積されます。同じ階層では、ルールを指定する最後の設定が優先されます。不明なキー、無効な値、または形式が壊れたファイルがあると、使用エラーとしてスキャンが停止します。どのルールにも一致しないルールパターンは警告になります。ルール ID は、[rules."R13.1"] のように、テーブル名として引用符で囲んで記述してください。

スキャンでは、プロジェクトが保持しているものの自ら作成したのではないコードは、すでにすべて対象外です。依存関係とビルド出力（node_modules/、dist/、build/、.next/、仮想環境）、ベンダー提供のフォルダー（vendor/、third_party/、third-party/）、圧縮ファイル（*.min.js、*.min.mjs、*.min.cjs、*.min.css）、バンドルのチャンク（*.chunk.js、*.bundle.js、chunk-*.js、index-<hash>.js のように16進数のハッシュで終わる名前のファイル）、および最初の2行がそれぞれ500文字を超えるファイルが対象です。コマンドラインで指定したファイルは、指定どおりにスキャンされます。名前の指定にかかわらず、ルールが TypeScript の宣言ファイル（*.d.ts、*.d.mts、*.d.cts）を読み取ることはありません。宣言ファイルには実行されるコードではなく、型が記述されているためです。生成コードや、別の名前のサードパーティフォルダーなどを追加で除外するには、exclude を使います。

brevio-core config src/app.ts を実行すると、ファイルまたはフォルダーに適用される内容を確認できます。適用元のファイル、除外対象かどうか、そこで実行される各ルールとそのレベルおよびステータスが表示されます（ツール向けには --json を指定します）。

brevio-core scan --fail-on error（Action では fail-on: error）は、エラーレベルの検出結果がある場合にのみ失敗し、警告レベルの検出結果も報告します。デフォルトの --fail-on new は、レベルにかかわらず、新しい検出結果があるたびに失敗します。プレビュー状態のルールではスキャンは失敗しません（RULES-STABILITY.md を参照）。設定でルールを無効にできるため、差分スキャンでは、brevio-core.toml の追加や編集も、ignore コメントと同様に、新しい抑制として報告されます。

extends を使った組織ポリシー

extends は、それを指定するファイルを読み込む前にポリシーファイルを読み込みます。ポリシー内のパスは、そのファイルがあるフォルダーを基準にします。

• extends = "policy/brevio-core.toml"：リポジトリにベンダーとして含めたファイルで、自分たちの履歴によってバージョンが固定されます。
• extends = "policy@<commit SHA>"：そのコミットでチェックアウトされた、サブモジュールなどのフォルダーです。
• extends = "<git URL>@<commit SHA>"：.gitmodules 内の URL が指定した URL と一致するサブモジュールを、そのコミットで使用します。

extends が読み込むのは、チェックアウト済みのファイルだけです。brevio-core はポリシーを取得しません（scan、エージェントフック、MCP サーバーはネットワークを使わず、何も送信しません）。チェックアウトがない場合や、別のコミットになっている場合はスキャンが停止し、その旨が表示されます。その場合は git submodule update --init を実行してください。新しいポリシーに切り替えるには、プルリクエストでサブモジュールと SHA をまとめて更新します。

段階的に導入する

1. 状況を確認する。 CI で1週間、brevio-core scan --fail-on none を実行します。すべてが報告され、失敗することはありません。
2. 新しい検出結果を警告にする。 brevio-core baseline で現状を記録し、brevio-core.toml で level = "warn" を設定して、--fail-on error を実行します。新しい検出結果はプルリクエストに表示されますが、処理はブロックされません。
3. 新しい検出結果でブロックする。 信頼できるルールの level = "error" を、1つずつ、または準備ができたパスに対する [[overrides]] を使って引き上げます。これらの新しい検出結果がチェックを失敗させるようになります。
4. さらに厳しくする。 ベースラインの項目を修正して brevio-core baseline を再実行し、それらを削除します。残りのルールも error に引き上げてから、デフォルトの --fail-on new に戻します。

GitHub Enterprise Server

GitHub リリースの .pyz をリポジトリにベンダーとして含めて使う方法と、pip 用の PyPI ミラーを使う方法に対応しています。未テストのため、GitHub Enterprise Server で実行した人はいません。

エージェントから使用する

すべてローカルで使える3つの方法があります。モデル呼び出しもAPIキーも不要です。

コーディングエージェントにスキャンを組み込みます。 プロジェクトフォルダーで：

brevio-core hook install

フォルダーまたはマシンに設定されているコーディングエージェントを検出し、それぞれにスキャンを追加するため、編集のたびにルールに照らしてチェックされます。また、エージェントにコマンドを実行するタイミングと検出結果の読み方を伝えるエージェントスキル（skills/brevio-core/SKILL.md）もインストールします。古いスキルの内容は置き換えられ、2回目の実行では変更はありません。

MCP サーバーとして実行します。 stdio 経由の MCP サーバーに対応するクライアントの mcpServers ブロックに、次の内容を追加します（設定ファイルはクライアントごとに異なりますが、形式は同じです）。

{
  "mcpServers": {
    "brevio-core": {
      "command": "brevio-core",
      "args": ["mcp"]
    }
  }
}

グローバルインストールをせずに使う場合は、"command": "uvx" と "args": ["[email protected]", "mcp"] を使用します。クライアントはプロジェクトフォルダーで起動してください。サーバーが読み取るのはそのフォルダーだけです。ツールには、scan（パスまたは差分のベース）、explain（ルール ID を指定し、ルールのページを返します）、list_rules、learn（修正済みの不具合をガードに変換します）があります。

修正から学習します。 brevio-core learn は最後の修正をガードに変換します。learn、hook install、gain、add、mcp についてはdocs/agent-tools.mdを参照してください。

ESLint、Biome、typescript-eslint がカバーしないこと

リンターはコードの書き方、つまり構文、型、スタイルをチェックします。エージェントが起こすミスの中には、これらのツールでは有効なコードとして扱われるものがあり、これらのルールはそうしたミスを検出します。ルールのページから：

ESLint、Semgrep、CodeQL との比較

brevio-core はこれらを補完するものであり、引き続き併用してください。

• これらのツールが得意とすること。 コードを解析するため、型、構文木、さらに Semgrep と CodeQL では複数行や複数ファイルにまたがるデータの流れも検出できます。ルール数がはるかに多く、エディターとの連携機能もあります。brevio-core は追加した行を1行ずつパターン照合するため、複数行にまたがるミスを見逃したり、文脈上は問題のない行を検出したりすることがあります。
• brevio-core が追加すること。 コーディングエージェントが繰り返すミスから選んだルール、編集のたびにスキャンするエージェントフック、エージェントが呼び出せる MCP サーバー、1つの修正をローカルガードに変換する learn、そして人とエージェント向けに書かれたルールごとのページです。設定も依存関係も不要です。

使用方法

brevio-core scan src/                 # files or folders
brevio-core scan --diff origin/main   # only the lines added against a base
brevio-core scan --diff --sarif out.sarif

何も検出されなかった場合の終了コードは0、検出結果がある場合は1、使用方法に誤りがある場合は2です。

正しい修正方法が1つだけあるものを修正する

brevio-core scan --fix --dry-run    # print the fixes as a unified diff, write nothing
brevio-core scan --fix              # rewrite the files in place, then scan again
brevio-core scan --fix --diff main  # fix only the lines your change adds

コードによって適用できる正しい書き換えが1つだけある場合に限り、ルールに修正機能が追加されます。モデルは使用しません。たとえば、@ts-ignore コメントは @ts-expect-error に、Python の except: は同じ対象を捕捉する except BaseException: に変換されます。それ以外の検出結果、とりわけハードコードされたシークレットは報告されますが、変更されません。コマンドは修正した内容と残っている内容を出力し、残りがある場合は失敗します。2回実行しても、2回目には何も変更されません。MCP サーバーには、同じ差分を返し、要求された場合にのみ書き込む fix ツールがあります。

GitHub Action

先頭のワークフローは、プルリクエストで追加された行をスキャンします。レポートをジョブのサマリーに書き込み、変更されたファイル上に各検出結果を表示します。pull-requests: write を指定すると、検出結果がある間はプルリクエスト上のコメントを1つ最新の状態に保ち、検出結果がなくなると解決済みとしてマークします。フォークからのプルリクエストではサマリーのみが表示されます。sarif: true と security-events: write を指定すると、検出結果をコードスキャンにアップロードします。シークレットもAPIキーも不要です。タグ v0.6.0 は、正確に brevio-core 0.6.0 を実行します。すべてのリリースを追跡するには、代わりに uses: Brevio-Ventures/brevio-core@v0 と記述してください。コミットを固定する場合は、SECURITY-REVIEW.mdを参照してください。pull_request、merge_group、push で実行され、それ以外のイベントは拒否します。

pre-commit

repos:
  - repo: https://github.com/Brevio-Ventures/brevio-core
    rev: v0.6.0
    hooks:
      - id: brevio-core

ルール

各ルールのページはdocs/rulesにあります。検出対象、その理由、代わりにどう書くべきかを説明しています。

主張していないこと

このリリースではベンチマークを公開していません。再現可能なベンチマークが用意できたら、その手法とデータを数値とともに公開します。

質問とサポート

質問やルールの提案は GitHub Discussions で受け付けています。バグや誤検知は、フォームを使って issue として報告してください。サポートはベストエフォートで提供しており、1 週間以内に初回の返信を行います （SUPPORT.md）。

プロジェクト

• セキュリティレビュー：セキュリティチーム向けに、実行、読み取り、書き込みの内容を説明します
• コントリビューション（サインオフが必要）：このリポジトリのエクスポート方法と、コントリビューションを取り込む方法を説明します
• ガバナンス：公開を続ける内容とメンテナーの追加方法を説明します。次回リリースについてはロードマップをご覧ください
• セキュリティ
• プライバシー
• 行動規範
• 商標ポリシー

Brevio が作成しました。