tracee-actionとは？GitHub ActionsにTraceeを組み込む手順と開発停止後の代替

tracee-actionは、Aqua Securityが公開しているランタイムセキュリティツールTraceeを、GitHub Actionsのジョブの中で動かすためのアクションです。ジョブ実行中のプロセス起動・DNS問い合わせ・ファイル書き込みを記録し、既知の攻撃パターン（シグネチャ）と「普段と違う動き」（プロファイル差分）を検出して、プルリクエストへのコメントや新しいPRで知らせます。

ただし、2025年2月にリポジトリのREADME冒頭へ「デモ目的のみ。活発な開発はしていない。自己責任で使用」という注記が加わり、コードの変更は2023年9月のv0.4.0で止まっています。この記事では、start／stopの2つのアクションで何が起きるかをaction.yamlとシェルスクリプトから読み解き、組み込み手順、2つの検知方式、ソースから分かるv0.4.0の挙動の癖、2026年時点で同じ目的を達成する代替の選び方を扱います。

まとめ：tracee-actionの現状と使う前に知るべき点

• 仕組み：ジョブの先頭に-start、末尾に-stopのタグを置く。先頭でTraceeを特権コンテナとして起動し、末尾でイベントを集計してシグネチャ検知とプロファイル差分を報告する。
• 開発状況：最新タグはv0.4.0（2023年9月13日）、同梱のTraceeイメージは0.17.1（2023年8月）。READMEはデモ目的と明記しており、本番のCIを守る用途には勧めない。
• 動く条件：Linuxランナー、Docker、特権コンテナの3つが要る。PRコメントとプロファイル更新PRにはcontents: writeとpull-requests: write、リポジトリ設定でのPR作成許可も必要。
• v0.4.0の癖：差分があるとcreate-pr: falseでもPRが作られる。更新PRが無い状態で差分が1種類だけだと、fail-on-diff: trueでもジョブは失敗しない。
• 代替：公開リポジトリ×GitHubホストランナーなら、StepSecurityのHarden-Runner（Community版は無料）。プライベートリポジトリやセルフホストでOSSに限るなら、Tracee本体（v0.24.1）を自分のステップで起動し、保守を引き受ける。

tracee-actionとTraceeの関係と開発状況

Tracee本体：eBPFで動くランタイムセキュリティツール

Traceeは、Linuxカーネル内で小さなプログラムを動かす仕組みであるeBPFを使い、システムの動きをイベントとして取り出して、不審な振る舞いのパターンを検知するツールです。ライセンスはApache-2.0で、本体の開発は続いています。2026年9月29日時点の最新リリースはv0.24.1（2025年11月19日公開）です。

前提条件のドキュメントでは、Linuxカーネル5.4以降が必要（RHEL 8系はバックポートにより4.18で対応）とされ、Linux以外のOSには対応していません。eBPFそのものの仕組みと用途はeBPFとは？Linuxカーネルを拡張する仕組みと可観測性・ネットワークでできることで解説しています。

tracee-action：更新が止まったデモ用アクション

tracee-actionのREADMEは、目的を「GitHub Actionsのワークフローをサプライチェーン攻撃から守ること」と説明しています。リポジトリはアーカイブされていませんが、タグの履歴を見ると更新は2023年で止まっています。

v0.4.0では、シグネチャdynamic_code_loadingがコミットメッセージ上「一時的に無効化」され、そのまま再有効化されていません。同梱のTraceeは0.17.1に固定されており、後述のとおり0.24.1ではCLIのフラグが変わっているため、イメージのタグを差し替えるだけでは新しい版に移れません。

start／stopの2アクションで起きる処理

tracee-actionはstartとstopの2本のブランチを持ち、-startで終わるタグは前者、-stopで終わるタグは後者を指します。どちらもシェルのステップを束ねたcomposite actionで、Node.jsのコードは含みません。

startアクション：Traceeコンテナの特権起動

1. pgrep Runner.ListenerでランナーのプロセスIDを取り、そのプロセスツリーを対象に、プロセス起動（sched_process_exec）とDNS（net_packet_dns）を記録するポリシーを作る。
2. ワークスペース配下へのファイル書き込み（file_write）を記録するポリシーと、シグネチャ29種を有効にするポリシーを作る。
3. aquasec/tracee:0.17.1を--privileged --pid=host --cgroupns=host付きでバックグラウンド起動し、イベントをJSONL形式で/tmp/tracee/out/へ書き出す。
4. ポート3366の/healthzが200を返すまで1秒ごとに待つ。

action.yamlはランナーのホスト上でdockerとpgrepを直接実行する前提で書かれています。Dockerが入っていないランナーや、ジョブ全体をcontainer:の中で動かす構成は、この前提を満たしません。

stopアクション：検知結果の報告とプロファイル比較

stopはTraceeコンテナを止めたあと、同梱のprofile-genで記録をプロファイルとシグネチャ検知結果に分けます。シグネチャが1件でも出ていれば、トリガーがpull_requestのときはそのPRにコメントし、それ以外のイベントではジョブのログへ出力します。続いて実行・DNS・書き込みの3種類のプロファイルを、リポジトリの.tracee/にある基準ファイルと比べます。

ワークフローへの組み込み手順

ジョブの最初のステップにstart、最後のステップにstopを置きます。READMEの例はv0.3.0のままですが、最新はv0.4.0です。タグは後から書き換えられる可能性があるため、コミットSHAで固定します。SHA固定の手順と自動化はSHA Pinningとは？GitHub ActionsをコミットSHAで固定する方法【Enforce設定・pinact v5】にまとめています。

name: ci
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: write        # プロファイル更新ブランチのpushに必要
  pull-requests: write   # PRへのコメントとPR作成に必要

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - name: Start Tracee
        timeout-minutes: 5
        uses: aquasecurity/tracee-action@9dd4f95736ab133fdf698321913b5498ed656420 # v0.4.0-start
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - run: make test
      - name: Stop Tracee
        if: ${{ !cancelled() }}
        uses: aquasecurity/tracee-action@1c04135eb3d95a927e75721ac49c9ae6038bf0ee # v0.4.0-stop
        with:
          fail-on-diff: true

stopの差分処理は、チェックアウトしたリポジトリの中でgitとghを使います。そのためactions/checkoutはstopより前に置き、認証情報を残すpersist-credentialsは既定のtrueのままにします。stopに付けたif: ${{ !cancelled() }}は、テストが失敗した実行でもTraceeの停止と結果の回収を行うための指定で、startのtimeout-minutesはヘルスチェック待ちが終わらない場合にジョブ全体の上限まで待たないための保険です。なお、2023年9月以降にランナーイメージの更新へ合わせた変更は入っていません。ubuntu-24.04（現在のubuntu-latest）やubuntu-26.04で使う場合は、検証用リポジトリで起動を確かめてから広げてください。

start／stopの入力パラメータと既定値

リポジトリ側の権限設定

GitHubのドキュメントによると、個人アカウントで新しく作ったリポジトリではGITHUB_TOKENはcontentsとpackagesの読み取り権限しか持たず、ワークフローがPRを作成・承認することも既定で許可されていません（組織のリポジトリは組織の設定を継承）。プロファイル更新PRを受け取るには、リポジトリのSettings → Actions → Generalで「Allow GitHub Actions to create and approve pull requests」を有効にし、ワークフローに上のpermissionsを書きます。権限を絞る考え方はGitHub Actionsのpermissions｜GITHUB_TOKENの既定権限と最小権限の設計を参照してください。

公開リポジトリへのフォークPRをpull_requestで実行する場合、GITHUB_TOKENは読み取り専用です。シグネチャ検知時のPRコメントはgh pr commentで書き込むため、この構成では投稿できません。外部からのPRを受け付ける公開リポジトリでは、検知結果をPR上で受け取る運用が成り立たない点に注意が必要です。なおプライベートリポジトリでは、管理設定でフォークPRに書き込み権限のトークンを渡すことを許可できます。

シグネチャとプロファイル、2つの検知方式

シグネチャ：既知の攻撃パターンの検出

policies/signatures.yaml.tmplで有効になっているシグネチャは29種類です。Tracee標準のものとして、ld_preload（LD_PRELOADによる共有ライブラリの差し込み）、fileless_execution（ディスクに置かないバイナリの実行）、dropped_executable（実行時に書き出された実行ファイル）、kernel_module_loading、sudoers_modificationなどが並びます。ワークスペース配下のファイル変更を捉えるfile_modificationはv0.4.0で追加されました。

アクションに同梱されたRegoのシグネチャは2本です。miner_domain（TRC_1002）はethermine・nanopool・minexmrなど暗号通貨のマイニングプールについて、固定の一覧にあるドメインへのDNS問い合わせを検出し、file_write（TRC_1001）はファイルへの書き込みを捉えます。依存パッケージに仕込まれたマイナーを捉えられるのは、一覧に載ったドメインを名前解決したときだけです。一覧に無いドメインやIPアドレスへの直接接続は、このシグネチャでは検出できません。

プロファイル：普段の挙動からの逸脱の検出

stopは次の3つのJSONを生成し、.tracee/の同名ファイルと比べます。

envs: trueは、Traceeのイベント出力に環境変数を含める設定です。ただし、それを実行プロファイルへ変換するv0.4.0-stopのprofile/exec.jqには不具合があります。リポジトリ同梱のテストデータのうち、環境変数を含むprofile/test/exec.jsonlに同梱の既定設定で当てると、jq 1.6でも1.7.1でも「Cannot index array with string “value”」で終了コード5になります。envsを有効にするなら、exec.jqの修正が前提です。

docs/profile.mdにはprofile-files.jsonとprofile-network.jsonという名前が書かれていますが、stopアクションが比較しているのは上の3つです。基準ファイルを手で用意する場合は実装側の名前に合わせます。

初回は基準ファイルが無いため、記録したすべてが差分として扱われ、tracee-profile-updateブランチから「Updates to tracee profile」というPRが作られます。このPRをマージした内容が、以後の比較の基準になります。依存関係の追加やビルド手順の変更で正当な差分が出たときも、同じPRで基準を更新します。

profile-config.jsonによる変動値の除外設定

一時ディレクトリのパスやトークンのように毎回変わる値がプロファイルに入ると、実行のたびに差分が出ます。リポジトリに.tracee/profile-config.jsonを置くと、同梱の既定設定の代わりにこのファイルが使われ、正規表現に一致した引数・環境変数・ドメインを除外できます。既定設定は丸ごと置き換わるため、既定の除外項目も書き写します。

{
  "args_discard": ["/home/runner/work/_temp/"],
  "args_discard_pair": ["--token"],
  "env_discard": ["RUNNER_TRACKING_ID", "SYSTEMD_EXEC_PID", "INVOCATION_ID", "JOURNAL_STREAM", "GITHUB_"],
  "dns_discard": ["pipelines.actions.githubusercontent.com"],
  "binary_sha256_discard": []
}

args_discard_pairは一致した引数と直後の引数をまとめて落とすので、--token 値の形で渡す秘密情報を基準ファイルに残さずに済みます。dns_discardに接続先を足すほど検知の網は粗くなるため、除外は毎回必ず変わる値に限ります。

ソースから分かるv0.4.0の挙動の癖

stopの差分判定はcheck.shが担います。v0.4.0-stopのcheck.shを、ghとgitを何もしないスタブに置き換えて実行すると、次の2点が再現します。どちらもREADMEやdocsには書かれていません。確認したのはv0.4.0-stopのcheck.shとv0.4.0-stopのaction.yamlです。

create-pr: falseでも起きるPR作成

check.shはPR作成の分岐をif [ "$create_pr" ]と書いています。これは「文字列が空でないか」の判定なので、入力の既定値である文字列falseも真になります。

create_pr=false
if [ "$create_pr" ]; then echo "PRを作る分岐に入る"; fi
# 出力: PRを作る分岐に入る

スタブ実行でも、create-prにfalseを渡した状態でgh pr createが呼ばれました。差分をPRにせずログだけで確認したい場合、この入力では止められません。

fail-on-diff: trueでも成功する条件

stopは実行・DNS・書き込みの3種類についてcheck.shを1回ずつ呼び、0以外を返した回数を数えて失敗を判定します。ところがcheck.shの終了コードは、差分の有無ではなく最後に実行したコマンド、つまりgh pr createの結果です。スタブ実行でも、PR作成が成功した場合は差分があっても終了コード0、失敗した場合（同じブランチのPRが既にある、権限が足りない等）だけ1でした。

このため、更新用のPRがまだ無い状態で差分が1種類だけのときは、PR作成が成功してfail-on-diff: trueでもジョブは成功扱いになります。2種類以上に差分があると、2回目以降のPR作成が既存PRとの重複で失敗し、ジョブは失敗します。つまり失敗するかどうかは、差分の大きさではなくPRの状態で決まります。

差分でCIを確実に止めたいなら、アクションをフォークしてcheck.shが差分の有無を終了コードで返すように直すか、後述の代替を選びます。

同梱Tracee更新時のCLI・ポリシー互換性

startはTracee 0.17.1を--healthzフラグ付きで起動します。v0.24.1のcmd/tracee/cmd/root.goにはこの単独フラグが無く、ヘルスチェックは--server healthzに統合されています。フォークして新しいTraceeを使う場合は、起動フラグ・ポリシーの書式・同梱のRegoシグネチャの互換性を、版タグのドキュメントとソースで1つずつ確かめる必要があります。

2026年に選ぶならどれか：代替手段の比較

Harden-Runner：公開リポジトリなら最初の候補

StepSecurityのHarden-Runnerは、ジョブの最初のステップに置くと外向き通信の宛先とファイル書き込みを記録します。egress-policyはaudit（通信先を記録。ただし既知の悪性宛先は遮断）とblock（許可リスト以外を遮断）の2つで、action.ymlの既定値はblockです。READMEの導入例はauditを指定しているので、最初はauditを明示して通信先を洗い出し、固まったらallowed-endpointsに書いてblockへ移る順が安全です。

    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1 # v2.21.1
        with:
          egress-policy: audit

無料のCommunity版が使えるのは、公開リポジトリをGitHubホストランナーで動かす組み合わせだけです。プライベートリポジトリとセルフホストランナー（ARCを含む）はEnterprise（有料）が必要で、契約の無いセルフホストでは「ステップは成功するが何も監視しない」状態になるとREADMEに明記されています。READMEには2025年3月のtj-actions/changed-files侵害（CVE-2025-30066）を検出した事例も載っています。事件の経緯はtj-actionsとreviewdogに関連するインシデントの概要とその経緯で扱っています。

Tracee本体の自前起動と保守負担

プライベートリポジトリやセルフホストランナーで費用をかけずにランタイム監視をしたいなら、tracee-actionのaction.yamlを雛形にして、Traceeの起動と停止を自分のワークフローに書く方法が残ります。この場合、イメージの更新、ポリシーの調整、検知結果で落とすかどうかの判定はすべて自分で保守します。CIだけでなくKubernetes上の本番ワークロードの監視まで同じ仕組みでそろえたい場合は、同じeBPF系のFalcoも候補になります。比較の観点はFalcoとは？ランタイム脅威検知の仕組みとルール運用・誤検知の抑え方を解説にあります。

tracee-actionを採用すべきでない場面

• リリースパイプラインのゲート：fail-on-diffの挙動上、差分があってもジョブが通る場合がある。
• 秘密情報を扱うジョブ：2023年8月のイメージを特権コンテナで動かすことになり、その後のTracee側の修正が入らない。
• macOS・Windowsランナーのジョブ：TraceeがLinux専用で、そもそも動かない。

一方で、eBPFでCIの挙動がどう見えるかを確かめる、プロファイル差分という考え方を検証用リポジトリで試す、といった学習用途なら今でも読む価値のある実装です。CI/CD全体の守り方はサプライチェーンセキュリティとは？開発工程に組み込む防御と2026年規制対応の実装判断で整理しています。

よくある質問

tracee-actionは無料で使えますか？

アクション自体はApache-2.0のOSSで無料です。GitHubホストランナーをプライベートリポジトリで使う場合、プランに含まれる無料枠を超えた実行時間などが課金対象です。アーティファクトやキャッシュの保存にも課金条件があり、セルフホストでは実行基盤の費用を別途負担します。

Traceeとtracee-actionの違いは何ですか？

TraceeはeBPFでLinuxの挙動を記録・検知するツール本体で、DockerコンテナやKubernetes上のDaemonSetとして動かします。tracee-actionはTraceeをGitHub Actionsのジョブ内で起動し、結果をPRコメントやプロファイルPRに変換するラッパーです。本体はv0.24.1まで進んでいますが、tracee-actionが使うのは0.17.1です。

tracee-actionは今も使えますか？

リポジトリはアーカイブされておらずタグも残っているため、ワークフローから参照すること自体はできます。ただしREADMEはデモ目的で活発な開発をしていないと明記しており、実装コードの更新は2023年9月で止まっています。READMEにはその後も変更があり、2025年2月に開発状況の注記が追加されています。現在のランナーイメージで動くかは自分で確かめる必要があり、本番のCIを守る用途には向きません。

検知結果はどこで確認できますか？

シグネチャ検知は、pull_requestトリガーならそのPRのコメント、それ以外ならstopステップのログに出ます。プロファイル差分はtracee-profile-updateブランチからのPRとして届き、差分の先頭20行が本文に入ります。

セルフホストランナーでも動きますか？

action.yamlが前提にしているのは、Linux、ホストで使えるDocker、特権コンテナの起動、Runner.Listenerプロセスの4点です。stopはこれに加えてjq・git・ghを使います。またmkdir /tmp/tracee-actionを-pなしで実行するため、使い捨てでないランナーでは前回のディレクトリが残っていると2回目以降のstopが失敗します。tracee-actionとしての対応表や動作保証もありません。

関連記事

• Falcoとは？ランタイム脅威検知の仕組みとルール運用・誤検知の抑え方を解説
• eBPFとは？Linuxカーネルを拡張する仕組みと可観測性・ネットワークでできること
• GitHub Actionsのpermissions｜GITHUB_TOKENの既定権限と最小権限の設計
• SHA Pinningとは？GitHub ActionsをコミットSHAで固定する方法【Enforce設定・pinact v5】
• サプライチェーンセキュリティとは？開発工程に組み込む防御と2026年規制対応の実装判断