Harden-Runner

Corporate laptops and production servers have strong security monitoring for compliance and risk reduction. However, CI/CD runners, which handle sensitive data like cloud secrets and production builds, often lack such protections, making them targets for supply chain attacks like SolarWinds and Codecov.

Traditional security tools struggle with CI/CD runners due to their short-lived nature and lack of workflow context.

Harden-Runner fills this gap by providing tailored security monitoring, ensuring CI/CD runners receive the same protection as other critical systems.

Security Incidents Detected

• Harden-Runner Detected the tj-actions/changed-files compromise (CVE-2025-30066)

• Harden-Runner Detected a CI/CD Supply Chain Attack in Google’s Open-Source Project Flank

• Harden-Runner Detected a CI/CD Supply Chain Attack in Microsoft’s Open-Source Project Azure Karpenter Provider in Real-Time

• Harden-Runner Detected Anomalous Traffic to api.ipify.org Across Multiple Customers

• Harden-Runner Flagged an Anomalous Outbound Call, Leading to a Docker Documentation Update

Threats in a CI/CD Environment

Compromised workflows, dependencies, and build tools pose two major threats:

1. Exfiltration of CI/CD credentials and source code

2. Tampering of source code, dependencies, or artifacts during the build process to inject backdoors

To mitigate these risks, Harden-Runner provides key security measures. The table below outlines its core functionalities and the threats they help prevent:

Security Measure	Function	Past Breach Example
Network Traffic Control	Monitor and block outbound network traffic at the DNS, HTTPS (Layer 7), and network layers (Layers 3 and 4) to prevent exfiltration of code and CI/CD credentials	To prevent the Codecov breach scenario
Source Code Integrity Check	Detect if source code is being tampered during the build process to inject a backdoor	To detect the XZ Utils and SolarWinds incident scenarios
Dependency and Workflow Monitoring	Detect poisoned workflows and compromised dependencies that exhibit suspicious behavior	To detect Dependency confusion and Malicious dependencies scenarios
GitHub Token Permission Enforcement	Determine minimum GITHUB_TOKEN permissions by monitoring HTTPS calls to GitHub APIs	To set minimum GITHUB_TOKEN permissions to reduce the impact of exfiltration

Enabling Runtime Security with Harden-Runner

Securing your CI/CD pipelines requires configuring your runners with StepSecurity’s Harden-Runner, which provides comprehensive monitoring and protection across different runner environments.

Harden-Runner supports multiple CI/CD runner types:

Environment Type	Compatibility	Audit Mode Deployment	Workflow Changes for Audit Mode
GitHub-Hosted runners	✅ Full support	Add Harden-Runner Action to workflow	Yes
Self-hosted VM runners	✅ Full support	Include agent in runner image	No
Self-hosted bare-metal runners	✅ Full support	Install agent as a service	No
Actions Runner Controller (ARC)	✅ Full support	Deploy as DaemonSet	No
RunsOn Runners	✅ Full support	Pre-integrated	No

GitHub-Hosted Runners

Step 1: Add the step-security/harden-runner GitHub Action to your GitHub Actions workflow file as the first step in each job. You can automate adding Harden-Runner Action to your workflow file by using Secure Workflow.

steps:
  - uses: step-security/harden-runner@v2 # v2.10.3
    with:
      egress-policy: audit

Step 2: You will see a link to security insights and recommendations in the workflow logs and the job markdown summary.

build log

Step 3: Click on the link (example link). You will see a process monitor view of network and file events correlated with each step of the job.

StepSecurity Insights Page showing Network Events

Step 4: In the Recommended Policy tab, you'll find a recommended block policy based on outbound calls aggregated from the current and past runs of the job. You can update your workflow file with this policy or use the Policy Store to apply the policy without modifying the workflow file. From now on, any outbound calls not on the allowed list will be blocked.

StepSecurity Insights Page showing Recommendations

Self-Hosted VM Runners

To enable runtime security for self-hosted runners on Cloud VMs (e.g. EC2 instances), you can add the Harden-Runner agent to your runner image.

Instead of adding the Harden-Runner GitHub Action in each job, you'll need to install the Harden-Runner agent on your runner image (e.g., AMI). This is typically done using a packer or as a post-install step when using the https://github.com/philips-labs/terraform-aws-github-runner project to set up runners.

The Harden-Runner agent monitors all jobs run on the VM; both ephemeral and persistent runners are supported; you do NOT need to add the Harden-Runner GitHub Action to each job for audit mode. You must add the Harden-Runner GitHub Action to jobs where you want to enable block mode.

Both ephemeral and persistent VM runners are supported.

You can access security insights and runtime detections under the Harden-Runner section in your dashboard.

Instructions for installing the Harden-Runner agent on your runner image are available in the Dashboard under Settings .

This agent is different from the one used for GitHub-hosted runners.

Self-Hosted bare-metal Runners

Self-hosted bare-metal runners are set up by installing the harden-runner agent as a service. This setup closely resembles the self-hosted cloud VM scenario but runs directly on physical hardware instead of virtualized environments.

Actions Runner Controller (ARC) Runners

Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates and scales self-hosted runners for GitHub Actions.

Rather than incorporating the Harden Runner GitHub Action into each individual workflow, you'll need to install the ARC-Harden-Runner daemonset on your Kubernetes cluster.

Upon installation, the ARC Harden-Runner daemonset monitors all jobs run on the cluster; you do NOT need to add the Harden-Runner GitHub Action to each job for audit mode. You need to add the Harden-Runner GitHub Action to jobs where you want to enable block mode.

You can access security insights and runtime detections under the Runtime Security tab in your dashboard.

Installation instructions for the ARC-Harden-Runner daemonset are available in the Dashboard under Settings

How to access Harden-Runner security insights

For each GitHub Actions workflow run, Harden-Runner monitors the run-time network, file, and process events and makes runtime insights available via the StepSecurity Web App.

There are four ways to find the insights link:

• BuildLog

• Workflow Runs

• Markdown Job Summary

• GitHub Checks

BuildLog

Step 1: Navigate to build log of your workflow file in Github Actions.

Step 2: Look for the Harden-Runner step in the log and click on the Insights link which appears in the logs as View security insights and recommended policy at: followed by a clickable URL (this is an example link).

build log

Step 3: Once you click on the Insights link, you will be redirected to the Summary tab in the StepSecurity Web App. The Summary Page provides an overview of:

• Outbound destinations contacted during the job execution.

• HTTPS requests and the number of actions taken.

• Detections (if any security risks were found).

StepSecurity Insights Summary Page

Workflow runs

StepSecurity provides a dashboard where you can view the latest GitHub Actions workflow runs monitored by Harden-Runner. This guide will help you navigate the dashboard and access insights for specific workflow runs.

Step 1: Navigate to https://app.stepsecurity.io/github/<GITHUB_ORG_NAME>/actions/dashboard

Step 2: In the left-hand menu, under Harden-Runner, click Workflow Runs

StepSecurity sidebar displaying different sections.

Step 3: After opening the Workflow Runs page, locate the workflow you want to inspect and click on it.

StepSecurity Workflow Runs page showing different workflow runs

Step 4: Once inside the workflow details page, navigate to the Summary tab.

Here, you can review:

• Outbound destinations contacted during the workflow.

• Security detections (if any were found).

• Actions performed by the workflow.

StepSecurity Insights summary page

Markdown Job Summary

Step 1: Navigate to the workflow run page

Step 2: Click "📄 View Full Report"

StepSecurity markdown report

Step 3: Review the outbound connections allowed during the workflow execution.

StepSecurity Insights summary page

GitHub Checks

To enable GitHub Checks, check out this guide.

Step 1: Navigate to the Pull Request

Step 2: View Check Details

• Look at the checks summary under your pull request.

• Identify any failed or successful checks.

• Click on the “Details” link next to the StepSecurity Harden-Runner check.

List of GitHub Checks including StepSecurity Harden-Runner check

Step 3: Access Insights URL

• On the new page, select StepSecurity Harden-Runner from the list of workflow checks.

• Find the Insights URL under the Workflow Run Insights section.

• Click the Insights URL to proceed.

StepSecurity Harden-Runner Check

Step 4: Review Security Insights

• The Insights page will display outbound traffic details, network events, and security findings.

• Verify if any unauthorized outbound connections were detected.

• Review the All Outbound Destinations and All Detections sections for further analysis.

StepSecurity Insights summary page