PerspectiveGraph

スキャナーは問題を見つけます。侵入経路を見つけるのは、これです。

PerspectiveGraph は、すでに運用している Trivy、Semgrep、Cloud Custodian、Falco に、AWS と Kubernetes の状態を加え、実際の環境を表すひとつのグラフにまとめ、次の問いを投げかけます。インターネットから、広すぎる権限を経由して、盗む価値のあるものにたどり着けるでしょうか？

プルリクエストでは、マージ前にこの問いを投げかけます。チェックが失敗するのは、この変更によって経路が開かれる場合だけで、修正は独立したプルリクエストとして返されます。オープンソース（Apache 2.0）で、お客様のインフラ上で動作し、テレメトリーは収集しません。

make demo の12秒間：現在悪用可能なもの → 優先順位付けされた経路 → ある経路のキルチェーンと生成される修正 → スコアを信頼できるかどうか。実際の環境ではなく、サンプルのスキャナー出力と、あらかじめ設定された判定結果を使っています。

• 動作を確認する - 同じダッシュボードを読み取り専用で公開しています。インストールは不要です。
• ドキュメントを読む - トピックごとに1ページで構成された、検索可能なマニュアルです。
• ご自身の AWS アカウントを30秒で確認する - 読み取り専用のコマンドひとつで、デプロイは不要です。
• プルリクエストに導入する - YAML を10行追加するだけです。

ここでのスコアは、与えられた証拠からモデルが導き出した結論であり、測定された頻度ではありません。現場のデータに照らした較正はまだ行われておらず、エンジン自身がそのことを示し、数値を切り上げることはありません。測定済みのものと、未測定のもの。

30 秒で自分のアカウントを確認

デプロイも Docker も、取り込みも不要です。1 つの静的バイナリが、AWS 自身のポリシー評価機能に、どのロールが管理者権限に到達できるかを問い合わせます。ポリシーを読むだけでは分からない、サービスコントロールポリシー、権限境界、条件キーを適用して判定します。

# macOS (Apple silicon); swap darwin_arm64 for linux_amd64, linux_arm64 or darwin_amd64
curl -sSL https://github.com/luiacuaniello/perspectivegraph/releases/latest/download/perspectivegraph_darwin_arm64.tar.gz | tar xz
./perspectivegraph redteam -roles -region eu-west-1

読み取り専用で無料です。各チェックは iam:SimulatePrincipalPolicy のドライランを 1 回実行するだけで、何も作成せず、費用もかかりません。必要な権限はこれと iam:ListRoles だけで、どちらも SecurityAudit に含まれています。Windows ビルドはリリースページにあります。すべてのバイナリには cosign 署名と SLSA の来歴情報が付属しており、実行前に 2 つのコマンドで両方を検証できます。

-compare を追加すると、同じアカウントに対してエンジンも実行し、両者の判定が異なる場合はゼロ以外の終了コードを返します。エンジンで初めて実証された偽陽性が見つかり、修正が維持されているのは、この仕組みによるものです。お使いの環境で判定が異なる場合は、ご報告ください。その報告が何よりも役立ちます。ここからは、評価方法で段階を追って評価を進め、各段階で答えを得ながら、ご自身の環境について結論を出せます。

90 秒でエンジン全体を見る

make demo

公開済みの cosign 署名付きイメージを取得し、サンプルの Trivy／Semgrep／Custodian／Falco／Kubernetes／IAM／SSO の出力を入力して、生成された修正案とともに最上位の攻撃経路を表示します。ダッシュボードは http://localhost:3000 で開き、終了するには make down を実行します。必要なのは Docker、jq、curl です。コンパイルは不要で、イメージキャッシュが空の状態から約 23 秒で起動します。make demo-build は同じデモを作業ツリーからビルドします。

Kubernetes では、このチャートは Artifact Hub の公式パッケージです。

helm install perspectivegraph oci://ghcr.io/luiacuaniello/charts/perspectivegraph \
  --version 1.39.1 # x-release-please-version

Docker を実行する VM と DNS 名を備えた 1 台のマシンなら、1 つのコマンドで TLS、生成された認証情報、認証済みバス、日次バックアップを設定し、起動できます。 1 台のマシンでの本番環境。

make prod-init DOMAIN=perspectivegraph.example.com

チャートと、チャートが実行する 3 つのイメージ（ghcr.io/luiacuaniello/perspectivegraph、-dashboard、-postgres）は、cosign のキーレス署名で署名され、SPDX SBOM と SLSA の来歴情報が付属します。サプライチェーンを無条件に信頼するのではなく、検証してください。

ダッシュボードはインベントリではなく、判断事項を最初に表示します。現在悪用されているもの、最小限の変更で最大のリスクを取り除く方法、そして数値をどの程度信頼できるかです。攻撃経路はトリアージの優先度に基づいて順位付けされます。経路が到達する先、ランタイムで確認されているか、入口がどの程度公開されているかなどを考慮するため、スコアの低い経路がスコアの高い経路より上位になることがあります。

経路が P1 である理由、範囲とともに示した確率、そして攻撃者に何を可能にするか、確率の根拠がどこにあるかを示すすべてのホップ。	記録された結果と照らし合わせて、エンジン自身のスコアが妥当だったか、また判断を下せるだけの結果があるかどうか。

スクリーンショットは、シード済みの判定を使った make demo のものです。make seed-validation は、一部の経路に合成結果を記録します。これは BAS の実行で環境の一部をテストするのと同じで、キャリブレーションパネルに表示内容がある理由です。また、まだ判定結果が十分ではありませんと表示される理由でもあります。記録される少数の結果は、判定に必要な 30 件には遠く及びません。画像内の件数は撮影時のリリースのものです。サンプルデータはその後増えているため、ご利用の環境では経路が 1、2 件異なる場合があります。新規インストールと公開デモでは、実際の結果が存在するまではデータ不足と報告されます。公開デモは無料の VM 1 台で動作しているため、ベストエフォートとしてご利用ください。

なぜ必要なのか？

スキャナーは、コンテナに重大な CVE が含まれていると報告できます。しかし、そのコンテナがインターネットに公開されたロードバランサーの背後にあり、本番データベースを読み取れるロールで実行されていて、1 万件の検出結果のうち今週修正すべき唯一のものだとは報告できません。そのためには、ほかのツールの出力も同じグラフに取り込む必要があります。このツールはそれを実現します。開発者は、変更によって実際の経路が開かれた場合にのみ失敗するチェックを利用でき、セキュリティチームは平坦な検出結果の一覧ではなく、優先順位付けされた短い攻撃経路の一覧を得られます。

経路を開くプルリクエストをブロックする

デプロイは不要です。 ランナーは環境を読み取り専用で調査し、このプルリクエストのスキャン結果を取り込み、同じエンジンでプロセス内の判定を行います。

- uses: luiacuaniello/perspectivegraph@v1
  with:
    mode: local
    aws-region: eu-west-1     # read-only; give the job an OIDC role with SecurityAudit
    report: trivy.json

チェックが失敗するのは、重大な CVE が追加されたときではなく、この変更によって機密資産への経路が開かれる、またはその可能性が高まるときです。どの経路からも到達できないホストの重大な CVE ではビルドは失敗せず、本番データベースに新たに到達できるようになったコンテナの中程度の CVE では失敗します。変更前から存在していた経路は、変更が影響するものを経由していても対象になりません。スキャンは環境のコピーに適用して比較され、環境には何も書き込まれないためです。また、3 つ目の結果もあります。スキャン結果が届いていないパイプラインに、問題がないパイプラインと同じ合格マークを付けるべきではないからです。

判定	終了コード	意味
clean	0	エンジンがこの変更を分析し、重大な経路の新設や悪化がないことを確認しました
blocked	1	重大な攻撃経路を新設、または悪化させます。チェックにはその経路が表示されます
unknown	2	誰も分析していません。 スキャン、取り込み、または SHA に問題があります

Terraform のプランも、デプロイ前に同じゲートを通過します。source: terraform と terraform show -json の出力を使い、単独で判定することも、稼働中の環境と比較して判定することもできます。経路を開くセキュリティグループルール、ポリシーのアタッチメント、バケットポリシーを記述したプルリクエストはチェックに失敗します。詳しくはTerraform プランをご覧ください。

GitHub Actions 以外ではコマンド 1 つで実行でき、Trivy プラグインとしてもインストールできます。

perspectivegraph gate -local -aws-region eu-west-1 -report trivy.json -slug owner/name -sha "$COMMIT_SHA"

trivy plugin install github.com/luiacuaniello/perspectivegraph
trivy image -f json myapp:pr-42 | trivy perspectivegraph gate -local -aws-region eu-west-1 -report -

警告

フォークからのプルリクエストにはシークレットが渡されないため、ゲートはフェイルクローズし、unknown になります。pull_request_target で回避しないでください。これは、投稿者のコードに対してシークレットを実行します。ローカルモードではクラウド認証情報も実行されます。

公開リポジトリでは、チェックがブロックされると、経路（実際の資産名、CVE、機密資産）が公開ジョブログに出力されます。soft-fail を使い、詳細は非公開の場所に投稿してください。

マニュアルでは、ほかの内容も説明しています。デプロイ済みエンジンをアクションの接続先にする方法、レンダリング済みマニフェストをゲートで判定する方法、事前に収集した環境を使う方法、ゲートの段階的な導入方法、action.yml のすべての入力などです。

エージェントから問い合わせる

言語モデルは、何千ものエッジを確実に列挙したり、ダイクストラ法を実行したりできません。また、「自分のアカウントの攻撃経路」を尋ねると、もっともらしい経路をでっち上げてしまいます。そこで、エンジンは MCP に対応しています。エージェントが問い合わせ、そのエージェントだけでは作り出せない回答をもとに推論します。

perspectivegraph mcp --api http://localhost:8080   # or https://demo.a3thinker.it, no credential needed

8 つのツールはすべて読み取り専用であり、そのことは通信上でも宣言されています。統合する価値があるのは simulate_fix です。指定したエッジを切断した状態でシミュレーションを再実行し、実際に何が変わるかを報告します。このサーバーは公式 MCP Registry と Glama に掲載されています。ツールとクライアントの設定についてはマニュアルをご覧ください。

プロジェクトの状況と成熟度

エンジンとそのパブリック API は完成しており、ドキュメントも整備され、テスト済みです。スコアはまだ調整されていません。 実際の環境でこれを実行し、提示された経路を検証して、その判定結果をフィードバックした人はまだいません。このループを回す仕組みは構築・テスト済みですが、ループはまだ完了していません。そのため、スコアは測定された頻度ではなく、モデルが何を信じ、どの程度確信していると示しているかとして捉えてください。経路を見つけて排除するために使い、パーセンテージを取締役会に提示するのは避けてください。ご自身の環境で実行した場合は、結果をお知らせください。 Positioning では、主張していることと、していないことを説明しています。

v1.39.1 時点で、現在測定されている内容。 make bench-cloudgoat は、CI で 4 つの CloudGoat を想定したシナリオを使ってエンジンを評価します。

シナリオ	期待される結果	結果
ec2_ssrf	経路あり	検出、誤検出なし
iam_privesc_by_attachment	経路あり（漏えいした認証情報を起点とする）	検出、誤検出なし
ec2_private_subnet_no_path	経路なし（SG はオープン、サブネットはプライベート）	なしと判定
iam_privesc_denied_by_guardrail	経路なし（明示的な Deny が優先）	なしと判定

4 つすべてで適合率と再現率は 1.00 です。既知の形状は 4 つで、そのうち 2 つはネガティブコントロールなので、これは回帰を検出するゲートであり、お客様の環境での精度を測定するものではありません。実際の AWS では、make reachability-lab-aws が無料で同様に露出を検証し、make redteam-aws が AWS 独自のポリシー評価ツールを使って、エンジンの権限昇格に関する主張を評価します。この評価ではすでに、エンジンが無視していたパーミッション境界という誤検出が 1 件見つかりました。この問題は修正済みで、エンジンと AWS の判定が食い違うと make boundary-lab-aws が失敗します。make entrypoints-lab-aws は、バケットポリシーと関数 URL について、同様に AWS に問い合わせます。初回の実行では 4 件のエラーが見つかり、これらも修正済みです。make public-access-lab-aws は、アカウント全体に設定された Block Public Access について、無料で同様に検証します。また、make terraform-lab-aws は、マージゲートで評価された Terraform プランを適用し、それぞれが侵入経路を開いたかどうかをインターネットに問い合わせます。これらのラボはそれぞれ、検出結果をビルドに記録します。ダッシュボードの Accuracy ページでは、AWS に照らして検証済みとして、すべての質問、AWS の回答、エンジンの回答、そして質問されたときのバージョンを確認できます。

• クラウド。 AWS は稼働中で、実際のアカウントで検証済みです。複数のアカウントを一度に読み取る機能はフィクスチャでテストしており、実際のアカウントではまだテストしていません。Azure はフィクスチャのみで、GCP や OpenStack 用のコネクターはありません。それぞれの計画については、ロードマップをご覧ください。
• インターフェース。 GraphQL スキーマは凍結され、ドリフトがないことを検証しています。そのため、破壊的変更はメジャーバージョンでのみ行われ、パッチバージョンで行われることはありません：API の安定性。
• デプロイ。 バックエンドは distroless で、読み取り専用のルートファイルシステム上で非 root として実行されます。イメージはダイジェストで固定され、Helm ではすべてのワークロードが restricted Pod Security Standard を満たすことを CI で検証します。Compose のデフォルト設定では意図的に外部から接続可能になっていますが、PG_ENV=production を設定すると、API と ingest の認証が設定されていない場合は起動しません。実際のロールアウトには、さらに TLS、バックアップ、プロキシの背後での TRUSTED_PROXY_CIDRS、フェイルオーバー可能なデータベースが必要です。1 台のマシンでは make prod-init が最初の 3 つを設定し、CI は変更のたびにバックアップの 1 つを復元します。その他の項目は運用ランブックに記載されています。
• サポート。 サポート対象は最新リリースのみで、セキュリティ修正には期限を設けています（Critical：7 日、High：30 日）：SUPPORT.md。
• テレメトリー。 ありません。初期状態では外部への接続は一切行いません。GitHub、AI アシスタント、KEV/EPSS フィードは、それぞれ設定するまで無効です。
• 対象範囲。 開発者のワークフローにおける、到達可能な攻撃経路に関する問いです。スキャナーでも、CNAPP でも、コンプライアンス製品でもなく、それらの代わりになるものでもありません。
• 開発方法。 Claude（Anthropic）と協働する人間が開発しています。設計上の判断とリリース内容はメンテナーが担い、実装とテストの多くはその協働から生まれました。信頼するだけでなく、make test、make bench-cloudgoat、govulncheck ./...、CONTRIBUTINGを確認してください。

ドキュメント

• 概念を平易な言葉で - 経路、スコア、間隔、優先度、結果、キャリブレーション：ダッシュボードで使われる用語
• 独自のインフラを接続する - ノートパソコン、1 台のマシン、EKS、または任意のクラスターから、自分の AWS アカウントと Kubernetes クラスターを接続します
• マニュアル - アーキテクチャ、スコアリング、すべてのインテグレーション、デプロイ、自分の環境向けのランブック
• 評価 - 自分の環境で試す方法を、各段階で答えが得られるように説明します
• 位置付け - 主張する内容、主張しない内容、確認方法
• 運用 · 脅威モデル · スケール · API の安定性
• サポート · アップグレード · ロードマップ · セキュリティ
• コントリビューション · ガバナンス · メンテナー · 導入事例

ライセンス

Apache License 2.0。ライセンスは、REUSEの定義する形式で各ファイルに宣言されており、CI で検証されます：REUSE.toml。