メインコンテンツまでスキップ

トレースの取得

Takumi Runner は、ワークフロー実行中に発生するプロセス・ネットワーク・ファイル操作を eBPF で網羅的にキャプチャします。このページでは、取得されるイベントの種類、データ形式、および生データへのアクセス方法を説明します。

取得の仕組み​

Takumi Runner のトレース取得は、Linux カーネルの eBPF（extended Berkeley Packet Filter）テクノロジーを基盤としています。eBPF を利用することで、ワークフロー内で実行されるユーザーコードに一切の変更を加えることなく、カーネルレイヤで VM 内での動作をキャプチャできます。

キャプチャされるイベント​

Takumi Runner の eBPF トレーサーは、以下のシステムコールレベルのイベントを記録します。

イベント種別説明記録されるフィールド
process_execプロセスの実行PID、コマンド名、ファイルパス、引数
net_connectネットワーク接続PID、接続先アドレス、ポート、プロトコル
dns_queryDNS ルックアップPID、ホスト名
file_openファイルのオープンPID、パス、フラグ
file_writeファイルへの書き込みPID、パス、書き込みバイト数

1 回のジョブ実行で、数千から数万件のイベントが記録されます。

トレースの用途​

収集されたトレースは、以下のようなセキュリティ分析に活用できます。

  • サプライチェーン攻撃の検知 として、npm install や pip install 中に不審な外部ホストへの通信が発生していないかを確認する
  • インシデント調査 として、特定のジョブ実行中に curl や wget が実行されたか、~/.netrc などの認証情報を含むファイルにアクセスがあったかを追跡する
  • ベースライン分析 として、正常なビルドのトレースと異常なビルドのトレースを比較し、差分を特定する

トレースのデータ形式​

トレースデータは JSONL（改行区切り JSON） 形式で保存されます。1 行が 1 イベントに対応し、各行は独立した JSON オブジェクトです。すべてのイベントには共通フィールドとして type（イベント種別）と timestamp（発生時刻、ISO 8601 形式）が含まれます。

警告

以下に示すフィールド定義は、現時点での実装に基づく参考情報です。フィールドの追加・変更・削除が事前の通知なく行われる場合があります。

process_exec​

プロセスの実行を記録します。

フィールド型説明
pidnumberプロセス ID
commstringコマンド名
filenamestring実行ファイルのパス
argsstring[]コマンドライン引数
{
  "type": "process_exec",
  "timestamp": "2025-01-15T10:30:01Z",
  "pid": 1234,
  "comm": "npm",
  "filename": "/usr/bin/npm",
  "args": ["npm", "install"]
}

net_connect​

ネットワーク接続を記録します。

フィールド型説明
pidnumberプロセス ID
dst_addrstring接続先 IP アドレス
dst_portnumber接続先ポート番号
protocolstringプロトコル（tcp / udp）
{
  "type": "net_connect",
  "timestamp": "2025-01-15T10:30:02Z",
  "pid": 1235,
  "dst_addr": "104.16.23.35",
  "dst_port": 443,
  "protocol": "tcp"
}

dns_query​

DNS ルックアップを記録します。

フィールド型説明
pidnumberプロセス ID
hostnamestring問い合わせたホスト名
{
  "type": "dns_query",
  "timestamp": "2025-01-15T10:30:02Z",
  "pid": 1235,
  "hostname": "registry.npmjs.org"
}

file_open​

ファイルのオープンを記録します。

フィールド型説明
pidnumberプロセス ID
pathstringファイルパス
flagsstringオープンフラグ（O_RDONLY など）
{
  "type": "file_open",
  "timestamp": "2025-01-15T10:30:03Z",
  "pid": 1235,
  "path": "/home/runner/work/app/package.json",
  "flags": "O_RDONLY"
}

file_write​

ファイルへの書き込みを記録します。

フィールド型説明
pidnumberプロセス ID
pathstringファイルパス
bytesnumber書き込みバイト数
{
  "type": "file_write",
  "timestamp": "2025-01-15T10:30:04Z",
  "pid": 1235,
  "path": "/home/runner/work/app/node_modules/.package-lock.json",
  "bytes": 2048
}

トレースの保管期間​

トレースデータは、取得日から最低 90 日間 保管されます。90 日を経過したトレースデータは削除される場合があります。

サブスクリプションの解約時には、利用規約その他の定めに従ってトレースデータが削除されます。

info

保持期間の延長を希望される場合は、アカウント担当までお問い合わせください。ご契約やご利用の状況により、ご要望にお応えできない場合があります。

生データへのアクセス​

Shisho Cloud コンソールのジョブ詳細画面にある クエリ タブでは、トレースデータに対して SQL（DuckDB）を使った自由なクエリを実行できます。

クエリタブ

また、各ジョブ実行のトレースデータを JSONL ファイルとしてダウンロードすることもできます。ダウンロードした生データは、独自のスクリプトやツールで自由に分析できます。

info

生データは gzip 圧縮された JSONL 形式です。gunzip で展開してから jq 等で処理できます。

gunzip trace.jsonl.gz
cat trace.jsonl | jq 'select(.type == "net_connect")'
に最終更新