RAPx: Rustプログラムのための静的解析ツール
RAPx: A static analysis tool for Rust programs (github.com)
要約
RAPx (Rust Analysis Platform with Extensions) は、Rustプログラム向けの高度な静的解析プラットフォームです。標準のrustcコンパイラを超える拡張可能なフレームワークを提供し、開発者が安全性、堅牢性、パフォーマンスをより深く理解できるようにします。このツールは、バグ検出、最適化機会の発見、アノテーション付き関数の検証など、多様な機能を提供します。
全文翻訳
[画像: license: MPL 2.0][画像: docs.rs] RAPx(Rust Analysis Platform with Extensions)は、Rust向けの高度な静的解析プラットフォームです。標準のrustcコンパイラでは利用できない、より強力な解析機能を構築・統合するための拡張可能なフレームワークを提供し、開発者が安全性、堅牢性、パフォーマンスについてより深く理解できるよう支援します。
RAPxはcrates.ioで利用可能です。[画像: crates.io]
特徴
[画像: logo]
RAPxは2つの層に分かれています。コア層は、エイリアス解析やデータフロー解析などの基本的なプログラム解析アルゴリズムを提供し、アプリケーション層はバグ検出などの特定のタスクを実装します。この関心の分離は、モジュール開発を促進し、アルゴリズム開発者とアプリケーション開発者の間の協力を育みます。
プロジェクトはまだ活発に開発中です。詳細については、RAPx-Bookを参照してください。
クイックスタート
rapxがコンパイルされる最新のnightlyツールチェーンをインストールしてください。これはマシン上で一度だけ実行すれば十分です。ツールチェーンが存在する場合は、何も行われません。
rustup toolchain install nightly --profile minimal --component rustc-dev,rust-src,llvm-tools-preview
cargo +nightly install rapx --git https://github.com/safer-rust/RAPx.git
使用方法
Cargo.tomlファイルを含むRustプロジェクトフォルダに移動します。次に、ツールチェーンオーバーライドのショートハンド構文に従ってツールチェーンのバージョンを手動で指定してrapxを実行します。
cargo +nightly rapx [rapx オプション] -- [cargo check オプション]
または、必要なバージョンにデフォルトのツールチェーンを設定することでも可能です。
rustup default nightly
--以降のすべてはそのままcargo checkに転送されるため、--targetやその他のcargoフラグはクロスコンパイルされたクレートやベアメタル(#![no_std])クレートでも機能します。
# ベアメタルターゲット用のno_stdカーネルクレートを検証する
cargo rapx verify --crate ostd -- --target x86_64-unknown-none
ここでostdはasterinas/asterinasのカーネルクレートです。
ターゲットが事前にインストールされていることを確認してください(rustup target add x86_64-unknown-none)。
サポートされているオプションは-helpで確認できます。
$ cargo rapx --help
Usage: cargo rapx [OPTIONS] <COMMAND> [-- [CARGO_FLAGS]]
Commands:
analyze クレートに対して様々な解析を実行します。例: エイリアス解析、コールグラフ生成
check クレートの潜在的な脆弱性をチェックします。例: use-after-free、メモリリーク
opt コード最適化の機会を検出します
verify クレート内のアノテーション付き関数を検証します。例: #[rapx::verify]ターゲットを特定します
help このメッセージまたは指定されたサブコマンドのヘルプを表示します
Options:
--timeout <TIMEOUT> rapxの実行時間を秒単位で指定します
--test-crate <TEST_CRATE> ワークスペース内のテスト対象パッケージを指定します
-h, --help ヘルプを表示します
-V, --version バージョンを表示します
NOTE: 複数の検出を一度の実行で処理できます。
オプションを引数に追加してください。例: `cargo rapx check -f -m` は2種類の検出を連続して実行します。
Examples:
1. use-after-free とメモリリークを検出する:
cargo rapx check -f -m
2. 最適化の機会を検出する:
cargo rapx opt
3. エイリアス解析を実行する:
cargo rapx analyze alias
4. アノテーション付き関数を検証する:
cargo rapx verify --prepare-targets
analyze コマンド
Usage: cargo rapx analyze <COMMAND>
Commands:
alias エイリアス解析(デフォルトはmeet-over-paths)
adg API依存グラフ
callgraph コールグラフ生成
dataflow データフローグラフ
heapowner ヒープ所有型を解析します
paths パスセンシティブなCFGパス
range 範囲解析
scan 基本的なクレート情報
mir MIRを表示します
dot-mir MIRをDOT形式で表示します
help このメッセージまたは指定されたサブコマンドのヘルプを表示します
Options:
-h, --help ヘルプを表示します
check コマンド
Usage: cargo rapx check [OPTIONS]
Options:
-f, --uaf [<UAF>] use-after-free/double-freeを検出します(オプションレベル、デフォルトは1)
-m, --mleak メモリリークを検出します
-h, --help ヘルプを表示します
opt コマンド
Usage: cargo rapx opt
verify コマンド
verifyコマンドは、#[rapx::verify]でアノテーションされた関数に対する契約ベースの検証パイプラインを提供します。パスセンシティブな後方/前方解析とZ3ベースのSMTソルバーを使用して、安全プロパティを証明します。
Usage: cargo rapx verify [OPTIONS]
Options:
--prepare-targets #[rapx::verify]関数を特定し、その安全契約をリストします
--postfix-repeat <N|auto> パス列挙中のSCCポストフィックス繰り返し回数(`auto`は自動ループ深度検出を有効にします)(デフォルト auto)
--mode <MODE> 検証モード: scan、targeted(デフォルト scan)
--skip-invariant 構造体不変条件チェックをスキップし、コンストラクタ・ミューテータ・メソッドチェーンを通じて安全性を導出します
--debug-contracts デバッグ目的で展開された契約アサーションを表示します
--crate <CRATE> 検証ターゲットを特定のクレート(Rustクレート名またはCargoパッケージ名)に絞り込みます
--module <MODULE_PATH> 検証ターゲットをクレート内の特定のモジュールパスに絞り込みます
-h, --help ヘルプを表示します
検証モード:
scan— 自動検出: unsafeな呼び出し元または構造体不変条件を持つすべての関数を検証します。targeted—#[rapx::verify]でアノテーションされた関数のみを検証します。
オプション:
--skip-invariant— 両方のモードで使用可能。構造体不変条件チェックをスキップし、代わりにコンストラクタ・ミューテータ・メソッドチェーンから安全要件を自動的に導出します。
ターゲットのフィルタリング: --crateと--moduleはどのモードでも機能し、組み合わせることができます。標準ライブラリワークスペースまたはサブワークスペースを解析する場合:
# 特定のモジュールを検証する(単一クレートまたはワークスペース)
cargo rapx verify --module my_mod::sub
# ワークスペース内の特定のクレートを検証する
cargo rapx verify --crate my_crate
# 精密なターゲティングのために両方を組み合わせる(例: 標準ライブラリ)
cargo rapx verify --crate core --module ptr::NonNull
cargo rapx verify --crate std --module collections::vec
--moduleが--crateなしで使用される場合、後方互換性のためにcrate_name::moduleプレフィックスも受け入れられます(例: --module core::ptrはcore::プレフィックスを自動的に削除します)。
#![feature(register_tool)]
#![register_tool(rapx)]
#[rapx::verify]
fn init_buffer(buf: *mut u32, len: usize) {
unsafe {
// rapxチェック: NonNull(buf), Align(buf, u32), InBound(buf, len)
core::ptr::write(buf.add(len - 1), 0);
}
}
#[rapx::requires(NonNull(_ptr))]
unsafe fn custom_ptr_op(_ptr: *const i32) -> i32 {
unsafe { *_ptr }
}
生のポインタを保持する構造体フィールドは、#[rapx::invariant(...)]アノテーションを持つことができます。メソッドはエントリ時に不変条件を仮定し(コンストラクタは戻り時にそれらを再確立します)、これによりRAPxは、ポインタの出所が関数本体ではなく型の不変条件内にあるような、連結リストのDrop実装のようなパターンを検証できます。
// nullの可能性があるフィールドは `any(...)` コンビネータを使用します(論理OR。括弧内のカンマは論理ANDを意味します)。ポインタがnullでない場合はすべてのプロパティが成り立ち、nullの場合は空虚に成り立ちます。
#[rapx::invariant(any(Null(next), (Align(next, Node), ValidPtr(next, Node, 1), Allocated(next, Node, 1), Typed(next, Node), Owning(next))))]
struct Node {
value: i32,
prev: *mut Node,
next: *mut Node,
}
// Option<NonNull<T>> フィールドは `unwrap_some()` で同じ条件付き表現をします。
// プロパティはSomeペイロードのみを制約します。
#[rapx::invariant(Align(head.unwrap_some(), Node))]
#[rapx::invariant(Allocated(head.unwrap_some(), Node, 1))]
#[rapx::invariant(Typed(head.unwrap_some(), Node))]
#[rapx::invariant(Owning(head.unwrap_some()))]
struct List {
head: Option<core::ptr::NonNull<Node>>,
}
tests/verify_cases/linked_list_rawptrおよびtests/verify_cases/linked_list_nonnullを参照してください。これらは、(Drop内のBox::from_rawを含む)エンドツーエンドで証明された完全な例です。
安全プロパティには、Align、NonNull、Allocated、InBound、Init、ValidPtr、Deref、Ptr2Refなどが含まれます。完全なリストについては、RAPx-Bookを参照してください。
検証プロパティサポートチェックリスト
このチェックリストは、RAPxの契約検証をsafer-rust/safety-tagsで定義されたプリミティブ安全プロパティにマッピングします。
凡例: ✅ = 完全なZ3ベースSMT検証(SOUND/UNSOUNDの判定結果を生成) — = まだ検証されていません(解析はされたがSMTへの降下はなし)
| safety-tag | 例 | サポート状況 |
|---|---|---|
Align | Align(p, T) | ✅ |
Size | Size(T, c) | ✅ |
NoPadding | !Padding(T) | ✅ |
NonNull | !Null(p) | ✅ |
Allocated | Allocated(p, T, len, A) | ✅ |
InBound | InBound(p, T, len) | ✅ |
NonOverlap | !Overlap(dst, src, T, len) | ✅ |
ValidNum | ValidNum(exp, vrange) | ✅ |
ValidString | ValidString(arange) | ✅ |
ValidCStr | ValidCStr(p, len) | ✅ |
Init | Init(p, T, len) | ✅ |
Unwrap | Unwrap(x, T) | — |
Typed | Typed(p, T) | ✅ |
ValidTransmute *† | ValidTransmute(T, U) | ✅ |
SplitTransmute *† | SplitTransmute(T, U) | ✅ |
Owning | Owning(p) | ✅ |
Alias | Alias(p1, p2) | ✅ |
Alive | Alive(p, l) | ✅ |
Pinned | Pinned(p, l) | — |
NonVolatile | !Volatile(p, T, len) | — |
Opened | Opened(fd) | — |
Trait | Trait(T, trait) | ✅ |
Unreachable | !Reachable() | — |
ValidPtr * | ValidPtr(p, T, len) | ✅ |
Deref * | Deref(p, T, len) | ✅ |
Ptr2Ref * | Ptr2Ref(p, T) | ✅ |
Layout * | Layout(p, l) | ✅ |
- 複合安全プロパティはプリミティブSPから構成されます:
Deref(p, T, len) = Allocated(p, T, len) && InBound(p, T, len)、ValidPtr(p, T, len) = Size(T, 0) || Deref(p, T, len)、Ptr2Ref(p, T) = Init(p, T, 1) && Align(p, T) && Alias(p)、Layout(p, l) = Allocated(p)。
*†ValidTransmuteとSplitTransmuteは、transmute操作のTypedの特殊化です:ValidTransmute(T, U)は、T型の値がUの有効なビットパターンであることをチェックし、SplitTransmuteは、T型の値の各size_of(U)バイトの連続チャンクが有効なUビットパターンであることをチェックします。
RAPxは、標準ライブラリ関数にプロパティタグをアノテーションした、厳選されたstdライブラリの安全契約(std-contracts.json)を同梱しています。これにより、ユーザーのアノテーションを必要とせずに、一般的なstd/core APIの契約ベース検証が可能になります。
組み込みタグを超えて、ユーザーはrapx_macrosのpred!マクロ(プリミティブ安全プロパティのブール結合)を使用して、クレート内に独自の名前付き契約を定義し、#[rapx::requires(MyTag(...))]から再ビルドせずに参照できます。
use rapx_macros::pred;
// Name(params) { body } — paramsは役割を担います: Ptr | Ty | Expr | Ident。
pred!(Readable(p: Ptr, T: Ty, n: Expr) { NonNull(p) && Align(p, T) && Allocated(p, T, n) && Init(p, T, n) });
#[rapx::requires(Readable(ptr, u8, len))]
unsafe fn read_byte(ptr: *const u8, len: usize) -> u8 {
unsafe { *ptr }
}
検証器は、core::sliceスタイルのメソッド(split_at、as_chunks/as_rchunks、as_flattened、binary_search、partition_dedup、get_disjoint_mutなど)のような、unsafeコードの上に構築された実際の安全な抽象化に対して実行されます。ここでは、RAPxは内部のunsafe操作が未定義の動作を引き起こさないことを証明します。各SMTクエリはクエリごとのタイムアウトによって制限されているため、決定不能な非線形目標はハングする代わりにunknownを返します。
環境変数(値は大文字小文字を区別しません)
| 変数 | 不在時のデフォルト | 可能な値 | 説明 |
|---|---|---|---|
RAPX_LOG | info | trace, debug, info, warn | ログの詳細度 |
RAPX_CLEAN | true | true, false | チェック前にcargo cleanを実行するかどうか |
RAPX_RECURSIVE | none | none, shallow, deep | チェックするパッケージのスコープ |
RAPXFLAGS | (unset) | CLI引数 | rapxバイナリに直接渡される引数 |
RAPX_RECURSIVEの場合:
none: 現在のフォルダをチェックします。shallow: 現在のワークスペースメンバーをチェックします。deep: 現在のフォルダからすべてのワークスペースをチェックします。
NOTE: shallowまたはdeepの場合、rapxは各メンバーフォルダに入ってチェックを実行します。
RAPxがcargo cleanの実行後に停止した場合、cargo metadataを手動で実行してメタデータ依存関係をダウンロードしてみてください。