cicd-sensor と連携

cicd-sensor は、GitHub Actions など CI 環境向けのオープンソースの eBPF ランタイムセキュリティセンサーです。CI/CD ジョブに cicd-sensor を導入すると、Takumi Runner を利用しなくてもジョブの実行をトレースし、そのログを Takumi に送信することが可能になります。

cicd-sensor のみご利用の場合でも、ルールを設定して脅威を検知したり、トレースログを保管したりできますが、Takumi と連携することにより、取得したトレースログをより効果的に活用できます。

Takumi と連携することにより、以下が可能になります。

トレースログが可視化できる
トレース検索機能により、サプライチェーンインシデント発生時に該当期間のトレースログを調査できる
脅威検出機能により、弊社の専門知識とシステムを活かした脅威を検出する機能をご利用いただける

info

cicd-sensor のルールは Takumi との連携と併用いただけます。

サポートされている CI/CD パイプライン

cicd-sensor の連携は実行環境に依存しないため、基本的には cicd-sensor がサポートする CI/CD パイプラインに対応しています。cicd-sensor は以下の CI/CD 環境に対応しています。

GitHub Actions
- GitHub ホステッドランナー
  - x64
  - arm64
- セルフホステッドランナー
- Blacksmith ランナー
  - x64
GitLab CI/CD
- Self-Managed Runner

Third party ランナーなど他にも対応している環境がありますので、詳しくはcicd-sensor のドキュメントをご覧ください。

警告

cicd-sensor は GitLab ホステッドランナーには対応しておりません。また、GitHub ホステッドランナーの ubuntu-slim と Blacksmith の arm64 ランナーにも対応しておりません。

cicd-sensor のトレースログを Takumi に送信する

cicd-sensor から Takumi へトレースログを送信できるよう、独自の cicd-sensor Manager（以下「Takumi の Manager」）を提供しています。cicd-sensor の Manager 設定で Takumi の Manager を指定することによって連携されます。

GitHub ホステッドランナーをご利用の場合

GitHub Actions のジョブでは cicd-sensor のパラメータ manager-url で Manager を指定します。

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - uses: cicd-sensor/cicd-sensor-action@49560b716a9abba9190a48c0b6bca18ba98918e8 # v0.0.40
        with:
          manager-url: https://manager.cicdsensor.cloud.shisho.dev
          manager-token: ${{ secrets.AUTH_TOKEN }} #トークンの設定は後述

manager-token に関しては以下の認証をご確認ください。

GitHub ホステッドランナー以外をご利用の場合

cicd-sensor の導入は CI/CD の環境により異なるため、cicd-sensor のドキュメントをご確認ください。

cicd-sensor が導入されたら、後は Manager の設定をするだけです。 Manager を設定するには Manager のエンドポイント manager-url と認証情報 manager-token を指定します。こちらの設定方法も実行環境によって異なるため、cicd-sensor のドキュメントをご確認ください。

Takumi の Manager のエンドポイントと認証情報は以下の通りです。

manager-url: https://manager.cicdsensor.cloud.shisho.dev
manager-token: 認証をご覧ください

認証

認証は、キーレス OIDC と API キーを使う 2 つの方法があります。どちらも Shisho Cloud のボットを利用して行います。

はじめに、Shisho Cloud のボット作成ページを開いてボットを作成してください。ボットの作成時には、必ずミッション固有ロールの Takumi Runnerトレース送信者 を指定してください（ルールと config のプッシュ用のボットを作成の場合は Takumi Runner設定管理者 のロールを選択してください）。

ボットの追加

Takumi Runnerトレース送信者ロールの選択

ここからは、キーレス OIDC を設定するか API キーを作成するかによって手順が異なります。セルフホステッドランナーなど、OIDC 認証が行えない環境では API キーをご利用ください。

方法 A: OIDC によるキーレス認証

キーレス認証では、ワークフロー実行時に短命なトークンを取得するため、長期間有効なシークレットを CI 環境に保存する必要がありません。

キーレス認証を利用するには、Shisho Cloud でボットに、GitHub Organization とリポジトリを紐付ける信頼条件を作成します。

信頼条件の作成

オーディエンス欄は空のままにしてください。flatt-security/shisho-cloud-action@v1 は特定のオーディエンスを要求しないため、空欄にするとトークンの aud クレームは検証されません。ワークフローが特定のオーディエンスを要求する場合に限り、その値をそのまま入力してください。

ボットを作成したら、次にワークフローで OIDC トークンを取得する設定を入れます。

GitHub Actions をご利用の場合、トークンは flatt-security/shisho-cloud-action@v1 を使って取得できます。OIDC トークンの取得には id-token: write 権限が必要です。

警告

id-token: write を指定したジョブでは、GitHub の OIDC トークンが発行できるようになります。トークンは Shisho Cloud 以外のサービスでも利用が可能なため、ジョブの侵害時に他サービスへの不正アクセスに使われる可能性があります。ここでは environment を cicd-sensor に設定してトークンがこの値を subject で持つようにし、少しでも他サービスで利用できる可能性を下げます。また、id-token: write の適用範囲で必要以上の処理を行わないようご注意ください。

以下は、 OIDC トークンを取得するワークフローです。

jobs:
  build:
    runs-on: ubuntu-latest
    environment: cicd-sensor # このジョブ専用の environment
    permissions:
      contents: read
      id-token: write
    steps:
      - id: auth
        uses: flatt-security/shisho-cloud-action@v1
        with:
          bot-id: <Bot ID>
          export-token: true
          expires-in-minutes: 360
      - uses: cicd-sensor/cicd-sensor-action@49560b716a9abba9190a48c0b6bca18ba98918e8 # v0.0.40
        with:
          manager-url: https://manager.cicdsensor.cloud.shisho.dev
          manager-token: ${{ steps.auth.outputs.token }}

<Bot ID> は、作成したボットの ID に置き換えてください。

トークンの有効期限（expires-in-minutes）はワークフローで指定されるため、ジョブの実行中に期限切れにならないようご注意ください。

方法 B: ボットの API キー

API キーを発行するには、ボットのページの「API キー」タブを開きます。ここから新しい API キーを作成してください。

API キーの作成

Manager に送信するトークンの形式は以下です。

<API キー>:<Bot ID>

この値は、GitHub Organization のシークレットなど、安全な場所に保存してください。ワークフローから secrets.SHISHO_CICD_SENSOR_TOKEN として参照できる場合は、以下のように manager-token で指定します。

steps:
  - uses: cicd-sensor/cicd-sensor-action@49560b716a9abba9190a48c0b6bca18ba98918e8 # v0.0.40
    with:
      manager-url: https://manager.cicdsensor.cloud.shisho.dev
      manager-token: ${{ secrets.SHISHO_CICD_SENSOR_TOKEN }}

cicd-sensor のルールと config を管理する

cicd-sensor の Manager では、ルールと config の管理も行えます。Takumi の Manager では、ORAS で OCI アーティファクトを Takumi のレジストリにプッシュすることによって、ルールと設定ファイルが更新されます。

ルールのレジストリエンドポイント: configs.cicdsensor.cloud.shisho.dev/orgs/<org_id>/rules
config ファイルのレジストリエンドポイント: configs.cicdsensor.cloud.shisho.dev/orgs/<org_id>/config

<org_id> は、Shisho Cloud の組織 ID です。

プッシュには、ミッション固有ロールの Takumi Runner設定管理者 を持つボットが必要です。ボットの作成方法は、トレースログ送信用のボットを作成する上記の認証をご覧ください。設定管理用のボットはトレースログ送信用とは別のボットを作成する必要があります。トレースログ送信と同様、キーレス OIDC および API キーによる認証が利用可能です。

ルールと config はリポジトリの .cicd-sensor/ のディレクトリーで管理することを推奨します。プッシュは以下ワークフローで行えます。

name: push-cicd-sensor-rules-and-config
on:
  push:
    branches: [main]
    paths:
      - ".cicd-sensor/**"

permissions:
  id-token: write
  contents: read

jobs:
  push:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Install cicd-sensorctl
        run: |
          curl -fsSL -o /tmp/cicd-sensor.tar.gz \
            "https://github.com/cicd-sensor/cicd-sensor/releases/download/releases/v0.0.44/cicd-sensor_0.0.44_linux_amd64.tar.gz"
          tar -xzf /tmp/cicd-sensor.tar.gz -C /tmp ./cicd-sensorctl-linux-amd64
          sudo install /tmp/cicd-sensorctl-linux-amd64 /usr/local/bin/cicd-sensorctl

      - uses: oras-project/setup-oras@1d808f7d7f6995cc68b7bf507bfe5c5446e1dc9d # v2.0.1

      - id: auth
        uses: flatt-security/shisho-cloud-action@v1
        with:
          bot-id: <Bot ID> # 「Takumi Runner設定管理者」ロールを持つボット
          export-token: true

      - name: Log in to the registry
        run: |
          printf '%s' '${{ steps.auth.outputs.token }}' |
            oras login configs.cicdsensor.cloud.shisho.dev --username '<Bot ID>' --password-stdin

      - name: Bundle, validate, and push the rules
        run: |
          cicd-sensorctl rule bundle --input-dir .cicd-sensor/rules --output-file bundle.yaml
          cicd-sensorctl rule validate bundle.yaml
          gzip -nc bundle.yaml > bundle.yaml.gz
          echo "rule bundle digest: sha256:$(sha256sum bundle.yaml.gz | cut -d' ' -f1)" # 後述のステータス確認で使う
          oras push "configs.cicdsensor.cloud.shisho.dev/orgs/<org_id>/rules:v1" \
            --artifact-type application/vnd.cicd-sensor.baseline.rules.config.v1+json \
            bundle.yaml.gz:application/vnd.cicd-sensor.baseline.rules.v1+yaml+gzip

      - name: Push the config file
        run: |
          gzip -nc .cicd-sensor/config.yaml > config.yaml.gz
          echo "config bundle digest: sha256:$(sha256sum config.yaml.gz | cut -d' ' -f1)" # 後述のステータス確認で使う
          oras push "configs.cicdsensor.cloud.shisho.dev/orgs/<org_id>/config:v1" \
            --artifact-type application/vnd.cicd-sensor.config.v1+json \
            config.yaml.gz:application/vnd.cicd-sensor.config.v1+yaml+gzip

ルールと config は、基本的に同じ流れでプッシュしますが、ルールの場合は設定不備を事前に確認するため cicd-sensorctl で一度検証した後にプッシュします。

プッシュ後の状態は、ジョブが出力するダイジェストを使って確認できます。ルールは /v1/rule-bundles、設定ファイルは /v1/config-bundles から確認します。

$ curl -H "Authorization: Bearer <トークン>" \
    "https://configs.cicdsensor.cloud.shisho.dev/v1/rule-bundles/sha256:<ダイジェスト>/status"
{"state": "promoted", ...}

state は pending・promoted・rejected の３種類があります。バンドルに問題がある場合は rejected になります。検証を通過すると promoted になり、その後すべてのジョブに適用されます。pending は、プッシュがまだ処理中であることを意味します。

Takumi の Manager を利用する場合、変更可能な config は output_settings.detection.enabled のみになります。他の項目は反映されません。

output_settings:
  detection:
    enabled: true

Takumi の機能を利用する

cicd-sensor を利用したジョブの実行が完了すると、内容が Shisho Cloud コンソールに反映されます。可視化されたトレースデータの確認やトレース検索・脅威検出機能の利用が可能になります。

料金体系

cicd-sensor 連携の料金体系に関しては料金体系をご覧ください。

サポートされている CI/CD パイプライン​

cicd-sensor のトレースログを Takumi に送信する​

GitHub ホステッドランナーをご利用の場合​

GitHub ホステッドランナー以外をご利用の場合​

認証​

方法 A: OIDC によるキーレス認証​

方法 B: ボットの API キー​

cicd-sensor のルールと config を管理する​

Takumi の機能を利用する​

料金体系​