Lachesis

Lachesis

Lachesis はコードを読み取り、そのマップを作成します。そのマップに質問して、たとえば、この関数を呼び出しているのは誰か、この値はどこに渡されるのか、危険な箇所に不正な入力が到達する可能性はあるか、といったことを調べられます。

C、Python、TypeScript/JavaScript に対応しており、すべてを 1 つのマップにまとめます。

これは何ですか？

grep などの検索ツールでわかるのは、コード内の 単語がどこに現れるか です。Lachesis は異なります。実際のデータの流れを追跡します。値がどこから来て、次にどこへ進むのか、また、外部からのリクエストが危険な処理に到達する可能性があるかどうかを調べられます。たとえば、手前にログインチェックのないデータベース呼び出しなどです。

そのために、テキストパターンから推測するのではなく、コンパイラーと同じ方法でコードを読み取ります。そのため、名前が変更されていたり、変則的な方法でインポートされていたりしても、呼び出しを見落としません。

使い方は 3 通りあります。ターミナルのコマンドとして、Python ライブラリとして、または AI エージェントが利用できる MCP サーバーとして使えます。

クイックスタート

インストールして、フォルダーを指定します。

python -m pip install lachesis-cpg
lachesis ./my-project

マップを作成して保存し、リードを出力します。リードとは、外部からの入力がチェックを経ずに機密情報に到達する可能性のある箇所です。それぞれのリードは調査すべき疑問点であり、最終的な結論ではありません。

  ✓ compiling (0.7s)
  2,677 nodes, 4,539 edges from typescript-compiler-api
  ✓ finding entrypoints that reach sensitive effects (0.1s)

2 leads (lens=all)
  1. [0.810] handleWebhook (http/webhook.ts:10, route) -> findById(documentId) [database]
     a caller that passes no recognized guard can read or write data
     through findById(documentId) starting from handleWebhook
  2. [0.810] handleWebhook (http/webhook.ts:10, route) -> findById(invoiceId) [database]
     this function branches on something, but no login-style check is seen here

フォルダーの代わりに Git URL を指定することもできます。 lachesis https://github.com/owner/repo と実行すると、コードを一時フォルダーにダウンロードしてスキャンした後、クリーンアップします。

プロジェクトの初回スキャンには時間がかかります。その後、マップは ~/.lachesis/cache にキャッシュされるため、以降の実行は高速です。

3 通りの使い方

ターミナル。 lachesis コマンド 1 つで使えます。lachesis ./repo が手軽な入り口です。より細かく制御したい場合は、次の 3 つのパスに分けて実行できます。

lachesis build   ./my-project graph.kuzu     # step 1: read the code, build the map
lachesis enrich  graph.kuzu                   # step 2: work out the data flow
lachesis analyze graph.kuzu --summary         # step 3: print the leads
lachesis explain graph.kuzu tree.c:1487       # show all the evidence for one spot

Python ライブラリ。 マップを一度開けば、好きなだけ質問できます。

import lachesis

a = lachesis.Analysis.build("./my-project", "graph.kuzu", enrich=True)
leads = a.scan()
print(leads.summary())

print(a.explain_sink("tree.c", 1487))   # all the evidence for one spot

実行可能なサンプルスクリプトは examples/ にあります。

MCP（AI エージェント向け）。 サーバーを起動すると、エージェントが自分でマップを作成してクエリできます。

lachesis mcp ./my-project

Cursor、VS Code、Claude、Docker でのセットアップについては、以下の MCP をご覧ください。

質問できること

マップを構築したら、次の操作ができます。ターミナルや Python ライブラリから実行することも、エージェントが使う MCP ツールとして利用することもできます。

知りたいこと	ツール
このコード部分は何を中心に構成されていますか？	hubs
この名前はどこにありますか？	search
これを呼び出すのはどれですか？ これは何を呼び出しますか？	callers, callees
実際のソースを表示してください	read_body
このファイルやフォルダーには何がありますか？	open_file, open_folder
この値はどこに流れますか？ この箇所には何が入力されますか？	flow, sources_of
この入力はその箇所に到達しますか？	reaches（経路を表示するか、明確に到達しないことを示します）
このポインターは何を指していますか？	points_to, aliases
外部入力はどこで危険なものに到達しますか？	taint
この C オブジェクトは二重に解放されているか、解放後に使用されていますか？	C のライフタイム解析
機密性の高い箇所に到達するエントリーポイントのうち、チェックのないものはどれですか？	scan（手がかりを提示します）
ある箇所についてのすべての根拠を、1 回の呼び出しで表示	explain

すべての回答には確信度が示されます。正確なリンクもあれば、安全な推測もあります。Lachesis は推測していることを隠さず、その旨を伝えます。回答は判定ではなく、根拠としてお読みください。

MCP

マップを構築した場所で lachesis mcp を実行します。graph.kuzu のパスを渡すこともできますが、必須ではありません。引数なしで起動し、リポジトリを指定すると、エージェントが独自のマップを構築します。

ワンクリック（uvx を使用。インストール不要）：

 

または、手動で設定します。パッケージがすでにインストールされている場合：

{
  "mcpServers": {
    "lachesis": { "command": "lachesis", "args": ["mcp"] }
  }
}

または、初回実行時に uvx で取得します。インストールは不要です：

{
  "mcpServers": {
    "lachesis": { "command": "uvx", "args": ["--from", "lachesis-cpg", "lachesis", "mcp"] }
  }
}

または、3 つの言語すべてがイメージに含まれている Docker で実行します：

{
  "mcpServers": {
    "lachesis": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/your/project:/src",
               "ghcr.io/unboundcompute/lachesis:edge"]
    }
  }
}

クライアントに関する詳細は、docs/queries.md をご覧ください。

言語

各言語は実際のコンパイラーまたは独自のパーサーで解析され、テキストから推測することはありません。

言語	解析方法	ファイルの種類
TypeScript / JavaScript	TypeScript コンパイラー	.ts .tsx .mts .cts .js .jsx
Python	Python 独自の ast + symtable	.py .pyi
C	Clang	.c .h

複数の言語が混在するプロジェクトも、3 つのマップではなく 1 つのマップです。Python の関数と、それが呼び出す TypeScript の関数は同じマップに含まれ、両方をまたいで同じツールを使用できます。

知っておくべき制限が 2 つあります。Python には型チェッカーがないため、属性の呼び出しは名前で照合します。C は一度に 1 つのファイルを解析するため、見えない関数ポインターテーブルを介した呼び出しは追跡できません。各言語で可能なことと不可能なことは、それぞれ明示されます。

仕組み

Lachesis は3つのステップで動作し、それぞれがコマンドです。

1. build：実際のコンパイラーでコードを読み込み、シンボルと呼び出しのシンプルなマップを作成します。ここが高速な処理で、ナビゲーションに必要な作業のほとんどはこれだけです。
2. enrich：マップ上でデータがどのように流れるかを調べます。これはビルド時には行いません。質問に応じて、必要なフローだけを計算してキャッシュします。
3. analyze：マップを調べ、手がかりを出力します。脆弱性が潜む箇所にスコアを付け、既知のバグのパターンと照合します。制限時間があるため、大規模なプロジェクトでも処理が止まることはありません。

C のライフタイムパスもあります。同じオブジェクトを2回解放したり、解放後に使ったりするバグは、1つの箇所だけに関係するものではありません。オブジェクトのライフサイクル全体に関わります。別のパスで、各 C オブジェクトの割り当て、解放、使用を追跡し、二重解放と解放後の使用を、発生までの経路とともに報告します。

マップはフォルダー（graph.kuzu）として保存されます。埋め込みデータベースと小さなインデックスファイルが含まれています。このフォルダー自体がマップです。すべてのツールがこれを直接読み込みます。

詳しくは、docs/graph-model.md（マップの内容）とdocs/scaling.md（大規模なリポジトリ、メモリ、速度）をご覧ください。

インストール

python -m pip install lachesis-cpg

Python 3.10～3.12 で動作します。Python の解析に追加の依存関係は必要ありません。TypeScript／JavaScript のスキャンには PATH 上の node が、C のスキャンには clang が必要です。どちらかが見つからない場合は、クラッシュせずに明確なメッセージが表示されます。

クローンから作業する場合（コントリビューター向け）：

git clone https://github.com/UnboundCompute/lachesis && cd lachesis
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
npm ci
cargo build --release --manifest-path native/clang_frontend/Cargo.toml

次に読むもの

• examples/：5分で読めるガイドと、機能ごとに実行可能なスクリプトです。
• docs/graph-model.md：マップの内容です。
• docs/queries.md：質問するすべての方法です。
• docs/scaling.md：大規模なリポジトリ、メモリ、CI について説明します。

ロードマップ

最近完了した項目：

• C のライフタイムバグ。 C オブジェクトの二重解放と解放後の使用を、発生までの経路とともに検出します。問題のない経路では誤検知しません。
• 大規模なリポジトリ。 複数言語にまたがる大規模なツリーを並列に分割してビルドし、1つのマップに統合します。設定したメモリ予算内に収まります。
• Git URL を直接スキャン。 https://… を指定すると、ダウンロード、スキャン、後片付けを行います。
• 1つのツールに3つの入口。 ターミナルコマンド、Python ライブラリ、MCP ツールで同じコードを利用できます。

今後の予定：

• 関数をまたいだ C のライフタイムバグ：ある関数で解放し、別の関数で使用する場合。
• 「この入力はこの箇所に到達するか？」を一度に尋ねる質問：ファイルと言語をまたいで、経路または明確な「いいえ」を返します。

ステータス

Lachesis は初期段階にあり、急速に開発が進んでいます。マップ、ストレージ、ナビゲーションと MCP ツール、C のライフタイムパスはすべて現在動作しており、テストスイートで検証されています。ライフタイムパスは現時点では C のみを対象とし、1つの関数内で動作します。既知の誤検知が1件あり、追跡中です。1.0 までにツールが変更される可能性があります。変更内容はCHANGELOGに記載されています。

ライセンス

AGPL-3.0 です。LICENSEをご覧ください。商用利用を含め、使用、調査、変更、共有が可能です。変更したバージョンをネットワークサービスとして実行する場合は、利用者に変更後のソースコードを共有する必要があります。この条件が合わない場合は、別途商用ライセンスを利用できる可能性があります。CONTRIBUTING.mdをご覧になるか、イシューを作成してください。

セキュリティ

セキュリティバグを見つけましたか？ 公開イシューは作成しないでください。非公開での報告方法については、SECURITY.mdをご覧ください。