pqc-scan

pqc-scan

JavaScript または TypeScript のコードベースで使用されている暗号技術と、 大規模な量子コンピューターで破られるものを一覧にします。

コンプライアンス証明書ではなく、一覧と手がかりを提供します。

pqc-scan はソースファイル、package.json とロックファイル、さらに ツリー内に記述されている TLS（Transport Layer Security）設定を読み取ります。 検出した暗号アルゴリズムすべてについて、使用しているインターフェース（Web Crypto、node:crypto、ライブラリ）、コードに記載されている場合は鍵のサイズ、コード内の場所、そして量子コンピューターで破られる各用途の移行優先度を含むレポートを作成します。このレポートは、英国の National Cyber Security Centre（NCSC）が耐量子暗号への移行スケジュールで求めている調査作業に沿っています。2028 年までに調査と計画を完了し、優先度の最も高い移行を 2031 年までに、それ以外の移行を 2035 年までに完了します。

読み取り専用です。スキャン対象を実行せず、環境変数も読み取らず、どこにも何も送信せず、テレメトリーもありません。依存関係はゼロで、Node 20 以降が必要です。無料で、コマンドライン版も引き続き無料です。将来的に、ホスト型レポート（経時的な傾向や組織全体の状況を表示するもの）が提供される可能性はありますが、同じ JSON ファイルを読み取るだけです。そのための機能はまだ構築されていません。

インストール

pqc-scan はコマンドラインツールです。コンピューターに必要なのは次の 2 つです。

1. Node.js 20 以降。 ターミナル（Windows ではコマンドプロンプト、PowerShell、または Windows ターミナル、macOS または Linux ではターミナル）で node --version を実行して確認してください。コマンドが見つからない場合、または 20 未満のバージョンが表示される場合は、https://nodejs.org から現在の「LTS」リリースをインストールしてください。Windows では通常の .msi インストーラーを使用します。既定の設定をそのまま使い、変更を反映するために新しいターミナルウィンドウを開いてください。
2. スキャナー。 最も手軽な方法では Node.js だけで済みます。手作業で何もダウンロードせず、npm レジストリから直接実行します。

   npx @microtoll/pqc-scan path/to/your/app
   

   または、一度インストールすれば、どこからでも pqc-scan として呼び出せます。

   npm install -g @microtoll/pqc-scan
   

   先にコードを確認したい場合や、レジストリを使わずに作業したい場合は、このリポジトリから次のいずれかの方法で入手してください。
   • ダウンロード：リポジトリページで Code → Download ZIP を選択し、ZIP を展開します。たとえば、Windows では C:\Tools\pqc-scan、それ以外では ~/tools/pqc-scan など、都合のよい場所に展開してください。
   • git が使える場合はクローンします。

     git clone https://github.com/microtoll/pqc-scan.git
     

ほかにインストールするものはありません。スキャナーには依存関係がないため、その中で npm install を実行する必要はありません。また、実行に設定、アカウント、ネットワーク接続も必要ありません。

実行方法

アプリケーションのコードがあるフォルダー（package.json があるフォルダー）を指定します。

Windows（PowerShell またはコマンドプロンプト）で、スキャナーを C:\Tools\pqc-scan に展開し、アプリを C:\Code\my-app に置いている場合：

C:\Tools\pqc-scan\pqc-scan C:\Code\my-app

macOS または Linux の場合：

node ~/tools/pqc-scan/bin/pqc-scan.mjs ~/code/my-app

短い概要を表示し、現在のフォルダーに2つのファイルを書き込みます。pqc-scan.md は確認用のレポート、pqc-scan.json は他のツール向けの同じ内容のレポートです。概要には両方のパスが表示されます：

pqc-scan: 6 quantum-vulnerable public-key uses in 5 files; 12 libraries; TLS groups not written down.
  272 files read; 1 High, 5 Medium, 0 Low; 2 to check by hand.
  Report: C:\Users\you\pqc-scan.md  (open it; read sections 1 and 3 first)
  JSON:   C:\Users\you\pqc-scan.json

pqc-scan.md を任意のエディターまたは Markdown ビューアーで開きます（Visual Studio Code では Ctrl+Shift+V で表示できます）。まずセクション1の概要を確認し、次にセクション3の優先事項を確認してください。そこには、High または Medium の各項目が、コードのどの行を指しているか、またその理由が記載されています。

レポートを別の場所に保存するには、ファイル名を指定します：--md C:\Reports\app.md、必要であれば --json C:\Reports\app.json。テストが test、tests、spec、__tests__ という名前のフォルダーにない場合は、ファイル名に含まれる文字列をスキャナーに伝えてください。そうすると、検出したコードのうち、テストコードがどれくらい含まれているかをレポートに記載できます：--test-files self-check。このオプションは繰り返し指定できます。

中規模のアプリケーションのスキャンには数秒かかります。スキャナー自身のフォルダーにいる場合、. は「このフォルダー」を意味し、--help ですべてのオプションが表示されます：

node bin/pqc-scan.mjs --help
node bin/pqc-scan.mjs . --fail-on high      # exit 1 if anything is High (for CI)

つまずきやすい点：

• Windows で 「node が認識されません」 と表示される場合：Node.js がインストールされていないか、インストーラーの実行前にターミナルを開いています。Node.js をインストールしてから、新しいターミナルを開いてください。
• スペースを含むパスには引用符が必要です："C:\My Projects\app"。
• 何も見つかりませんか？ スキャナーが読み取るのは JavaScript と TypeScript（.js、.mjs、.cjs、.ts、.mts、.cts、.jsx、.tsx）、ロックファイル、TLS 設定ファイルのみです。他の言語で書かれたコードは検出されません（「検出できないもの」を参照）。
• ファイルが変更されることはありません。 ファイルを読み取り、指定したレポートファイルのみを書き込みます。

オプションの全一覧：

オプション	意味
dir	スキャンするフォルダー（デフォルト：現在のフォルダー）。
--write	現在のフォルダーに pqc-scan.md と pqc-scan.json を書き込みます。ターミナルから実行した場合のデフォルトの動作です。
--md <file>	人が読むためのレポートを、代わりにこのファイルに書き込みます。
--json <file>	機械可読レポート（スキーマバージョン1）をこのファイルに書き込みます。
--cbom <file>	CycloneDX 1.6 暗号部品表（CBOM）をこのファイルに書き込みます。
--test-files <text>	パスにこの文字列を含むファイルをテストコードとして扱います。繰り返し指定できます。
--fail-on high	High が1件でもある場合、終了コード1で終了します。
--fail-on medium	High または Medium が1件でもある場合、終了コード1で終了します。
--exclude <name>	ディレクトリーまたはファイル名、あるいは dir からのパスをスキップします。繰り返し指定できます。node_modules と .git は常に読み取り対象外です。

スクリプト内またはパイプで実行し、--json、--md、--cbom のいずれも指定しない場合、Markdown は標準出力に出力され、ディスクには何も書き込まれません。ターミナルで実行した場合は、代わりに pqc-scan.md と pqc-scan.json が書き込まれます（部品表は指定した場合のみ）。終了コード：0 完了、1 --fail-on のしきい値に達した、2 使用方法または読み取りエラー。しきい値の判定対象は、テストコードを含むレポート内のすべての項目です。ディレクトリーを除外するには --exclude を使用します。

GitHub Actions での使用

permissions:
  contents: read
steps:
  - uses: actions/checkout@<commit>
  - uses: microtoll/pqc-scan@<commit>   # pin a full commit SHA
    with:
      fail-on: high                      # optional; empty never fails

アクションはワークスペースでスキャナーを実行し、Markdown レポートをジョブの概要に追加し、2つのレポートと部品表を pqc-scan アーティファクトとしてアップロードします。その後、fail-on が設定され、条件を満たした場合はジョブを失敗させます。入力：path、fail-on、exclude（1行につき名前を1つ）、json、md、cbom、job-summary、upload、artifact-name。出力：high、medium、low、verdict、json、cbom。 ランナーには Node 20 以降が必要です。GitHub のホストランナーにはインストール済みです。

検出対象

• Web Crypto：crypto.subtle の呼び出しを検出します。最も近いリテラルからアルゴリズムを読み取ります。耐量子およびハイブリッド方式の名前（ML-KEM-768、ML-DSA-65、X25519MLKEM768、MLKEM768-X25519）も対象です。
• node:crypto：ハッシュ、HMAC、暗号、鍵ペア、署名、Diffie– Hellman、公開鍵暗号化、PBKDF2、scrypt、HKDF、乱数を検出します。
• ライブラリ：package.json、package-lock.json、yarn.lock、pnpm-lock.yaml から、ほぼ60種類のカタログ登録済みパッケージ（tweetnacl、libsodium、@noble ファミリー、jose、jsonwebtoken、bcrypt、crypto-js、web-push、openpgp、…）を検出します。カタログで対応付けられている呼び出しや、RS256 などの JSON Web Token（JWT）アルゴリズム名も対象です。
• TLS：nginx、Apache、Caddy、Node の tls および https オプションを検出します。ハイブリッド耐量子鍵交換グループが有効かどうかも確認します。

読み取れない値（変数に格納されているアルゴリズム名）は、推測せず、動的 — 手動で確認として報告します。

優先度

優先度が付くのは公開鍵の用途だけです。大規模な量子コンピューターは RSA、楕円曲線、Diffie–Hellman 暗号を破りますが、共通鍵暗号やハッシュを弱めるだけです。

• 高：データを封印する鍵共有または公開鍵暗号化です。暗号文を今記録し、後で解読できます（「今収集し、後で復号」）。新しいデータにはハイブリッド方式での封印を検討してください。
• 中：署名です。こうしたコンピューターが存在するようになって初めて偽造が可能になるため、リスクが及ぶのは長期間有効な署名です。計画を立て、急がずに進めてください。
• 低：セッション用の鍵交換です。ハイブリッドグループを使わない TLS も含みます。影響するのはセッションであり、アーカイブではありません。

優先度は、呼び出しの近くにある語句（seal、encrypt、store…と、session、tls、handshake…）に基づくヒューリスティックです。判断材料となる語句がない用途は、担当者が確認するまで「高」となります。各項目には、優先度の判断に使われた語句が記載されています。「高」の項目はすべて担当者が確認してください。

レポート

• pqc-scan.json：schema/pqc-scan.schema.json（バージョン 1）で定義されるインベントリです。パスは相対パスで、区切りにはスラッシュを使います。スキャン対象のディレクトリは名前のみ表示されます。同じツリーを2回スキャンした場合、異なるのは scannedAt だけです。
• pqc-scan.md：概要、インベントリ、検討する代替案を添えた優先度、共通鍵暗号とハッシュに関する注記（AES-128、SHA-1、MD5、3DES、ECB モード、弱い PBKDF2 反復回数）、依存関係、TLS、NCSC の3つのマイルストーンに沿った次のステップ、およびスキャンで検出できない項目をまとめています。
• --cbom <file>：同じインベントリを、CycloneDX 1.6 形式の暗号資材部品表として出力します。これは、一元管理されたインベントリ、サプライヤー向け質問票、またはこれらのファイルを表示するビューアーが想定する形式です。

暗号資産部品表

CycloneDX 1.6 の部品表には、スキャンで見つかった各アルゴリズムのバリアントが cryptographic-asset コンポーネントとして記載されます（AES-256-GCM、ECDH P-256、ML-KEM-768 など）。名称から特定できる場合は、プリミティブ、鍵長または曲線、モード、使用される関数、古典的および NIST の耐量子セキュリティレベルといった CycloneDX 独自のフィールドも記載され、使用箇所ごとに、ファイル、行、インターフェイスと呼び出し、および優先度付きのソース行が示されます。Web Crypto API、node:crypto、カタログに登録された各パッケージは、そこから見つかった資産を 提供する library コンポーネントとして記載され、ロックファイルに記載がある場合はパッケージ URL（pkg:npm/…）とバージョンも含まれます。各 TLS 設定は、鍵交換グループを参照する protocol 資産です。そのため、サーバーのグループリストにある X25519 と Web Crypto の呼び出しにある X25519 は、同じ資産として扱われます。CycloneDX に対応するフィールドがない情報（スキャナーのクラスと種類、移行の優先度とその理由、反復回数などのリテラルパラメーター、注記）は、microtoll:pqc-scan:* という名前のプロパティに記録されます。部品表の内容は JSON レポートに含まれる情報だけです。レポートのみから生成され、シリアル番号は部品表自身の内容から算出されます（同じツリーを 2 回スキャンすると、タイムスタンプとシリアル番号を除き、同一の部品表が生成されます）。また、メタデータには インベントリと参照情報であり、コンプライアンス証明書ではありません という一文が記載されます。マッピングは DESIGN.md §8.14 に記載されており、出力はすべてテストで公開済みの CycloneDX スキーマに照らして検証されます。

コーディングエージェント向け

pqc-scan mcp は、標準入力と標準出力を介してスキャナーを Model Context Protocol（MCP）サーバーとして実行するため、Claude Code、Cursor、その他の MCP ホスト上のコーディングエージェントは、書き込んだばかりの暗号化を確認できます。すべてのプロジェクトで Claude Code に追加するには、次のコマンドを実行します。

claude mcp add pqc-scan --scope user -- npx -y @microtoll/pqc-scan mcp

--scope user を指定しない場合、Claude Code はコマンドを実行したフォルダーに対してのみサーバーを登録します。新しい会話では利用できますが、すでに開いている会話では利用できません。

その他のホストでは、同じコマンド（npx -y @microtoll/pqc-scan mcp）を stdio サーバーとして使用します。次のツールを提供します。

ツール	内容
pqc_scan({ directory, exclude?, testFiles?, detail? })	フォルダー（絶対パス、またはホストがサーバーを起動した場所からの相対パス）をスキャンし、レポートの概要をコンパクトな JSON として返します。detail: "full" を指定すると、--json が出力するものと同じ JSON レポートそのものが、インデントなしで返されます。exclude と testFiles は、同名のオプションと同じくリストです。

概要にはレポートの件数が含まれます。レビューが必要な各使用箇所（優先度が設定されているもの、アルゴリズムを読み取れなかったもの、注記があるもの）は、アルゴリズムと対応方法ごとにまとめられ、ファイルと行番号とともに緊急度の高い順に並びます。また、その他すべての使用箇所はアルゴリズムごとに集計されます。これはエージェントが対応に使う情報で、一般的なアプリケーションではレポート全体の 20 分の 1 のサイズです。レポート全体はホストのツール結果の上限（Claude Code の場合は約 25,000 トークン）を超えることがあります。大規模なコードベースのレポート全体が必要な場合は、変更したフォルダーをスキャンするか、exclude を使用してください。

このツールはファイルを読み取るだけです。レポートファイルは書き込まず、スキャン対象のコードを実行せず、スキャナーが情報を外部に送信することもありません。結果は呼び出し元のホストに返され、そこからエージェントのコンテキストに渡されます。通常、その情報はエージェントのモデルプロバイダーにも届きます。レポート全体には証拠として検出されたソース行が含まれていますが、エージェントはこれらの行をすでに読み取れます。概要に含まれるのはファイルと行番号のみです。mcp という名前のフォルダーをスキャンするには、pqc-scan ./mcp を実行してください。詳しくは DESIGN.md §8.15 を参照してください。

このツールは仕様の動作ヒント（annotations）を通じて、ホストにも同じ情報を伝えます。読み取り専用、何も破壊しない、再度呼び出しても安全、ネットワークを使用しない、という内容です。また、「コードベースで使用されている暗号を一覧表示」というわかりやすいタイトルも設定されています。ホストはこれらの情報を使い、呼び出しの前にユーザーへの確認が必要かどうかを判断できます（DESIGN.md §8.17）。

検出できないもの

• JavaScript、TypeScript、ロックファイル、TLS 設定ファイル以外のすべて：ほかの言語、バイナリ、オペレーティングシステム、クラウド鍵サービス、ネットワーク呼び出しの先にあるもの。
• 実際に実行されるファイル。サービスが読み込まないファイルからのみインポートされるライブラリも報告されます。
• フレームワーク独自の暗号処理。ただし、そのフレームワークがカタログに含まれている場合を除きます。
• 検査対象の場所に記述されていない値。同じブロック内の const、または相対インポート先への1段階の参照（ワークスペースパッケージ名によるインポートは対象外）まではたどりますが、それ以外はたどりません。同じ名前のモジュールレベル定数を関数パラメーターがシャドーイングしている場合、誤解を招く可能性があることが分かっているのはこのケースだけです。
• 証拠は記述されたとおりにコピーされます。 暗号処理の呼び出しと同じ行にある秘密情報は、レポートに表示されます。レポートは、そこに記述されているコードと同じように扱ってください。

開発

npm test

node:testを使用しており、フレームワークも依存関係もありません。見つかった誤検出はすべて、test/fixtures/のフィクスチャとテストの1行として追加されます。設計と確定した詳細はすべてDESIGN.mdに記載されています。セキュリティレポートについてはSECURITY.mdをご覧ください。

開発の経緯とサポート

このスキャナーは、創業者が作成して決定した設計に基づき、Claude Code（Anthropicのコーディングエージェント）を用いて開発されました。創業者はすべての変更を確認し、承認しています。チェックの内容はここで確認できます。設計、実際のコードのパターンをまとめたフィクスチャ、テスト、そしてDESIGN.md §8に記録された実際のリポジトリの手動レビューです。レビューで見つかった誤検出はすべてテストに追加されました。

コマンドラインツールは無料で、今後も無料です。時間の節約に役立った場合は、GitHubで開発を支援できます。

ライセンス

Apache-2.0です。LICENSEをご覧ください。