# Rego インラインポリシー

このページでは、ワークフロー中のジョブに対して Rego で記述されたインラインポリシーと、Shisho Cloud の間の API 仕様を示します。

## `jobs[].decide.rego` に関する API

`jobs[].decide.rego` に指定されたインラインポリシーは、[ワークフロー](/docs/ja/g/concepts/workflow.md) の持つ「データ取得 → 検査/監査 → 結果の通知・結果の記録」という機能のうち、検査・監査の役割を持ちます。

![](/docs/ja/_md-assets/005ec9db77-how-workflows-work.ja.png)

### パッケージ名

制限はありません。自由なパッケージ名を指定できます。

```rego
package arbitrary.name.could.be.specified
```

### ポリシー実行時の入力

`jobs[].decide.rego` に指定されたインラインポリシーに対しては、いくつかの入力が与えられます。

#### `input`

`input` 変数には、`jobs[].decide.input.schema` に指定された GraphQL クエリにより取得されたデータが格納されます。

:::info

例えば同 GraphQL クエリが以下のようなものだったとします:

```graphql
query {
  github {
    organizations {
      login
      requiresTwoFactorAuthentication
    }
  }
}
```

このとき、インラインポリシー中からアクセスできる `input` という変数に、以下のようなオブジェクトが格納されます:

```json
{
  "github": {
    "organizations": [
      {
        "login": "octcat",
        "requiresTwoFactorAuthentication": true
      },
      {
        "login": "your-org-name",
        "requiresTwoFactorAuthentication": false
      }
    ]
  }
}
```

インラインポリシーから上記のオブジェクトへのアクセスは、以下のようにして行えます:

```rego
org := input.github.organizations[_]
```

:::

#### `data.shisho`

`data.shisho` 変数には、[Shisho Cloud 公式の Rego ライブラリ](https://github.com/flatt-security/shisho-cloud-rego-libraries) 中の定義が格納されています。

:::info

例えば、[shisho.decision.dependency パッケージ中の package_known_vulnerability 関数](https://github.com/flatt-security/shisho-cloud-rego-libraries/blob/ed057664c7f687432af8b16530a3aaf7617e841e/decision/dependency/package.gen.rego#L48) にアクセスしたい場合、以下のような Rego ポリシーを記述できます:

```rego
import data.shisho

x := shisho.decision.dependency.package_known_vulnerability(...)
```

:::

### ポリシーに期待される出力

#### `decisions` 変数

インラインポリシーは `decisions` というリストに、_Decision_ と呼ばれる構造のデータのリスト（配列）を格納しなくてはなりません。
これを通して、インラインポリシーは、ポリシーによる検査/監査結果を Shisho Cloud に伝えることが出来ます。

:::info

[Shisho Cloud 公式の Rego ライブラリ](https://github.com/flatt-security/shisho-cloud-rego-libraries) 中で、`"Emits a decision ..."` なる `description` が指定された関数を用いることで、特定の `kind` を持った `decision` を簡単に発行できます。

:::

## `jobs[].notify.rego` に関する API

### パッケージ名

制限はありません。自由なパッケージ名を指定できます。

### ポリシー実行時の入力

#### `input.query`

`jobs[].notify.input.schema` で指定された GraphQL クエリにより取得されたデータが格納されています。

#### `input.organization_id`

ワークフローが実行されている組織の ID が格納されています。

#### `input.workflow_id`

ワークフローの ID が格納されています。

#### `input.job_id`

当該インラインポリシーが指定されているジョブの ID が格納されています。

#### `input.decisions`

当該インラインポリシーが指定されているジョブの `decide` ブロックにより生成された `decisions` が格納されています。

#### `input.running_state`

当該インラインポリシーが指定されているジョブの実行状態が格納されています。

:::info

[shisho.job 以下](https://github.com/flatt-security/shisho-cloud-rego-libraries/blob/main/job/running_state.rego) に、この変数が取りうる値が定数として定義されています。

:::

#### `input.exit_code`

当該インラインポリシーが指定されているジョブの実行状態が格納されています。

:::info

[shisho.job 以下](https://github.com/flatt-security/shisho-cloud-rego-libraries/blob/main/job/exit_code.rego) に、この変数が取りうる値が定数として定義されています。

:::

#### `data.shisho`

`data.shisho` 変数には、[Shisho Cloud 公式の Rego ライブラリ](https://github.com/flatt-security/shisho-cloud-rego-libraries) 中の定義が格納されています。

### ポリシーに期待される出力

#### `notifications` 変数

インラインポリシーは `notifications` というリストに、_Notification_ と呼ばれる構造のデータのリスト（配列）を格納する必要があります。
これを通して、インラインポリシーは、Shisho Cloud に通知の送信を指示できます。

:::info

[Shisho Cloud 公式の Rego ライブラリ](https://github.com/flatt-security/shisho-cloud-rego-libraries) 中の `shisho.notification.new()` 関数を用いて、_Notification_ オブジェクトを容易に作成できます。

:::