Skip to content

About

Harden-Runner is a CI/CD security agent that works like an EDR for GitHub Actions runners. It monitors network, file, and process activity and integrates with Secure Registry to apply package cooldowns and block known compromised packages.

Topics

Resources

Security policy

Stars

1.3k stars

Watchers

13 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Dark Banner

Maintained by stepsecurity.io OpenSSF Scorecard License: Apache 2.0

Harden-Runner

Corporate laptops and production servers typically have robust security monitoring in place to reduce risk and meet compliance requirements. However, CI/CD runners, which handle sensitive information like secrets for cloud environments and create production builds, often lack such security measures. This oversight has led to significant supply chain attacks, including the SolarWinds and Codecov breaches.

Traditional security monitoring and EDR solutions are ineffective for CI/CD runners due to their ephemeral nature. These tools also lack the necessary context to correlate events with specific workflow runs in a CI/CD environment.

StepSecurity Harden-Runner addresses this gap by providing security monitoring tailored for CI/CD runners, with support for Linux, Windows, and macOS runners. This approach brings CI/CD runners under the same level of security scrutiny as other critical systems, addressing a significant gap in the software supply chain.

CI/CD workflows also download dependencies that can introduce malicious code into builds. Applying security policies before those packages are downloaded adds another layer of protection. Harden-Runner integrates with StepSecurity Secure Registry, a hosted SaaS registry, to apply a cooldown to newly published package versions and block known compromised packages. Harden-Runner automatically configures supported package managers to use the registry and provides visibility into package requests through its Insights page, making these protections easier to adopt and verify.

Harden-Runner: Security Incidents Detected

See It in Action

Harden-Runner secures over 25 million CI/CD workflow runs every week, protecting thousands of pipelines, including those from popular open-source projects by Microsoft, Google, and CISA. See how top projects are using Harden-Runner and explore the insights: ➡ïļ Who's using Harden-Runner?

Quick Links


Introduction

Learn how Harden-Runner works through the video below, which shows how it detected the tj-actions/changed-files compromise. View the interactive demo here.

Harden-Runner detected the tj-actions/changed-files Breach

Getting Started

This guide walks you through the steps to set up and use Harden-Runner in your CI/CD workflows. For more details, refer to the official documentation.

Note

The Community tier is free for public repositories on GitHub-hosted runners and includes the core feature set. Advanced features, private repositories, and self-hosted runners (including ARC) require the Enterprise tier. See Features and Pricing Tiers for what is in each tier.

Step 1: Add Harden-Runner to Your Workflow

To integrate Harden-Runner, follow these steps:

  • Open your GitHub Actions workflow file (e.g., .github/workflows/<workflow-name>.yml).
  • Add the following code as the first step in each job:
    steps:
      - name: Harden Runner
        uses: step-security/harden-runner@05e31511f85b41b11d1cf0ef85d0992719546e2c # v2.21.0
        with:
          egress-policy: audit

Want to protect package downloads too? Enable Secure Registry with secure-registry: true to apply a cooldown to new releases and block known compromised packages. It is free for public repositories using GitHub-hosted runners with Harden-Runner.

Tip: Automate this step by pasting your workflow into the StepSecurity online tool

Click to view the full Getting Started Guide

Step 2: Access Security Insights

Run your workflow. Once completed:

  • Review the workflow logs and the job markdown summary.
  • Look for a link to security insights and recommendations.

    Link in workflow log

  • Click on the provided link (e.g., example link) to access the Process Monitor View, which displays:
    • Network events: Outbound network calls correlated with each step.
    • File events: File writes tracked during the job.

      Link in network events

If you enabled Secure Registry, open the Packages tab to review this job's package requests, allowed or blocked outcomes, and policy block reasons.


Secure Registry

Protect package downloads with StepSecurity Secure Registry, integrated with the Harden-Runner GitHub Action. The community tier is free for public repositories using GitHub-hosted runners with Harden-Runner. Private repositories and self-hosted runners require the Enterprise tier, including self-hosted runners used by public repositories.

StepSecurity hosts and operates the registry. There is no registry infrastructure to deploy or manage.

Enable package protection

The setup below enables the Secure Registry community tier. Enterprise integration through secure-registry: true is not yet available.

Add secure-registry: true to your Harden-Runner step and keep it first in the job:

steps:
  - name: Harden Runner
    uses: step-security/harden-runner@v2
    with:
      egress-policy: audit
      secure-registry: true

  # Continue with your existing checkout, setup, and install steps.

Harden-Runner automatically configures supported package managers to use Secure Registry. For a standard npm workflow, keep your existing npm install or npm ci command.

The community tier initially supports the JavaScript ecosystem, including npm, pnpm, and Bun. See the Community tier documentation for setup and supported ecosystems.

With secure-registry: true, the default package policy provides:

  • Two-day cooldown: Holds newly published package versions during the waiting period.
  • Compromised-package blocking: Blocks known compromised versions, including versions older than the cooldown period.
  • Package visibility: Shows package requests and policy outcomes for each job in Harden-Runner Insights.

The registry enforces these package protections even when egress-policy: audit is selected. That setting controls network monitoring separately from registry package policies.

Verify the results

After your workflow finishes, follow the Harden-Runner Insights link in the job summary and open the Packages tab. Select the job to review allowed and blocked requests, including the reason for each policy block. Use Network Events to inspect the registry domains contacted by the job.

Explore an example workflow run and its package records:

  • is-number@7.0.0: metadata lookup and archive download allowed.
  • typescript@7.1.0-dev.20261115.1: archive download blocked by the two-day cooldown.
  • chalk@5.6.1: archive download blocked as a known compromised package.

The test job succeeds because it checks for the expected blocks. The blocked packages are not installed. These two tests request archive URLs directly; they do not demonstrate metadata version filtering or installation from an existing lockfile.

For policy configuration and setup details, see the Community tier documentation.


Why Choose Harden-Runner?

  • Prevent Exfiltration: Prevent the exfiltration of CI/CD secrets and source code.
  • Detect Tampering: Identify source code modifications during builds.
  • Anomaly Detection: Spot unusual dependencies and workflow behaviors.
  • Simplify Permissions: Determine the minimum required GITHUB_TOKEN permissions.
  • Protect Package Downloads: Use Secure Registry to hold newly published versions during a cooldown, block known compromised packages, and inspect package requests in Harden-Runner Insights.

Features and Pricing Tiers

Harden-Runner offers a comprehensive suite of features to enhance the security of your CI/CD workflows, available in two tiers: Community (free) and Enterprise (paid). Two things determine what you get: where your workflows run decides whether the free tier is available at all, and your tier decides which features you get. The feature lists below show what is in each tier.

Where your workflows run What's available
Public repositories on GitHub-hosted runners Community features free; Enterprise features require a paid plan
Private repositories (any runner type) Enterprise (paid) only
Self-hosted runners, including ARC and bare metal (public or private repositories) Enterprise (paid) only

Important

Self-hosted runners require an Enterprise subscription, even for public repositories. Without a subscription, the Harden-Runner action is a no-op on self-hosted runners: the step succeeds and your workflow passes, but nothing is monitored and no insights are generated. To enable Harden-Runner on your self-hosted runners, start a free trial.

Community (Free)

Available for public repositories running on GitHub-hosted runners:

  • CI/CD-Aware Event Correlation: Each outbound network connection, file operation, and process execution is mapped to the exact step, job, and workflow where it occurs.
  • Automated Baseline Creation: Harden-Runner builds a baseline for each job based on past outbound network connections.
  • Anomaly Detection: Once the baseline is created, any future outbound calls not in the baseline trigger a detection.
  • Block Network Egress Traffic with Domain Allowlist: Optionally use the automatically created baseline to control outbound network traffic by specifying allowed domains, preventing unauthorized data exfiltration.
  • Global Block List: Block known-malicious domains and IP addresses tied to active supply chain attacks, maintained by StepSecurity's 24x7 SOC. No configuration required, new indicators apply automatically without an action version bump, and it is enforced even in egress-policy: audit mode.
  • Secure Registry: Opt in with secure-registry: true to automatically configure supported package managers, apply a default two-day cooldown, and block known compromised packages. Review package requests and block reasons in Harden-Runner Insights. Get started.
  • Detect Modification of Source Code: Monitor and alert on unauthorized changes to your source code during the CI/CD pipeline.

Enterprise (Paid)

Includes all features in the Community tier, plus:

  • Support for Private Repositories: Extend Harden-Runner's security capabilities to your private GitHub repositories.
  • Support for Self-Hosted Runners: Apply security controls and monitoring to self-hosted GitHub Actions runners (VM, bare metal, and ARC), for both public and private repositories.
  • GitHub Checks Integration: Enable GitHub Checks for Harden-Runner. If the baseline remains unchanged, the check passes; if it changes, the check fails, showing new outbound connections.
  • View Outbound GitHub API calls at the Job Level: Monitor HTTPS requests to GitHub APIs
  • Determine Minimum GITHUB_TOKEN Permissions: Monitor outbound HTTPS requests to GitHub APIs to recommend the least-privilege permissions needed for your workflows, enhancing security by reducing unnecessary access.
  • View the Name and Path of Every File Written During the Build Process: Gain visibility into every file written to the build environment, including the ability to correlate file writes with processes, ensuring complete transparency.
  • View Process Names and Arguments: Monitor every process executed during the build process, along with its arguments, and navigate the process tree to detect suspicious activities.
  • Centralized Policy Store: Manage egress policies centrally from the StepSecurity dashboard instead of editing each workflow file. Learn more in the Policy Store documentation.
  • Baselines at Repository, Organization, and Cluster Level: Create and manage baselines beyond the per-job level. Learn more in the Baseline documentation.
  • Suppression Rules: Suppress expected detections to reduce alert noise. Learn more in the Suppression Rules documentation.
  • Alert Notifications and SIEM Integration: Receive alerts via email, Slack, and Microsoft Teams, and integrate detections with your SIEM solution.

For a detailed comparison and more information, please visit our Pricing Page.

Explore the full feature set in the Features Documentation.


StepSecurity Maintained Actions

Many popular third-party GitHub Actions are abandoned or stuck on outdated runtimes. StepSecurity publishes Maintained Actions: drop-in replacements that are actively maintained, security-reviewed, and kept current, including updates to the Node 24 runtime.

  • Free for public repositories, no subscription required. Read the announcement.
  • ~500 actions and growing. Browse the full catalog.
  • Actively maintained: dependency updates, runtime upgrades (such as Node 24), and defined SLAs for patching vulnerabilities.
  • Hardened release process: manual secure code review before onboarding, signed commits, mandatory peer review, and tag protection.

Trusted By and Case Studies

Harden-Runner is trusted by over 11,000 leading open-source projects and enterprises, including Microsoft, Google, Kubernetes, and more.

Trusted by

CISA Microsoft Google DataDog Intel Kubernetes Node.js AWS
CISA
Explore
Microsoft
Explore
Google
Explore
DataDog
Explore
Intel
Explore
Kubernetes
Explore
Node.js
Explore
AWS
Explore

Enterprise Case Studies


Environment Compatibility Matrix

Harden-Runner is designed to work seamlessly across a variety of runner environments, providing consistent security insights and protections regardless of where your workflows execute. For self-hosted runners, audit mode is deployed directly to the runner infrastructure without requiring any changes to your existing workflows. For more details, refer to the official documentation.

Environment Type Compatibility Audit Mode Deployment Workflow Changes for Audit/Block Mode Free Community Tier
GitHub-hosted runners (Linux) ✅ Full support Add Harden-Runner Action to workflow Yes ✅ Public repos (Community features only)
GitHub-hosted runners (Windows, macOS) ✅ Audit mode only Add Harden-Runner Action to workflow Yes ✅ Public repos (Community features only)
Self-hosted VM runners ✅ Full support Include agent in runner image No ❌ Enterprise subscription required
Self-hosted bare-metal runners ✅ Full support Install agent as a service No ❌ Enterprise subscription required
Actions Runner Controller (ARC) ✅ Full support Deploy as DaemonSet No ❌ Enterprise subscription required
RunsOn Runners ✅ Full support Pre-integrated No ❌ Enterprise subscription required

Note

If you use GitHub Enterprise Server (GHES), set customer and server-name for TLS checks and policy fetching.

For an ephemeral Linux VM without the agent already installed, add this as the first job step, using the customer and server names registered with StepSecurity:

- uses: step-security/harden-runner@v2
  with:
    deploy-on-self-hosted-vm: true
    customer: your-stepsecurity-customer
    server-name: your-ghes-server
    egress-policy: audit

This requires a StepSecurity subscription with TLS inspection and self-hosted VM support enabled. The action uploads the job's events and prints agent logs during its post step.

How It Works

Want to know the technical details? Dive into the architecture of Harden-Runner and its integrations for GitHub-hosted and self-hosted runners in our How Harden-Runner Works Documentation.


Limitations

While Harden-Runner offers powerful features, there are certain limitations. See the complete list in Known Limitations.


Discussions

Join the conversation! For questions, ideas, or feedback, visit our Discussions Page.

For enterprise support, email support@stepsecurity.io. Interested in using Harden-Runner in other CI/CD platforms? Reach out to interest@stepsecurity.io.


License

Harden-Runner is open source. See the LICENSE file for details.

About

Harden-Runner is a CI/CD security agent that works like an EDR for GitHub Actions runners. It monitors network, file, and process activity and integrates with Secure Registry to apply package cooldowns and block known compromised packages.

Topics

Resources

Security policy

Stars

1.3k stars

Watchers

13 watching

Forks

Releases

Packages

Used by

Contributors

Languages