docs: align policy structure (#307)

* docs: align policy rego structure and fix typos

* docs: Update gh page creation script by removing policy remediation indexing

* docs: fix detached metadata

* chore: update max-file-length in .regal/config.yaml

* docs: align policies to the desired structure

* docs: update repository title to reflect the need for regular secret updates

* docs: Ensuring that tests pass

* docs: fix latest PR review comments

* test: fix tests due to policy changes

* docs: update organization secret title to reflect the need for regular updates

---------

Co-authored-by: noamd-legit <[email protected]>

.regal/config.yaml

@@ -5,8 +5,8 @@ rules:
       level: ignore
   style:
     file-length:
-      # Override default of 500 as one file has 515 lines
-      max-file-length: 550
+      # Override default of 500 as one file has 690 lines
+      max-file-length: 750
     line-length:
       # Violations here mostly from metadata annotation values.
       # These could be fixed by using |> and newlines, but we'll

policies/bundle_test.go

@@ -2,9 +2,10 @@ package policies
 
 import (
 	"embed"
-	"github.com/stretchr/testify/require"
 	"path"
 	"testing"
+
+	"github.com/stretchr/testify/require"
 )
 
 func countFiles(fs embed.FS, p string) (int, error) {
@@ -46,5 +47,5 @@ func TestPoliciesBundle(t *testing.T) {
 	count, err := countBundles()
 
 	require.Nilf(t, err, "counting files: %v", err)
-	require.Equal(t, count, 10, "Expecting 10 files in bundle")
+	require.Equal(t, count, 9, "Expecting 9 files in bundle")
 }

policies/github/actions.rego

@@ -6,16 +6,21 @@ package actions
 # description: By not limiting GitHub Actions to specific repositories, every user in the organization is able to run arbitrary workflows. This could enable malicious activity such as accessing organization secrets, crypto-mining, etc.
 # custom:
 #   requiredEnrichers: [organizationId]
-#   remediationSteps: [Make sure you have admin permissions, Go to the org's settings page, Enter the "Actions - General" tab, Under "Policies", Change "All repositories" to "Selected repositories" and select repositories that should be able to run actions, Click "Save"]
+#   remediationSteps: 
+#     - 1. Make sure you have admin permissions
+#     - 2. Go to the org's settings page
+#     - 3. Enter the 'Actions - General' tab
+#     - 4. Under 'Policies', Change 'All repositories' to 'Selected repositories' and select repositories that should be able to run actions
+#     - 5. Click 'Save'
 #   severity: MEDIUM
 #   requiredScopes: [admin:org]
-#   threat:
-#     - "This misconfiguration could lead to the following attack:"
-#     - "1. Prerequisite: the attacker is part of your GitHub organization"
-#     - "2. Attacker creates new repository in the organization"
-#     - "3. Attacker creates a workflow file that reads all organization secrets and exfiltrate them"
-#     - "4. Attacker trigger the workflow"
-#     - "5. Attacker receives all organization secrets and uses them maliciously"
+#   threat: 
+#     - This misconfiguration could lead to the following attack:
+#     - 1. Prerequisite: the attacker is part of your GitHub organization
+#     - 2. Attacker creates new repository in the organization
+#     - 3. Attacker creates a workflow file that reads all organization secrets and exfiltrate them
+#     - 4. Attacker trigger the workflow
+#     - 5. Attacker receives all organization secrets and uses them maliciously
 #   requiredScopes: [admin:org]
 default all_repositories_can_run_github_actions := true
 
@@ -29,14 +34,21 @@ all_repositories_can_run_github_actions := false {
 # description: It is recommended to only use GitHub Actions by Marketplace verified creators or explicitly trusted actions. By not restricting which actions are permitted, developers may use actions that were not audited and may be malicious, thus exposing your pipeline to supply chain attacks.
 # custom:
 #   requiredEnrichers: [organizationId]
-#   remediationSteps: [Make sure you have admin permissions, Go to the org's settings page, Enter "Actions - General" tab, Under "Policies", 'Select "Allow enterprise, and select non-enterprise, actions and reusable workflows"', Check "Allow actions created by GitHub" and "Allow actions by Marketplace verified creators", Set any other used trusted actions under "Allow specified actions and reusable workflows", Click "Save"]
+#   remediationSteps: 
+#     - 1. Make sure you have admin permissions
+#     - 2. Go to the org's settings page
+#     - 3. Enter 'Actions - General' tab
+#     - 4. Under 'Policies', Select 'Allow enterprise, and select non-enterprise, actions and reusable workflows'
+#     - 5. Check 'Allow actions created by GitHub' and 'Allow actions by Marketplace verified creators'
+#     - 6. Set any other used trusted actions under 'Allow specified actions and reusable workflows'
+#     - 7. Click 'Save'
 #   severity: MEDIUM
 #   requiredScopes: [admin:org]
 #   threat:
-#     - "This misconfiguration could lead to the following attack:"
-#     - "1. Attacker creates a repository with a tempting but malicious custom GitHub Action"
-#     - "2. An innocent developer / DevOps engineer uses this malicious action"
-#     - "3. The malicious action has access to the developer repository and could steal its secrets or modify its content"
+#     - This misconfiguration could lead to the following attack:
+#     - 1. Attacker creates a repository with a tempting but malicious custom GitHub Action
+#     - 2. An innocent developer / DevOps engineer uses this malicious action
+#     - 3. The malicious action has access to the developer repository and could steal its secrets or modify its content
 default all_github_actions_are_allowed := true
 
 all_github_actions_are_allowed := false {
@@ -50,12 +62,12 @@ all_github_actions_are_allowed := false {
 # custom:
 #   requiredEnrichers: [organizationId]
 #   remediationSteps:
-#     - Make sure you have admin permissions
-#     - Go to the org's settings page
-#     - Enter "Actions - General" tab
-#     - Under 'Workflow permissions'
-#     - Select 'Read repository contents permission'
-#     - Click 'Save'
+#     - 1. Make sure you have admin permissions
+#     - 2. Go to the org's settings page
+#     - 3. Enter 'Actions - General' tab
+#     - 4. Under 'Workflow permissions'
+#     - 5. Select 'Read repository contents permission'
+#     - 6. Click 'Save'
 #   severity: MEDIUM
 #   requiredScopes: [admin:org]
 #   threat: In case of token compromise (due to a vulnerability or malicious third-party GitHub actions), an attacker can use this token to sabotage various assets in your CI/CD pipeline, such as packages, pull-requests, deployments, and more.
@@ -72,12 +84,12 @@ token_default_permissions_is_read_write := false {
 # custom:
 #   requiredEnrichers: [organizationId]
 #   remediationSteps:
-#     - Make sure you have admin permissions
-#     - Go to the org's settings page
-#     - Enter "Actions - General" tab
-#     - Under 'Workflow permissions'
-#     - Uncheck 'Allow GitHub actions to create and approve pull requests.
-#     - Click 'Save'
+#     - 1. Make sure you have admin permissions
+#     - 2. Go to the org's settings page
+#     - 3. Enter 'Actions - General' tab
+#     - 4. Under 'Workflow permissions'
+#     - 5. Uncheck 'Allow GitHub actions to create and approve pull requests'
+#     - 6. Click 'Save'
 #   severity: HIGH
 #   requiredScopes: [admin:org]
 #   threat: Attackers can exploit this misconfiguration to bypass code-review restrictions by creating a workflow that approves their own pull request and then merging the pull request without anyone noticing, introducing malicious code that would go straight ahead to production.