セキュリティスキャン

Qoder Agent SDK には組み込みのコードセキュリティ機能があり、Agent はコードを生成・変更しながら自身の出力を検査し、必要に応じてリポジトリ全体を監査できます。自動化されたワークフローでもセキュリティの最低線を確保できます。 3つのスイッチは既定ですべて無効です。セキュリティスキャンはターンとクレジットを追加で消費するため、自動的には有効化されません。アプリケーションがセッション単位で明示的に有効にします。両言語がこのオプションに対応しています。TypeScript は securityScan（キーはキャメルケース）、Python は security_scan（キーはスネークケース）です。

3つのレベル

3つのレベルは互いに独立しています。必要なものだけを有効にしてください。

スイッチ（TypeScript / Python）	対象範囲	実行タイミング
`l1StaticCheck` / `l1_static_check`	Agent が直前に変更したファイル	対応するファイル編集後に自動実行
`l2LightweightScan` / `l2_lightweight_scan`	リポジトリ全体、浅いスキャン	Agent がスキャンが必要と判断したとき
`l3DeepScan` / `l3_deep_scan`	リポジトリ全体、詳細スキャン	Agent が詳細な監査が必要と判断したとき

l1StaticCheck は Agent 自身の変更に対する最終確認で、オーバーヘッドが最小です。l2LightweightScan と l3DeepScan は Agent にリポジトリをスキャンする権限を付与するもので、毎ターン強制的に実行するものではありません。

スキャンを有効にする

import { query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'パスワードリセットのエンドポイントを実装してください',
  options: {
    securityScan: {
      l1StaticCheck: true,
      l2LightweightScan: true,
    },
  },
})) {
  console.log(message);
}

段階的な使い分けの例：

機能開発：l1StaticCheck のみを有効にし、1ターンの所要時間を大きく延ばさずに Agent 自身の変更をカバーします。
マージ前レビュー：l2LightweightScan を追加します。
定期監査：l3DeepScan を追加し、時間の余裕があるジョブで実行します。

このオプションは設定を上書きし、マージしない

securityScan を渡すと、そのセッションではこのオプションが優先されます。設定ファイルや settings オブジェクト内の securityScan ブロックは全体が無効になり、明示的に指定されていないスイッチはすべて false として扱われます。

// settings.json に次の内容がある場合：{ "securityScan": { "l1StaticCheck": true } }

options: {
  settings: './settings.json',
  securityScan: { l3DeepScan: true },
}

// 実際に適用される結果 —— l1StaticCheck は無効になる：
// { l1StaticCheck: false, l2LightweightScan: false, l3DeepScan: true }

Python で security_scan を使う場合も同じ規則が適用されます。設定内の他のキーは影響を受けず、securityScan のブロックのみが置き換えられます。あるスイッチを有効に保つには、オプション側で再度指定してください。 securityScan をまったく渡さない場合は、設定ファイルの内容が使われます。

検証はプロセス起動前に行われる

不正な値は即座に例外となり、しかも Qoder CLI の起動前に発生します。スイッチのつづり間違いはその場で判明し、黙って無視されることはありません。

options: { securityScan: { l2LightweightScann: true } }
// TypeError: securityScan contains unknown option: l2LightweightScann

options: { securityScan: { l1StaticCheck: 'yes' } }
// TypeError: securityScan.l1StaticCheck must be a boolean

適用されたことを確認する

いずれかのスイッチを有効にすると、セッションに組み込みの security-scan 機能が公開されます。初期化結果から読み戻せます。

const q = query({ prompt: userMessages(), options: { securityScan: { l2LightweightScan: true } } });

const init = await q.initializationResult();
const enabled = init.skills?.some(
  (skill) => skill.name === 'security-scan' && skill.source === 'built-in',
);
console.log(enabled); // true

securityScan を渡さない場合、この項目は現れません。

スキャンは権限制御ではない

この2つの仕組みは異なる問題を扱い、互いに代替できません。

仕組み	扱う問題
`securityScan`	Agent がコード内の脆弱性を検査できるか
権限制御	Agent がそのツールの実行やそのパスへのアクセスを許可されているか

セキュリティスキャンはコード内の問題を検出するものであり、Agent の動作範囲を制限しません。l3DeepScan だけを有効にして権限ポリシーを設定していない Agent は、任意のコマンドを実行できます。両方を設定してください。

次のステップ

権限制御 —— Agent がアクセスできるツールとパスを制限する
Hooks —— ツール呼び出しの実行前に介入または書き換える
Skills —— セッションがモデルに公開する機能を制御する

​3つのレベル

​スキャンを有効にする

​このオプションは設定を上書きし、マージしない

​検証はプロセス起動前に行われる

​適用されたことを確認する

​スキャンは権限制御ではない