# cicd-sensor と連携 {#cicdsensor-integration}

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

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

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

- [トレースログが可視化](/docs/ja/t/runner/features/trace-visualization.md)できる
- [トレース検索機能](/docs/ja/t/runner/features/trace-search.md)により、サプライチェーンインシデント発生時に該当期間のトレースログを調査できる
- [脅威検出機能](/docs/ja/t/runner/features/threat-detection.md)により、弊社の専門知識とシステムを活かした脅威を検出する機能をご利用いただける

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

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

cicd-sensor の連携は実行環境に依存しないため、基本的に cicd-sensor がサポートする CI/CD パイプラインには対応しています。cicd-sensor がサポートしているパイプラインに関しては [cicd-sensor のドキュメント](https://cicd-sensor.github.io/user-guide/overview.html)をご確認ください。

## cicd-sensor のトレースログを Takumi に送信する {#send-traces}

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

### GitHub ホステッドランナーをご利用の場合 {#github-hosted-runner}

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

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

`manager-token` に関しては以下の[認証](#authentication)をご確認ください。

### GitHub ホステッドランナー以外をご利用の場合 {#non-github-hosted-runner}

cicd-sensor の導入は CI/CD の環境により異なるため、[cicd-sensor のドキュメント](https://cicd-sensor.github.io/user-guide/overview.html)をご確認ください。

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

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

- **`manager-url`:** `https://manager.cicdsensor.cloud.shisho.dev`
- **`manager-token`:** [認証](#authentication)をご覧ください

### 認証 {#authentication}

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

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

![ボットの追加](/docs/ja/_md-assets/1395520a4c-cicdsensor-create-bot.png)

![Takumi Runnerトレース送信者ロールの選択](/docs/ja/_md-assets/f557a8a1dd-cicdsensor-select-role.png)

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

#### 方法 A: OIDC によるキーレス認証 {#keyless-oidc}

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

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

![信頼条件の作成](/docs/ja/_md-assets/2ab3af446b-cicdsensor-trust-condition.png)

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

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

:::warning
`id-token: write` を指定したジョブでは、GitHub の OIDC トークンが発行できるようになります。トークンは Shisho Cloud 以外のサービスでも利用が可能なため、ジョブの侵害時に他サービスへの不正アクセスに使われる可能性があります。認証処理は別ジョブに分けて、`id-token: write` の適用範囲を最小限にしてください。
:::

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

```yaml
jobs:
  auth:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    outputs:
      token: ${{ steps.auth.outputs.token }}
    steps:
      - id: auth
        uses: flatt-security/shisho-cloud-action@v1
        with:
          bot-id: <Bot ID>
          export-token: true
          expires-in-minutes: 360
  build:
    needs: auth
    runs-on: ubuntu-latest
    steps:
      - uses: cicd-sensor/cicd-sensor-action@a803a7bc1890f85d3f2feb7c29b74b5c730da6c2 # v0.0.37
        with:
          manager-url: https://manager.cicdsensor.cloud.shisho.dev
          manager-token: ${{ needs.auth.outputs.token }}
```

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

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

#### 方法 B: ボットの API キー {#api-key}

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

![API キーの作成](/docs/ja/_md-assets/432de45a20-cicdsensor-create-apikey.png)

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

```
<API キー>:<Bot ID>
```

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

```yaml
steps:
  - uses: cicd-sensor/cicd-sensor-action@a803a7bc1890f85d3f2feb7c29b74b5c730da6c2 # v0.0.37
    with:
      manager-url: https://manager.cicdsensor.cloud.shisho.dev
      manager-token: ${{ secrets.SHISHO_CICD_SENSOR_TOKEN }}
```

## cicd-sensor のルールと config を管理する {#manage-rules-config}

cicd-sensor の Manager では、ルールと config の管理も行えます。Takumi の Manager では、[ORAS](https://oras.land/) で 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設定管理者** を持つボットが必要です。ボットの作成方法は、トレースログ送信用のボットを作成する上記の[認証](#authentication)をご覧ください。設定管理用のボットはトレースログ送信用とは別のボットを作成する必要があります。トレースログ送信と同様、キーレス OIDC および API キーによる認証が利用可能です。

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

```yaml
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` から確認します。

```console
$ 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` のみになります。他の項目は反映されません。

```yaml
output_settings:
  detection:
    enabled: true
```

## Takumi の機能を利用する {#takumi-features}

cicd-sensor を利用したジョブの実行が完了すると、内容が Shisho Cloud コンソールに反映されます。[可視化されたトレースデータ](/docs/ja/t/runner/features/trace-visualization.md)の確認や[トレース検索](/docs/ja/t/runner/features/trace-search.md)・[脅威検出](/docs/ja/t/runner/features/threat-detection.md)機能の利用が可能になります。

## 料金体系 {#pricing}

cicd-sensor 連携の料金体系に関しては[料金体系](/docs/ja/t/runner/billing/pricing.md)をご覧ください。