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
Follow this interactive demo to see a real detection:
Threats in a CI/CD Environment
Compromised workflows, dependencies, and build tools pose several major threats:
Exfiltration of CI/CD credentials and source code
Tampering of source code, dependencies, or artifacts during the build process to inject backdoors
Exploitation of third party GitHub Actions
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:
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
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 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.
Inspecting the Global Block List
The current contents of the Global Block List are available as a read-only JSON feed:
The endpoint is public, requires no authentication, and returns the live list of indicators currently enforced across every workflow protected by Harden-Runner. It is provided so security teams can audit what is being blocked on their behalf, integrate the list into their own threat-intelligence tooling, or confirm that a specific domain or IP is on the list.
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:
Follow this interactive demo to see how it works:
Platform Capability Matrix
Harden-Runner's capabilities vary by runner operating system. The matrix below shows which features are currently supported on Linux, macOS, and Windows.
GitHub-hosted runner support
✅
✅
✅
Self-hosted VM (ephemeral)
✅
✅
✅
Self-hosted VM (persistent)
✅
✅
✅
Network + DNS monitoring
✅
✅
✅
Process monitoring
✅
✅
✅
Correlation of events with the exact workflow step
✅
✅
✅
Job summaries in workflow logs
✅
✅
✅
Imposter commit detection
✅
✅
✅
Secrets and build-log detection
✅
✅
✅
Source code overwrite detection
✅
✅
❌
File write events (GitHub-Hosted)
✅
✅
❌
File write events (Self-Hosted, ephemeral)
✅
✅
❌
File write events (Self-Hosted, persistent)
❌
✅
❌
Custom VM image baking
✅
❌
✅
Non-intrusive HTTPS monitoring
✅
❌
❌
Suspicious process event detection
✅
❌
❌
Known C2 endpoint blocking
✅
✅
❌
Agent tampering detection
✅
❌
❌
Runner.Worker memory-dump detection (prevents secret exfiltration)
✅
❌
❌
Policy Store enforcement
✅
✅
✅
Block mode (GitHub-hosted, supported for Allow list)
✅
✅
✅
Block mode (Self-hosted, supported for Allow list)
✅
✅
✅
Block mode (GitHub-hosted, supported for Deny list)
✅
❌
❌
Block mode (Self-hosted, supported for Deny list)
✅
✅
✅
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.
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.
Data Collection and Hosting
Harden-Runner sends runtime telemetry from the runner to StepSecurity. This telemetry is what powers the security insights page, runtime detections, and notifications. This section covers what the agent sends, where that data is stored, and what it does not collect.
What the agent sends
The agent reports metadata about the job and about the runtime activity it observes on the runner.
Network and DNS events
Domain names resolved, IP addresses and ports contacted, the process that made each call, and a timestamp
HTTPS request metadata
Where non-intrusive HTTPS monitoring is supported: the request method, host, and path of outbound HTTPS calls
Process events
Process name and executable path, process arguments, process ID and parent process ID, and working directory
File write events
Name and path of each file written to the working directory, and the process that wrote it
Workflow and job metadata
Repository owner and name, repository visibility, workflow name and path, run and job IDs, branch, commit SHA and commit message, committer, trigger event, and the name, status, and start and end times of each step
Runner details
Runner name, machine name, runner group, runner labels, environment type (for example GitHub-hosted, self-hosted, or ARC), and for ARC deployments the cluster name
Harden-Runner configuration
The egress policy in effect for the job, and whether telemetry or file monitoring were disabled for that job
Every event is correlated with the workflow step that produced it. That correlation is what allows the insights page to attribute a network call or a process launch to a specific step rather than to the job as a whole.
Process events and file write events are available on the Enterprise Tier only. See Workflow Runs for the full list of features and their tier requirements.
Raw process and file event data is uploaded through the transient data endpoint listed under Harden-Runner Endpoints. All uploads are outbound only and encrypted over TLS.
For the exact shape of the data StepSecurity stores per workflow run, see the Insights Response example on the Sample Detection Events page.
Where the data is hosted
Harden-Runner telemetry is processed and stored in StepSecurity's own AWS environment. That environment runs in two AWS regions, both in the United States:
us-east-1 (N. Virginia)
us-west-2 (Oregon)
The StepSecurity console reads from the same environment, so the insights, detections, and reports you see in the app are served from these regions.
How the data flows
Three kinds of traffic cross the boundary between your environment and StepSecurity:
Runtime events, sent outbound from the Harden-Runner agent on the runner to the StepSecurity backend. This is the telemetry described above.
Console access, from your authorized users to the StepSecurity frontend, which in turn calls the backend API.
GitHub API calls, made by the StepSecurity backend to your GitHub organization, for example to post GitHub Checks, open pull requests, and read workflow run metadata. These calls are authorized by the StepSecurity GitHub App you install.
On the StepSecurity side, the platform runs entirely on managed AWS services within the two regions listed above:
Frontend app
AWS Amplify
Serves the StepSecurity console to authorized users
Backend API
Amazon API Gateway
Entry point for agent telemetry and console API calls
Backend
AWS Lambda
Processes runtime events, evaluates detections, and calls the GitHub API
Object storage
Amazon S3
Stores raw process and file event data and generated report artifacts
Structured storage
Amazon DynamoDB
Stores workflow run records, detections, policies, and organization configuration
All agent traffic is outbound only. The Harden-Runner agent never accepts inbound connections, and StepSecurity does not require any inbound network access into your runner environment.
StepSecurity is SOC 2 Type II and ISO/IEC 27001 compliant, and compliance and penetration test reports are available on request. See Enterprise Readiness for details.
If your organization needs telemetry or detection events in storage you control, for example to satisfy an internal retention or residency requirement, StepSecurity can export them to your own infrastructure through the S3 Integration or the Webhook Integration.
What the agent does not collect
The Harden-Runner agent collects only the metadata required for runtime visibility and enforcement. It does not send:
Source code or file contents. File write events record file names and paths, never the contents of those files.
Secret values. When StepSecurity detects a secret in a build log or a build artifact, the detection event records a masked preview and the location of the match, not the secret itself.
Environment variable values.
Turning telemetry off
On the Community Tier, workflows running in block mode can stop sending telemetry with the disable-telemetry input. This is not recommended on the Enterprise Tier, because detections and notifications depend on the telemetry. See Disable telemetry in block mode.
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.
Step 2: You will see a link to security insights and recommendations in the workflow logs and the job markdown summary.
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.
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.
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.
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
For jobs where you want to enable block mode, there are two options:
Attach a policy 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 Harden-Runner section in your dashboard.
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 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.
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:
Bitrise
Harden-Runner supports Bitrise Build Hub macOS runners for GitHub Actions. Bitrise runners are targeted using the labels you define when creating a Build Hub machine pool, so your runs-on value depends on your pool configuration. Use your pool's label in runs-on and add Harden-Runner as the first step:
Blacksmith
Use a Blacksmith runner label in runs-on and add Harden-Runner as the first step:
Depot
Use a Depot runner label in runs-on and add Harden-Runner as the first step.
Namespace
Use a Namespace profile label in runs-on and add Harden-Runner as the first step:
Warp
Use a Warp runner label in runs-on and add Harden-Runner as the first step:
AWS CodeBuild
Harden-Runner supports GitHub Actions runners hosted on AWS CodeBuild on EC2 compute. CodeBuild registers a just-in-time self-hosted runner for each queued job, so the job runs on your AWS compute, in your VPC, under your CodeBuild project's IAM service role.
CodeBuild project requirements
Unlike the other providers on this page, CodeBuild requires specific settings on the CodeBuild project itself. The agent relies on kernel-level features, so a project that does not meet these requirements will not be monitored.
Compute
EC2. Lambda compute is not supported.
Host kernel
kernel-6 (Amazon Linux 2023)
Privileged
Enabled
Provisioning model
On-demand or Reserved capacity. Both are supported.
Environment image
Managed image with Running mode set to Instance, or Custom image with Environment type set to Linux Container.
Workflow configuration
Target CodeBuild runners with the standard CodeBuild runner label and add Harden-Runner as the first step:
Replace my-project with the name of the CodeBuild project whose webhook is configured for WORKFLOW_JOB_QUEUED events. The project name must match the project name in the AWS console exactly.
No buildspec or webhook changes are needed. If you use CodeBuild label overrides to select an image, instance size, or fleet per job, those continue to apply, as long as the resulting environment still meets the requirements above.
Custom images
CodeBuild runners that run Linux containers on EC2 compute with a custom image are supported from Harden-Runner v2.21.0. Set Environment image to Custom image and Environment type to Linux Container. Images hosted in Amazon ECR and in external Docker registries are both supported. You can also select a custom image per job with the image:custom-<environment-type>-<custom-image-identifier> label override.
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 blockingBlock mode (
egress-policy: block) withallowed-endpointsPolicy Store integration (
use-policy-store: truewith anapi-key) — centrally manage egress policies without modifying each workflowSecurity 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
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).
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).
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
Step 3: After opening the Workflow Runs page, locate the workflow you want to inspect and click on it.
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.
Markdown Job Summary
Step 1: Navigate to the workflow run page
Step 2: Click "📄 View Full Report"
Step 3: Review the outbound connections allowed during the workflow execution.
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.
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.
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.
Last updated
Was this helpful?