Claude CodeでCheckmarx MCPとcx-devassistを使い生成コードを検査する

Checkmarx OneをClaude Codeにつなぐ方法は2つあります。ホスト型のCheckmarx Security MCPサーバーをMCPクライアントとして登録する方法と、書き込み前に必ずスキャンするcx-devassistプラグインを入れる方法です。前者は「頼んだときだけ」スキャンし、後者は「頼まなくても」スキャンして、問題があれば書き込みを止めます。

この記事では、2つの違い、プラグインの入れ方、スキャン対象になるファイルの範囲、MCPサーバーを単体で使う設定、止まったときの対処を順に扱います。同じ領域の別製品は、Snyk StudioやSonarQubeプラグインの記事にあります。

2つの接続方法はどう違うか

Checkmarxのリポジトリ(cx-agentic-ai)は、Checkmarx One向けの2つの部品を同梱しています。READMEの整理は次のとおりです。

Developer AssistプラグインはClaude Code向けがcx-devassist、ほかにCursor、GitHub Copilot CLI、Codex CLI、Gemini CLI向けがあります。両者は併用も単独利用もできます。プラグインはCheckmarx OneのCLI(cx)を包んでいて、修正のためのMCPサーバーも一緒に起動します。

cx-devassistは何を止めるのか

プラグインの核は、Claude CodeのPreToolUse hookで動く2段構えのチェックです。hookの仕組みそのものはClaude Codeのhooksガイドにまとめています。

1. 1段目のゲートが、スキャナーを信頼してよいかを確かめます。cxが入っているか、バージョンが十分新しいか、必要なサブコマンドを持つか、認証済みか、の順です。どれか1つでも証明できなければ拒否(exit 2)し、2段目は動きません。
2. 2段目がネイティブのスキャナー(cx hooks claude-*)で、実際の解析と許可・ブロックの判断をします。

対象のツール呼び出しとスキャン内容は次のとおりです。

「スキャナーが信頼できないときも止める」のが名前の由来のfail-closedです。cxが入っていない、未認証、といった状態では書き込みが通らず、/cx-cli-setupへの案内が表示されます。

スキャン対象のファイル

ゲートが書き込みを止めるのは、3つのエンジンのどれかが解析できるファイルだけです。一覧はconfig/cx-scannable-filesにあります。

.md、.html、.css、.sql、.sh、.rb、.php、.c、.rsはスキャン対象外で、書き込みはそのまま通ります。Ruby、PHP、Rustのコードが中心のプロジェクトでは、書き込みの大半がゲートの対象外になります。

見落としやすいのは次の2点です。

• .jsonと.yamlはKICSの対象なので、IaCでないtsconfig.jsonを書くときも準備状態のチェックが走ります
• 素の.tfvarsは対象外です。KICSが扱うのは.auto.tfvarsと.terraform.tfvarsだけだからです

すべてのファイル書き込みを対象にしたいときは、環境変数CX_GATE_ALL_FILES=1を設定します。

プラグインを入れる

前提条件

プラグインはcx CLIを自分でインストールしますが、ホスト側の前提までは用意できません。

Python 3が無いときはゲートがfail-closedで書き込みを止めます。逆にWindowsでshが無いと、hookそのものが起動できません。Claude Codeは起動できないhookを非ブロックのエラーとして扱うため、書き込みはスキャンなしで通ります。READMEもこの点を明記していて、Git for Windowsの導入を先に確かめるよう求めています。

インストール手順

/plugin marketplace add Checkmarx/cx-agentic-ai
/plugin install cx-devassist@cx-devassist-marketplace

入ったかどうかはシェルから確認できます。READMEの例ではcx-devassist@cx-devassist-marketplaceがenabledと表示されます。

claude plugin list

hookスクリプトを更新したあとは/reload-pluginsで現在のセッションに反映します。マーケットプレイスやプラグインの仕組みはプラグインとマーケットプレイスの解説にあります。

cx CLIの導入と認証

/cx-cli-setupは、cxのダウンロードをチェックサム検証つきで入れ、PATHに通し、認証(APIキーまたはOAuth)まで案内するスキルです。最低バージョンはscripts/cx-min-versionに2.3.67と書かれています。ただしこの数字は下限にすぎません。実際に使えるかは、cx mcp bridgeとcx hooks claude-*の各サブコマンドが--helpに応答するかという実行時の確認で決まり、通らなければ「incapable」と報告されます。

cxがPATHに無い環境では、CX_BINARYに絶対パスを指定できます。指定したcxも、新しさ・機能・認証の検査を受けます。

見つかった問題を直す

修正は、プラグインが同梱するCheckmarx MCPサーバー(cx mcp bridge)が担当します。.mcp.jsonに宣言されているので、claude mcp addなどの登録は要りません。1回のcxサインインがCLIとMCPの両方に効きます。

必要に応じて明示的にスキャンさせるための3つのスキルも入ります。

対象を指定しない「このファイルをスキャンして」は、ソースコードならASCA、マニフェストならSCA、IaCならKICSに自動で振り分けられます。プロジェクト全体やクラウド規模のスキャンは、スキルでなくCheckmarx MCP(Cx1クラウド側)のツールの担当です。

プラグインの挙動を調整する

設定はすべて任意で、既定値のまま動きます。

ログはゲートの許可・拒否ごとに1行のJSONLで残ります。ソースコード、秘密情報、プロンプト、自由文は許可リスト方式で書き込み前に落とされ、scan_decisionは検出内容の文面でなく結果だけを持ちます。MCPブリッジが資格情報を送るのはAuthorizationヘッダーだけで、チャットにもログにも出ません。

管理者がチームに配るときは、config/cx-onboarding.propertiesでCheckmarx OneのURLとテナントを事前に埋められます。READMEは、エンドユーザーの手元のインストール先でなく、フォークした社内マーケットプレイス側のコピーを編集するよう書いています。プラグイン更新で上書きされるからです。

アンインストールはclaude plugin uninstall cx-devassist@cx-devassist-marketplaceです。cxのバイナリは~/.checkmarxなどに残るので、必要なら別に消します。

MCPサーバーだけを使う

ゲートが不要で、必要なときにスキャンできれば足りるなら、ホスト型のMCPサーバーを単体で登録します。URLの形はhttps://{cxone_base_url}/api/security-mcp/mcp/{tenant}です。ホスト名(ast.checkmarx.netなど)とテナント名(cx_euなど)は、Checkmarxの管理者から受け取る値です。

OAuth2で接続する

推奨は動的クライアント登録(DCR)を使うOAuth2です。設定にはURLだけを書きます。

{
  "mcpServers": {
    "Checkmarx": {
      "type": "http",
      "url": "https://{cxone_base_url}/api/security-mcp/mcp/{tenant}"
    }
  }
}

初回の接続でCheckmarx Oneのログインページにリダイレクトされ、ログインするとツールが使えます。トークンの更新はクライアント側が自動で行います。

APIキーで接続する

CIやスクリプトで動かすなら、AuthorizationヘッダーにAPIキーを渡す形にします。キーはCheckmarx OneのAccess ManagementのAPI Keysで発行します。リポジトリのexamples/claude-mcp.jsonは次の形です。

{
  "mcpServers": {
    "Checkmarx": {
      "type": "http",
      "url": "https://{cxone_base_url}/api/security-mcp/mcp/{tenant}",
      "headers": {
        "cx-origin": "Claude",
        "Authorization": "{api_key}"
      }
    }
  }
}

APIキーを設定ファイルに平文で書いてリポジトリにコミットしない、という注意がドキュメントにあります。MCPサーバーの登録の基本はClaude CodeのMCPサーバー設定ガイドが扱っています。

使えるツール

READMEは、スキャン(planScan triggerScan getScanDetails getLatestScans listScans listFindings getFindingDetails)、プロジェクト管理、アプリケーション管理、分析、修正(codeRemediation packageRemediation imageRemediation)に分けて並べています。スキャンエンジンはSAST、SCA、KICS、シークレット検出です。

ここで1つ注意があります。分析カテゴリのツールは、READMEではgetTenantVulnerabilitiesSummaryの1つだけですが、docs/usage.mdにはlistProjectsOverview、getRiskSummary、listRiskResults、updateRiskResultStatusなど7つが載っています。2つの文書で一覧が食い違っているので、接続後にクライアント側のツール一覧を見て、実際に公開されているものを確かめてから頼み方を決めるのが確実です。

頼み方の例はdocs/usage.mdに載っています。たとえば次の流れです。

1. 「このプロジェクトにはどのスキャンエンジンを使うべきか」でplanScan
2. 「mainブランチでmy-apiをスキャン」でtriggerScan
3. 「HIGHとCRITICALの検出を一覧にして」でlistFindings
4. 「finding #12のSQLインジェクションを直して」でcodeRemediation

getScanDetailsは5秒間隔でポーリングし、既定の最大待機は2分です。大きなスキャンはそれより長くかかるため、getScanDetailsかgetLatestScansを手動で呼び直します。

止まったとき・つながらないときの対処

docs/troubleshooting.mdの項目を、症状から引ける形にしました。

ゲートがcxの不備で書き込みを止めている間も、git、npm、mvn、pytest、dockerなどのシェルコマンドは動きます。cxの導入と認証もシェルから行えるので、詰まっても自力で復旧できます。

使いどころの目安

プラグインとMCPの違いは、「誰が呼ぶか」に集約されます。MCPはClaude(と人間の依頼)が呼び、プラグインはhookが呼びます。チーム全体で「生成コードのうちスキャン可能な種類は必ず検査を通す」ことを揃えたいなら、後者が合います。フォークした社内マーケットプレイスでcx-onboarding.propertiesを配れば、URLとテナントの入力も省けます。一方で、検査の対象がスキャン可能な種類の書き込みに限られ、シェル経由は素通りする点は変わりません。レビューやCI側のスキャンと併走させる前提で入れるのが現実的です。

個人で必要なときだけ脆弱性を調べるなら、MCPサーバー単体の登録で十分です。プラグインのゲートを入れると、.jsonや.yamlを書くたびに準備状態の確認が走ります。その手間と引き換えに、スキャン可能な種類の書き込みを検査なしで通さない構成になります。ほかの静的解析をClaude Codeに組み込む場合は、Semgrep MCPの記事も参照してください。