# 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. **Community Tier Availability** * **Public repositories only:** The Community Tier does not support private repositories. To enable Harden-Runner on private repositories, upgrade to the Enterprise Tier, which includes a 14-day free trial. For teams with higher usage needs or private repository support, the Enterprise Tier provides expanded capacity and advanced features. ## Security Incidents Detected * [Harden-Runner Detected the tj-actions/changed-files compromise](https://www.stepsecurity.io/blog/harden-runner-detection-tj-actions-changed-files-action-is-compromised) ([CVE-2025-30066](https://github.com/advisories/GHSA-mrrh-fwg8-r2c3)) * [Harden Runner Detected the Sha1-Hulud Supply Chain Attack in CNCF's Backstage Repository](https://www.stepsecurity.io/blog/how-harden-runner-detected-the-sha1-hulud-supply-chain-attack-in-cncfs-backstage-repository) * [Harden-Runner Detected the NX Build System compromise](https://www.stepsecurity.io/blog/supply-chain-security-alert-popular-nx-build-system-package-compromised-with-data-stealing-malware) * [Harden-Runner Detected a CI/CD Supply Chain Attack in Google’s Open-Source Project Flank](https://www.stepsecurity.io/case-studies/flank) * [Harden-Runner Detected a CI/CD Supply Chain Attack in Microsoft’s Open-Source Project Azure Karpenter Provider in Real-Time](https://www.stepsecurity.io/case-studies/azure-karpenter-provider) * [Harden-Runner Detected Anomalous Traffic to api.ipify.org Across Multiple Customers](https://www.stepsecurity.io/blog/harden-runner-detects-anomalous-traffic-to-api-ipify-org-across-multiple-customers) * [Harden-Runner Detected an Unexpected Microsoft Defender Installation on GitHub-Hosted Ubuntu Runners ](https://www.stepsecurity.io/blog/how-stepsecurity-harden-runner-detected-unexpected-microsoft-defender-installation-on-github-hosted-ubuntu-runners) ## Threats in a CI/CD Environment Compromised workflows, dependencies, and build tools pose several 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 3. Exploitation of third party GitHub Actions 4. Dependency based supply chain attacks 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](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/ExfiltratingCICDSecrets.md#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](https://www.stepsecurity.io/blog/analysis-of-backdoored-xz-utils-build-process-with-harden-runner) and [SolarWinds incident ](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/TamperingDuringBuild.md#sunspot-an-implant-in-the-build-process)scenarios | | Dependency and Workflow Monitoring | Detect poisoned workflows and compromised dependencies that exhibit suspicious behavior | To detect [Dependency confusion](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/ExfiltratingCICDSecrets.md#dependency-confusion-attacks) and [Malicious dependencies](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/ExfiltratingCICDSecrets.md#compromised-dependencies) scenarios | | GitHub Token Permission Enforcement | Determine minimum GITHUB\_TOKEN permissions by monitoring HTTPS calls to GitHub APIs | To set [minimum GITHUB\_TOKEN permissions](https://www.stepsecurity.io/blog/determine-minimum-github-token-permissions-using-ebpf-with-stepsecurity-harden-runner) to reduce the impact of exfiltration | | Threat Intelligence-Driven Blocking | StepSecurity's 24×7 SOC identifies IOC domains and IPs from active supply-chain attacks and adds them to a Global Block List that is enforced automatically across every protected workflow. | To block exfiltration from the [pgserve npm compromise](https://www.stepsecurity.io/blog/pgserve-compromised-on-npm-malicious-versions-harvest-credentials) in real time | ## Global Block List Harden-Runner enforces a **Global Block List** of domains and IP addresses associated with active supply-chain attacks. The list is maintained by StepSecurity's 24×7 Security Operations Center (SOC), which continuously tracks emerging threats across the CI/CD ecosystem and the npm, PyPI, and GitHub Actions registries. **Automatic, zero-config enforcement:** When our SOC identifies a new indicator of compromise (IOC), it's added to the Global Block List and takes effect immediately across every workflow using Harden-Runner — no configuration change, no action version bump, no workflow edit required. **Enforced regardless of egress policy:** The Global Block List is enforced even when a workflow is running in `egress-policy: audit` mode. IOCs represent known-malicious infrastructure, so customers shouldn't have to re-decide whether to block each one. Allowlisting an IOC domain in your policy does **not** override the Global Block List. This is intentional — it prevents a compromised action or misconfigured workflow from granting itself access to known-malicious infrastructure. **When an entry fires,** the blocked request appears on the workflow's Network Events and Detections views, labeled **Attack Blocked** so you can distinguish it from regular policy blocks. {% hint style="info" %} You don't manage the Global Block List directly — it's maintained centrally by StepSecurity so every customer benefits from threat intelligence gathered across the entire fleet. If you believe a domain has been blocked in error, contact StepSecurity support. {% endhint %} ## Enabling Runtime Security with Harden-Runner Securing your CI/CD pipelines starts with protecting your runners. StepSecurity’s Harden-Runner provides comprehensive monitoring and protection across different runner environments. Because these runners handle sensitive build processes, dependencies, and secrets, runtime protection is essential to prevent supply chain attacks. Harden-Runner supports multiple CI/CD runner types:
Environment TypeCompatibilityAudit Mode DeploymentWorkflow Changes for Audit Mode
GitHub-Hosted runners (Linux, macOS, Windows)✅ Full supportAdd Harden-Runner Action to workflowYes
GitHub-Hosted Custom VM✅ Full supportInclude agent in runner imageNo
Self-hosted VM runners✅ Full supportInclude agent in runner imageNo
Self-hosted bare-metal runners✅ Full supportInstall agent as a serviceNo
Actions Runner Controller (ARC)✅ Full supportDeploy as DaemonSetNo
RunsOn Runners✅ Full supportPre-integratedNo
BlackSmith✅ Full supportAdd Harden-Runner Action to workflowYes
Namespace✅ Full supportAdd Harden-Runner Action to workflowYes
Warp✅ Full supportAdd Harden-Runner Action to workflowYes
Depot✅ Full supportAdd Harden-Runner Action to workflowYes
### Harden-Runner Endpoints The Harden-Runner agent requires outbound access to the following endpoints on port 443 (HTTPS). If your runner environment uses a firewall, proxy, or network allowlist, ensure these endpoints are permitted. | Endpoint | Purpose | | --------------------------------------------------------------------- | ------------------------------------------------ | | `agent.api.stepsecurity.io:443` | Agent communication and policy retrieval | | `prod.app-api.stepsecurity.io:443` | Telemetry | | `customer-transient-data-277233109775.s3.us-west-2.amazonaws.com:443` | Transient data storage for runtime event uploads | All communication is encrypted over TLS. These endpoints are automatically allowed by Harden-Runner and do not need to be added to your allowed endpoints list. However, if your organization has configured firewalls at the infrastructure level (e.g., network firewalls, proxy servers, or cloud security groups), these endpoints must be permitted for Harden-Runner to function correctly. ### 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 showing link to StepSecurity insights page

build log

**Step 3:** Click on the link ([example link](https://app.stepsecurity.io/github/step-security/github-actions-goat/actions/runs/7704454287)). 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

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

StepSecurity Insights Page showing Recommendations

### GitHub-Hosted Custom VM GitHub-hosted custom VM runners combine the flexibility of self-managed environments with the convenience of GitHub’s hosted infrastructure. Harden-Runner enables runtime security for GitHub-hosted custom VM runners by providing continuous monitoring and policy enforcement directly on the VM image. Unlike the standard GitHub-hosted environment, which requires adding the Harden-Runner GitHub Action in each workflow, custom VM environments can be preconfigured with the Harden-Runner agent for persistent protection. {% hint style="info" %} Instructions for installing the Harden-Runner agent on your runner image are available under **Harden-Runner Installations** under `Settings` . {% endhint %} ### 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](https://github.com/github-aws-runners/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 For jobs where you want to enable `block` mode, there are two options: * Attach a [policy](/harden-runner/policy-store.md#for-self-hosted-runners) to enforce blocking behavior. * Add the Harden-Runner GitHub Action directly to those specific jobs. {% hint style="info" %} Both ephemeral and persistent VM runners are supported. {% endhint %} You can access security insights and runtime detections under the `Harden-Runner` section in your dashboard. {% hint style="info" %} Instructions for installing the Harden-Runner agent on your runner image are available under **Harden-Runner Installations** under `Settings` . This agent is different from the one used for GitHub-hosted runners. {% endhint %} ### 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. For jobs where you want to enable `block` mode, there are two options: * Attach a [policy](/harden-runner/policy-store.md#for-self-hosted-runners) to enforce blocking behavior. * Add the Harden-Runner GitHub Action directly to those specific jobs. You can access security insights and runtime detections under the Runtime Security tab in your dashboard. {% hint style="info" %} Installation instructions for the ARC-Harden-Runner daemonset are available under the **Harden-Runner Installations** under `Settings` {% endhint %} ### Third-Party GitHub Actions Runners Harden-Runner supports third-party GitHub Actions runner providers that offer faster, cheaper, or region-specific alternatives to GitHub-hosted runners. Integration works the same way as with GitHub-hosted runners: add the `step-security/harden-runner` action as the first step of each job. Only the `runs-on` value changes. The following providers are supported: * [Blacksmith](https://www.blacksmith.sh/) * [Depot](https://depot.dev/) * [Namespace](https://namespace.so/) * [Warp Build](https://warpbuild.com/) {% hint style="info" %} Harden-Runner action **v2.19.0 or later** is required for third-party runner support. {% endhint %} #### **Blacksmith** Use a Blacksmith runner label in `runs-on` and add Harden-Runner as the first step: ```yaml jobs: build: runs-on: blacksmith-4vcpu-ubuntu-2404 steps: - uses: step-security/harden-runner@v2.19.0 with: use-policy-store: true api-key: ${{ secrets.STEP_SECURITY_API_KEY }} - uses: actions/checkout@v4 ``` #### **Depot** Use a Depot runner label in `runs-on` and add Harden-Runner as the first step. ```yaml jobs: build: runs-on: depot-ubuntu-24.04 steps: - uses: step-security/harden-runner@v2.19.0 with: use-policy-store: true api-key: ${{ secrets.STEP_SECURITY_API_KEY }} - uses: actions/checkout@v4 ``` #### **Namespace** Use a Namespace profile label in `runs-on` and add Harden-Runner as the first step: ```yaml jobs: build: runs-on: namespace-profile-default steps: - uses: step-security/harden-runner@v2.19.0 with: use-policy-store: true api-key: ${{ secrets.STEP_SECURITY_API_KEY }} - uses: actions/checkout@v4 # ... rest of your job ``` #### **Warp** Use a Warp runner label in `runs-on` and add Harden-Runner as the first step: ```yaml jobs: build: runs-on: warp-ubuntu-latest-x64-4x steps: - uses: step-security/harden-runner@v2.19.0 with: use-policy-store: true api-key: ${{ secrets.STEP_SECURITY_API_KEY }} - uses: actions/checkout@v4 # ... rest of your job ``` #### **What works the same as GitHub-hosted runners** All standard Harden-Runner features are available on these providers: * **Audit mode** (`egress-policy: audit`) — logs outbound traffic without blocking * **Block mode** (`egress-policy: block`) with `allowed-endpoints` * **Policy Store** integration (`use-policy-store: true` with an `api-key`) — centrally manage egress policies without modifying each workflow * **Security insights link** in the job log and the Markdown job summary * All detections surface in the StepSecurity dashboard the same way as for GitHub-hosted runners ## 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**](#buildlog) * [**Workflow Runs**](#latest-workflow-runs) * [**Markdown Job Summary**](#markdown-job-summary) * [**GitHub Checks**](#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](https://app.stepsecurity.io/github/ossf/scorecard/actions/runs/2265028928)).
build log showing StepSecurity insights 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

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//actions/dashboard` **Step 2:** In the left-hand menu, under Harden-Runner, click Workflow Runs
StepSecurity sidebar displaying different sections.

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

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

StepSecurity Insights summary page

### Markdown Job Summary **Step 1:** Navigate to the workflow run page **Step 2:** Click "📄 View Full Report"
StepSecurity markdown report

StepSecurity markdown report

**Step 3:** Review the outbound connections allowed during the workflow execution.
StepSecurity Insights summary page

StepSecurity Insights summary page

### GitHub Checks To enable GitHub Checks, check out this [guide](/settings/github-checks.md#how-to-enable-the-github-checks-feature). **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

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

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

StepSecurity Insights summary page

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.stepsecurity.io/harden-runner.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.