giip
SES案件登録
9分で読了

CQE Repository Script Management Guide

Learn how to manage, execute, and monitor script registration in the CQE (Custom Query Engine) Repository.

🤖 CQE リポジトリ一覧ページへ →

📋 Overview

The CQE Repo List provides a centralized repository for your maintenance and diagnostic scripts. You can store scripts once and deploy them across any number of logical servers (LSVR) with custom execution parameters.

🔍 Script Details & Execution

When you click on a script in the list, the detail modal opens with the following capabilities:

1. Script Content

View the full source code of the script. This is read-only in the list view; use the edit feature if modifications are needed.

2. Execution Settings (NEW)

Before registering a script to a server, you can configure how it should run:

  • Active: Toggle whether the script is enabled for the selected servers.
  • Repeat: If enabled, the script will run periodically.
  • Interval (min): Set the frequency for repeated execution (in minutes).
  • Start Date: Specify when the first execution should occur.

3. Server Registration (LSVR Queue Put)

You can select one or more servers from your current project to receive this script.

  • LSVR Selector: Use the checkboxes to choose target servers.
  • Add to Queue: Click this button to register the script with the defined settings for all selected servers.

📊 Script Usage Status

At the bottom of the modal, the Usage Status Table displays all servers currently registered for this specific script.

  • Hostname: The name of the server using the script.
  • Usage: The logical server's defined purpose.
  • Settings: View the active/repeat/interval status for each registration.
  • Last Run: Tracks the last time the script was successfully executed on that machine.

API リファレンス

この機能の API 詳細仕様は専用ガイドを参照してください。

📘 システム管理 API リファレンス

トラブルシューティング

症状原因解決
キュー登録後もスクリプトが実行されない実行設定で 有効 (Active) がオフになっている詳細モーダルで Active をオンにして再度キューに登録します。
LSVR セレクターに対象サーバーが表示されない選択中のプロジェクトにサーバーがない、またはサーバーが別プロジェクトに属している上部で正しいプロジェクトを選択しているか確認します。
繰り返し実行が動作しない繰り返し (Repeat) はオンだが 実行間隔 (分) が空になっている実行間隔を 1 以上に設定して再登録します。
登録状況の 最終実行 が更新されない対象サーバーのエージェントがまだキューを受信していないエージェントの接続状態と、開始日時が過去の時刻かを確認します。

🔌 CQE API (自動化向け)

上記のUI操作は次のCQE APIバーブ(byAK/bySkディスパッチャ)に対応します。リクエストは text(バーブ+パラメータ名)、jsondata(値)、token を送信します。

  • CQERepoPut msName msDetail msBody msPer msPrice msType — スクリプトをリポジトリに登録。

    • text にはパラメータ名のみを入れます: CQERepoPut msName msDetail msBody msPer msPrice msType
    • jsondata には実際の値を入れます: {"msName":"...","msDetail":"...","msBody":"#!/bin/sh\n...","msPer":0,"msPrice":0,"msType":"sh"}
    • msType は5文字(varchar(5))までに制限されています。powershell、expect、cmdwin のような長い名前は保存できません — 下の表の短いコードを使用してください。
    msType対象OSエージェントでの実際の実行方法
    ps1Windowspowershell.exe(ヘッドレス)
    cmdWindowscmd.exe
    batWindowscmd に正規化してから cmd.exe
    wsfWindowswscript.exe //B //Nologo
    ps1ui / cmduiWindowsデスクトップセッションで可視ウィンドウ付きで実行
    shLinuxsh <tempfile>
    pyLinuxpython3 <tempfile>
    ps1Linuxpwsh <tempfile>

    OSを混在させないでください。 Windows エージェントは上記の Windows 用タイプのみを実行し、それ以外の値は unsupported_script_type としてログに記録され、実行されません。Linux エージェントは逆で、未知のタイプはすべて sh で実行するため、bat/wsf のスクリプトを Linux サーバーに割り当てると気づかないまま sh で実行されて壊れます。割り当て先サーバーのOSに合ったタイプでスクリプトを登録してください。

    • Linux シェルスクリプトの登録: msType に sh を入れ、msBody にシェルスクリプト全文を入れます。Linux エージェントは本文を一時ファイルに書き出して**sh で実行**するため、#!/bin/bash のシバンは無視されます。bash 専用の構文([[ ]]、配列など)は避けて POSIX シェルで書くか、1行目で exec bash "$0" "$@" により bash に引き渡してください。

      #!/bin/sh
# Runs under sh, so use POSIX syntax only. sk/lssn/apiaddrv2 arrive as environment variables.
curl -s -H "Authorization: Bearer $sk" "$apiaddrv2/health" | jq -r .status

    • スクリプト本文の置き場所: どちらの方法でも動作します。

      • 本文全体を msBody に入れる — ホスト側に事前インストールが一切不要で、giip 側の変更がすべてのサーバーに反映されます。推奨。
      • スクリプトをホスト側に置いて呼び出すだけにする — jq/curl などの前提条件が既に必要なホストや、本文が非常に長い場合向け。その場合はホストごとの配布状態を自分で管理する必要があります。
      • msBody は ntext なので、実用上の長さ制限はありません(観測された最大: 20,883文字)。

  • CQEQueuePut mssn lssngroup csn interval active script_type custom_values repeat startdate auid — サーバーにスクリプトを割り当て。

    • lssngroup: カンマ区切りのLSSN一覧(サーバーごとに1件)。
    • interval: 分。repeat: 0/1 = 一回のみ, 2 = 繰り返し(intervalごとに再実行)。
    • custom_values: サーバー別の注入値 → スクリプト本文の {{CustomVariables}} を置換。

  • CQEQueueGet lssn hostname os op — エージェントがポーリングして次のスクリプト本文を受信。

スクリプト本文のプレースホルダ: {{CustomVariables}}(割り当てごとのcustom_values、サーバー側で注入)、{{sk}}(エージェントトークン)、{{lssn}}(エージェントLSSN)。

Linux エージェントは sk、lssn、apiaddrv2 を環境変数としてエクスポートもします。{{sk}}/{{lssn}} のプレースホルダの代わりに $sk、$lssn、$apiaddrv2 を直接参照できます。

実行制限

Windows エージェントLinux エージェント
時間制限既定で 600秒。giipAgent.cfg の cqetimeoutsec で変更します。超過するとスクリプトは強制終了されますなし
実行方法一時ファイル、ヘッドレスプロセス一時ファイル、sh で実行
本文の長さ無制限(ntext)同じ

実行間隔: interval は分単位です。実際の周期はエージェントのポーリングサイクルに左右されます — interval=0 は「スケジュールなし」ではなく、ポーリングのローテーションごとに再ディスパッチするという意味です。有効なキューは複数あればローテーションで処理されるため、N 件のキューがあると体感の間隔はおよそ N 倍に伸びます(giipdb docs/30_Specs/SPEC_AND_CHECKLIST.md で計測)。間隔を 1 分に設定しても、ポーリングサイクルより頻繁に実行されることはありません。

結果の保存先: スクリプトの標準出力/標準エラー出力は、エージェントが動作しているサーバー上のローカルログファイルに出力されます。giip に送られるのはサマリーのみで、KVSPut(kType=lssn、kKey=<lssn>、kFactor=giipagent)が script_type、exit_code、execution_time_seconds、mslsn、mssn を保持する event_type="script_execution" レコードを作成します。出力そのものは giip には保存されません。 giip で出力を確認したい場合は、スクリプト内から KVSPut で出力を送るようにしてください(保持期間はその KVS の設定に従います)。

失敗通知: 組み込みの通知はありません。exit_code が 0 以外の script_execution レコードを検索して失敗を検知するか、スクリプト内からアラートを送信してください。

完全な仕様: giipdb docs/30_Specs/CQE_SPECIFICATION.md。

Version: 1.3 Last Updated: 2026-10-19 Source File: giipv3/public/help/cqerepolist.en.md

関連ガイド

リアルタイムセキュリティエージェント自律型AIによるプロアクティブな脅威監視と監査エージェントループとディスパッチGitHubのイシューに基づいてエージェントループを通じて作業を実行する簡単な方法タスク状態遷移ガイドエージェントディスパッチシステムのタスク状態遷移ルール
← PreviousAIエージェント3種のCSN一括登録（新規マシン）Next →CQE 論理サーバー実行ジョブ照会