Runtime security with StepSecurity Harden-Runner

StepSecurity Harden-Runner ↗ is a security agent for CI runners. It records what each job does, and can block what a job should not do. RunsOn publishes runner images with the agent already installed, so all you add is an API key.

A CI runner holds registry and cloud secrets and produces your release builds, yet it is rarely monitored like a laptop or a server. Harden-Runner covers that gap:

• Network egress. It records every outbound connection of a job. From that baseline it can flag new destinations, or enforce an allow list and block the rest.
• GitHub API calls. It shows which GitHub API calls a job makes, which tells you the smallest GITHUB_TOKEN permissions the workflow needs.
• File changes. It detects source files modified during the build.
• Step-level detail. Each connection, file write and process is tied to the step, job and workflow it came from.
• GitHub Checks. It can fail a pull request check when a run does something outside its baseline.

Set it up#

1. Get a StepSecurity API key. This needs a StepSecurity Enterprise license. You can start a free trial ↗.

2. Give the key to RunsOn.

   Flex

   Set the IntegrationStepSecurityApiKey stack parameter, or integration_step_security_api_key with Terraform.

   Fleet

   Set the integration_step_security_api_key input of the Fleet module.

3. Run your jobs on a StepSecurity image.

   Flex

   jobs:
     build:
       runs-on:
         - runs-on=${{ github.run_id }}
         - runner=2cpu-linux-x64
         - image=ubuntu24-stepsecurity-x64

   Fleet

   runners = {
     linux-secured = {
       family = ["c8i.large"]
       image  = "ubuntu24-stepsecurity-x64"
     }
   }
   
   fleets = {
     linux-secured = {
       runner = "linux-secured"
     }
   }

4. Open your StepSecurity dashboard ↗ to see the network, process and file activity of each run.

Images#

Use an instance family that matches the image’s architecture, such as c8g or m8g for arm64.

How it works on RunsOn#

• The agent is in the image. RunsOn hands your API key to the runner. When the job starts, RunsOn starts the agent for the organization that owns the repository.
• Only StepSecurity images are affected. Jobs on any other image run as before.
• If the agent cannot start, the job still runs. The job log then shows a StepSecurity warning: “Failed to start the StepSecurity agent; continuing without protection.”
• Linux only. There is no StepSecurity image for Windows.

Example#

Add the step-security/harden-runner step to choose a policy for the job. Start with audit, which only records what the job connects to:

name: Build

on:
  pull_request:

jobs:
  build:
    runs-on:
      - runs-on=${{ github.run_id }}
      - runner=2cpu-linux-x64
      - image=ubuntu24-stepsecurity-x64
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit

      - uses: runs-on/action@v2

      - uses: actions/checkout@v7

      - run: npm ci && npm test

Once you know what the job needs, switch to block and list the endpoints it may reach. Everything else is refused:

      - name: Harden Runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: block
          allowed-endpoints: >
            github.com:443
            registry.npmjs.org:443

StepSecurity tests RunsOn with a longer workflow ↗ that covers the host, Docker containers and Docker builds. These are the insights ↗ for one of its runs:

FAQ#

How much does StepSecurity cost?#

StepSecurity charges by the number of contributing developers in protected repositories. See its pricing page ↗.

The integration is included in your RunsOn license, at no extra cost.

Does Harden-Runner slow down jobs?#

Harden-Runner is built for low overhead.

Can I use the Harden-Runner community tier with RunsOn?#

No. The community tier only works on GitHub-hosted runners. Self-hosted runners, RunsOn included, need a StepSecurity Enterprise license.

Resources#

• StepSecurity documentation ↗
• StepSecurity case studies ↗
• RunsOn security model