docs: separate documents about policies (#216)

suzuki-shunsuke · Nov 16, 2023 · a2bfca1 · a2bfca1
1 parent 04b99d4
commit a2bfca1
Show file tree

Hide file tree

Showing 7 changed files with 275 additions and 203 deletions.
diff --git a/README.md b/README.md
@@ -6,209 +6,12 @@ GitHub Actions linter for security best practices.
 
 ## Policies
 
-- `job_permissions`: All jobs should have `permissions`
-  - Why: For least privilege
-  - Exceptions
-    - workflow's `permissions` is empty `{}`
-    - workflow has only one job and the workflow has `permissions`
-- `deny_read_all_permission`: `read-all` permission should not be used
-  - Why: For least privilege
-- `deny_write_all_permission`: `write-all` permission should not be used
-  - Why: For least privilege
-- `deny_inherit_secrets`: `secrets: inherit` should not be used
-  - Why: Secrets should be exposed to only required jobs
-- `workflow_secrets`: Workflow should not set secrets to environment variables
-  - How to fix: set secrets to jobs
-  - Why: To limit the scope of secrets
-  - Exceptions
-    - workflow has only one job
-- `job_secrets`: Job should not set secrets to environment variables
-  - How to fix: set secrets to steps
-  - Why: To limit the scope of secrets
-  - Exceptions
-    - job has only one step
-
-### job_permissions
-
-:x:
-
-```yaml
-permissions:
-  contents: read
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    # Without permissions
-    steps:
-      - run: echo hello
-  bar:
-    runs-on: ubuntu-latest
-    # Without permissions
-    steps:
-      - uses: actions/checkout@v3
-```
-
-:o:
-
-```yaml
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions: {} # Set permissions
-    steps:
-      - run: echo hello
-  bar:
-    runs-on: ubuntu-latest
-    permissions: # Set permissions
-      contents: read
-    steps:
-      - uses: actions/checkout@v3
-```
-
-Or
-
-```yaml
-permissions: {} # empty permissions
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo hello
-  bar:
-    runs-on: ubuntu-latest
-    permissions: # Set permissions
-      contents: read
-    steps:
-      - uses: actions/checkout@v3
-```
-
-### deny_read_all_permission
-
-:x:
-
-```yaml
-name: test
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions: read-all # Don't use read-all
-    steps:
-      - run: echo foo
-```
-
-:o:
-
-```yaml
-name: test
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - run: echo foo
-```
-
-### deny_write_all_permission
-
-Same with `deny_read_all_permission`.
-
-## deny_inherit_secrets
-
-:x:
-
-```yaml
-jobs:
-  release:
-    uses: suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml@v0.4.4
-    secrets: inherit # `inherit` should not be used
-```
-
-:o:
-
-```yaml
-jobs:
-  release:
-    uses: suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml@v0.4.4
-    secrets: # Only required secrets should be passed
-      gh_app_id: ${{ secrets.APP_ID }}
-      gh_app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
-```
-
-### workflow_secrets
-
-:x:
-
-```yaml
-name: test
-env:
-  GITHUB_TOKEN: ${{github.token}}
-  DATADOG_API_KEY: ${{secrets.DATADOG_API_KEY}}
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions: {}
-    steps:
-      - run: echo foo
-  bar:
-    runs-on: ubuntu-latest
-    permissions: {}
-    steps:
-      - run: echo bar
-```
-
-:o:
-
-```yaml
-name: test
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions: {}
-    env:
-      GITHUB_TOKEN: ${{github.token}}
-    steps:
-      - run: echo foo
-  bar:
-    runs-on: ubuntu-latest
-    permissions: {}
-    env:
-      DATADOG_API_KEY: ${{secrets.DATADOG_API_KEY}}
-    steps:
-      - run: echo bar
-```
-
-### job_secrets
-
-:x:
-
-```yaml
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-    env:
-      GITHUB_TOKEN: ${{github.token}} # secret is set in job
-    steps:
-      - run: echo foo
-      - run: gh label create bug
-```
-
-:o:
-
-```yaml
-jobs:
-  foo:
-    runs-on: ubuntu-latest
-    permissions:
-      issues: write
-    steps:
-      - run: echo foo
-      - run: gh label create bug
-        env:
-          GITHUB_TOKEN: ${{github.token}} # secret is set in step
-```
+- [job_permissions](docs/policies/001.md): All jobs should have `permissions`
+- [deny_read_all_permission](docs/policies/002.md): `read-all` permission should not be used
+- [deny_write_all_permission](docs/policies/003.md): `write-all` permission should not be used
+- [deny_inherit_secrets](docs/policies/004.md): `secrets: inherit` should not be used
+- [workflow_secrets](docs/policies/005.md): Workflow should not set secrets to environment variables
+- [job_secrets](docs/policies/006.md): Job should not set secrets to environment variables
 
 ## How to install
 

diff --git a/docs/policies/001.md b/docs/policies/001.md
@@ -0,0 +1,66 @@
+# job_permissions
+
+All jobs should have `permissions`
+
+## Why?
+
+For least privilege.
+
+## Exceptions
+
+- workflow's `permissions` is empty `{}`
+- workflow has only one job and the workflow has `permissions`
+
+## Examples
+
+:x:
+
+```yaml
+permissions:
+  contents: read
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    # Without permissions
+    steps:
+      - run: echo hello
+  bar:
+    runs-on: ubuntu-latest
+    # Without permissions
+    steps:
+      - uses: actions/checkout@v3
+```
+
+:o:
+
+```yaml
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    permissions: {} # Set permissions
+    steps:
+      - run: echo hello
+  bar:
+    runs-on: ubuntu-latest
+    permissions: # Set permissions
+      contents: read
+    steps:
+      - uses: actions/checkout@v3
+```
+
+Or
+
+```yaml
+permissions: {} # empty permissions
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo hello
+  bar:
+    runs-on: ubuntu-latest
+    permissions: # Set permissions
+      contents: read
+    steps:
+      - uses: actions/checkout@v3
+```
diff --git a/docs/policies/002.md b/docs/policies/002.md
@@ -0,0 +1,34 @@
+# deny_read_all_permission
+
+`read-all` permission should not be used
+
+## Why?
+
+For least privilege.
+
+## Examples
+
+:x:
+
+```yaml
+name: test
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    permissions: read-all # Don't use read-all
+    steps:
+      - run: echo foo
+```
+
+:o:
+
+```yaml
+name: test
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - run: echo foo
+```
diff --git a/docs/policies/003.md b/docs/policies/003.md
@@ -0,0 +1,34 @@
+# deny_write_all_permission
+
+`write-all` permission should not be used.
+
+## Why?
+
+For least privilege.
+
+## Examples
+
+:x:
+
+```yaml
+name: test
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    permissions: write-all # Don't use write-all
+    steps:
+      - run: echo foo
+```
+
+:o:
+
+```yaml
+name: test
+jobs:
+  foo:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - run: echo foo
+```
diff --git a/docs/policies/004.md b/docs/policies/004.md
@@ -0,0 +1,29 @@
+# deny_inherit_secrets
+
+`secrets: inherit` should not be used
+
+## Why?
+
+Secrets should be exposed to only required jobs.
+
+## Examples
+
+:x:
+
+```yaml
+jobs:
+  release:
+    uses: suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml@v0.4.4
+    secrets: inherit # `inherit` should not be used
+```
+
+:o:
+
+```yaml
+jobs:
+  release:
+    uses: suzuki-shunsuke/go-release-workflow/.github/workflows/release.yaml@v0.4.4
+    secrets: # Only required secrets should be passed
+      gh_app_id: ${{ secrets.APP_ID }}
+      gh_app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
+```