Policy Store

The policy store holds a collection of customized policies for your workflows, allowing you to easily manage and update policies in a single location.

Steps To Create and Use a Policy

For GitHub-Hosted Runners

Step 1: Navigate to the Policy Store

• Open StepSecurity, then navigate to the Harden Runner section and click on Policy Store

Step 2: Click "Create policy"

Step 3: Create a New Policy

• Enter a policy name.

• Configure the policy settings (e.g., allowed endpoints, telemetry settings).

• Click Add Policy to save.

Step 4: Apply the Policy in Your Workflow

• Remove any existing manual policy configurations.

• Add the policy name under the Harden Runner step.

• Ensure id-token: write permission is explicitly set in your workflow file. This permission is required to authenticate with the StepSecurity backend API and fetch the policy.

Here’s an example:

name: CI

on:
  pull_request:

permissions:
  contents: read
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Harden Runner
      uses: step-security/harden-runner@446798f8213ac2e75931c1b0769676d927801858 # v2.10.0
      with:
        policy: Test-policy

Step 5: Verify the Integration

• Run a test workflow to ensure the policy is applied correctly.

For Self-Hosted Runners

Policies are applied based on scope, following a defined precedence. If a workflow-level policy exists, it takes priority. If not, the system checks for a repository-level policy. If that's also absent, an organization-level policy will be applied. Finally, if none of the above are defined, the cluster-level policy will be enforced

To use the Policy Store with self-hosted runners, you first need to configure a pre-job hook:

Pre-Job Hook Setup

• Go to Settings → Self-Hosted Runners → Runner Job Hooks.

• Follow the provided script to configure the hook as a pre-job hook for your runner.

Once the hook is configured, proceed with policy creation:

Step 1: Navigate to the Policy Store

• Go to the Harden Runner section

• Click Policy Store

Step 2: Create a Policy

• Click Create Policy

• Enter a policy name

• Manually add allowed endpoints

Step 3: Import Endpoints (Optional)

• You can also automatically import endpoints from baseline

Step 4: Select a baseline source

Step 5: Click Import Endpoints

Step 6: Save the Policy

• Click Add Policy

Step 5: Attach the Policy

• Click the three-dot menu next to the policy.

• Select Attach Policy.

Step 6: Choose whether to attach it to a Cluster, Organization, Repository, or Workflow.

Step 7: Click "Attach Policy"

Example: Policy Enforcement

• Suppose you create a policy that only allows specific endpoints

• During a workflow run, if the job attempts to call a domain not on the allowlist, the request will be automatically blocked.

• On the Network Events tab of the Insights page, you can see that the policy was responsible for blocking the request and causing the run to fail