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

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
    • セルフホステッドランナー
  • GitLab CI/CD
    • Self-Managed Runner

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

警告

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

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@6511eb44c91d71b2b93d71193b1bf2cb18352f66 # v0.0.38
        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@6511eb44c91d71b2b93d71193b1bf2cb18352f66 # v0.0.38
        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@6511eb44c91d71b2b93d71193b1bf2cb18352f66 # v0.0.38
    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 連携の料金体系に関しては料金体系をご覧ください。

に最終更新