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

GitHub 組織の監査自動化

このチュートリアルでは、GitHub 組織の監査自動化のための、ポリシーの記述とデプロイ方法を説明します。

ゴール​

  • GitHub 組織に対する監査ポリシーの書き方を知る
  • 既存ポリシーの変更方法・テスト方法を知る
  • 変更したポリシーのデプロイ方法を知る

準備​

このページ を参照し、同ページ中の ./shisho-cloud-workflows ディレクトリ同等の構造のディレクトリを用意してください。 具体的には、以下のような構造のディレクトリです:

./shisho-cloud-workflows
├── lib
│   ├── README.md
│   ├── decision
│   │   ├── dependency
│   │   │   ├── package.gen.rego
│   │   │   ├── package.pb.rego
│   │   │   └── vulnerability.rego
│
...
│
├── prebundle-workflow-github-configurations
│   ├── manifest.yaml
│   ├── notify
│   │   ├── decide
│   │   │   ├── input.graphql
│   │   │   ├── policy.rego
│   │   │   └── policy_test.rego
│   │   └── notify
│   │       ├── input.graphql
│   │       ├── policy.rego
│   │       └── policy_test.rego
...

デフォルトのポリシーを確認する​

以降では、shishoctl workflow export --structured コマンドにより標準搭載のワークフローを書き出した際に、以下のパスに書き出される Rego ポリシーを例にとって説明します。

./shisho-cloud-workflows/prebundle-workflow-github-configurations/review-org-owners-number/decide/policy.rego

この Rego ポリシーは、標準状態では、およそ以下のような内容になっています:

package policy.github.config.review_org_owners_number

import data.shisho

max_admin_num = 2

admins(org) = x {
  x = [member.login | member := org.members[_]; member.role == "OWNER"]
}

decisions[d] {
  org := input.github.organizations[_]
  allowed := count(admins(org)) <= max_admin_num

  e := shisho.decision.github.org_owners_entry(org.policyReportId, admins(org))

  d := shisho.decision.github.org_owners({
    "allowed": allowed,
    "subject": org.policyReportId,
    "entries": [e],
  })
}

なお、このポリシーは、同じディレクトリに含まれる input.graphql で定義されている、以下の GraphQL クエリにより取得されたデータに対するものです:

query {
  github {
    organizations {
      policyReportId

      members {
        login
        role
        policyReportId
      }
    }
  }
}

同ポリシーでは、input.github.organizations[_] (GraphQL クエリを通して取得した GitHub 組織の情報) を列挙しながらレビューしています。 とりわけ、その中の members フィールドの持つ要素のうち、ロールが定数 OWNER である要素の数を数え、それが規定数以上であれば deny を示す Decision を出力しています。

ワークフロー中のポリシーを修正する​

この Rego ポリシーでは、GitHub 組織ごとに許容されるオーナーの数を示す定数 max_admin_num に、値 2 がセットされています。 試しに、これを以下のように編集し、GitHub 組織ごとに許容されるオーナーの数を 3 人まで引き上げてみましょう:

max_admin_num = 3

単体テストを記述する​

次に、この変更が適切に動作していることを確かめるために、単体テストを記述してみましょう。 まずは以下のファイルを開いてください:

./shisho-cloud-workflows/prebundle-workflow-github-configurations/review-org-owners-number/decide/policy_test.rego

そして、以下のような Rego コードを記述してみましょう:

package policy.github.config.review_org_owners_number

import data.shisho
import future.keywords

dummy_account := {
    "login": "dummy",
    "role": "OWNER",
    "policyReportId": "dummy-account",
}

test_decision_with_few_admins if {
    count([d |
        decisions[d]
        shisho.decision.is_allowed(d)
    ]) == 1 with input as {"github": {"organizations": [{
        "policyReportId": "dummy",
        "members": [dummy_account, dummy_account],
    }]}}

    count([d |
        decisions[d]
        shisho.decision.is_allowed(d)
    ]) == 1 with input as {"github": {"organizations": [{
        "policyReportId": "dummy",
        "members": [dummy_account, dummy_account, dummy_account],
    }]}}
}

test_decision_with_too_many_admins if {
    count([d |
        decisions[d]
        not shisho.decision.is_allowed(d)
    ]) == 1 with input as {"github": {"organizations": [{
        "policyReportId": "dummy",
        "members": [dummy_account, dummy_account, dummy_account, dummy_account],
    }]}}
}

記述したテストは、Open Policy Agent をインストール した後に以下のようなコマンドを実行することで、実際に実行できます:

# in your ./shisho-cloud-workflows
opa test ./

ここまでのステップが適切に実行できていれば、以下のように、2 つのテストが PASS するはずです。 これで確かに、GitHub 組織ごとに許容されるオーナーの数を 3 人まで引き上げることができました:

prebundle-workflow-github-configurations/review-org-owners-number/decide/policy_test.rego:
data.policy.github.config.review_org_owners_number.test_decision_with_few_admins: PASS (11.614042ms)
data.policy.github.config.review_org_owners_number.test_decision_with_too_many_admins: PASS (1.328917ms)
--------------------------------------------------------------------------------
PASS: 2/2

ワークフローを適用・実行する​

最後に、変更済みのワークフローを Shisho Cloud にデプロイしてみましょう！ これは shishoctl workflow apply コマンドにより実現できます:

# Run the following in your ./shisho-cloud-workflows
# (need to set the ID of your Shisho Cloud organization to $YOUR_ORG_ID)
shishoctl workflow apply \
    -o $YOUR_ORG_ID \
    -f ./prebundle-workflow-github-configurations/manifest.yaml