[![Maintained by stepsecurity.io](https://img.shields.io/badge/maintained%20by-stepsecurity.io-blueviolet)](https://stepsecurity.io/?utm_source=github&utm_medium=organic_oss&utm_campaign=harden-runner)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/step-security/harden-runner/badge)](https://api.securityscorecards.dev/projects/github.com/step-security/harden-runner)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://raw.githubusercontent.com/step-security/harden-runner/main/LICENSE)
+
+
---
Harden-Runner GitHub Action installs a security agent on the GitHub-hosted runner (Ubuntu VM) to
1. Prevent exfiltration of credentials
-2. Detect compromised dependencies and build tools
-3. Detect tampering of source code during build
+2. Detect tampering of source code during build
+3. Detect compromised dependencies and build tools
+
-
-
+
+
## Why
-Compromised dependencies and build tools typically make outbound calls to exfiltrate data or credentials, or may tamper source code, dependencies, or artifacts during the build.
+Compromised dependencies and build tools typically make outbound calls to exfiltrate credentials, or may tamper source code, dependencies, or artifacts during the build.
Harden-Runner GitHub Actions installs a daemon that monitors process, file, and network activity to:
| | Countermeasure | Threat |
| --- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1. | Block outbound calls that are not in the allowed list to prevent exfiltration of credentials | To prevent [Codecov breach](https://github.com/step-security/supply-chain-goat/blob/main/RestrictOutboundTraffic.md) scenario |
-| 2. | Detect if source code is being overwritten during the build process to inject a backdoor | To detect [SolarWinds incident scenario](https://github.com/step-security/supply-chain-goat/blob/main/MonitorSourceCode.md) |
-| 3. | Detect compromised dependencies that make unexpected outbound network calls | To detect [Dependency confusion](https://github.com/step-security/supply-chain-goat/blob/main/DNSExfiltration.md) and [Malicious dependencies](https://github.com/step-security/supply-chain-goat/blob/main/CompromisedDependency.md) |
+| 1. | Block outbound calls that are not in the allowed list to prevent exfiltration of credentials | To prevent [Codecov breach](https://github.com/step-security/attack-simulator/blob/main/docs/RestrictOutboundTraffic.md) scenario |
+| 2. | Detect if source code is being overwritten during the build process to inject a backdoor | To detect [SolarWinds incident scenario](https://github.com/step-security/attack-simulator/blob/main/docs/MonitorSourceCode.md) |
+| 3. | Detect compromised dependencies that make unexpected outbound network calls | To detect [Dependency confusion](https://github.com/step-security/attack-simulator/blob/main/docs/DNSExfiltration.md) and [Malicious dependencies](https://github.com/step-security/attack-simulator/blob/main/docs/CompromisedDependency.md) |
Read this [case study](https://infosecwriteups.com/detecting-malware-packages-in-github-actions-7b93a9985635) on how Harden-Runner detected malicious packages in the NPM registry.
@@ -46,30 +53,71 @@ Read this [case study](https://infosecwriteups.com/detecting-malware-packages-in
2. In the workflow logs, you will see a link to security insights and recommendations.
-
-
-
+
+
+
-3. Click on the link ([example link](https://app.stepsecurity.io/github/ossf/scorecard/actions/runs/2265028928)). You will see a process monitor view of what activities happened as part of each step.
+3. Click on the link ([example link](https://app.stepsecurity.io/github/ossf/scorecard/actions/runs/2265028928)). You will see a process monitor view of file and network activities correlated with each step of the job.
-
-
-
+
+
+
+
+4. Below the insights, you will see the recommended policy. Update your workflow file with the recommended policy.
+
+
+
+
-4. Below the insights, you will see the recommended policy. Add the recommended outbound endpoints to your workflow file, and only traffic to these endpoints will be allowed. When you use `egress-policy: block` mode, you can also set `disable-telemetry: true` to not send telemetry to the StepSecurity API.
+## Features at a glance
+
+For details, check out the documentation at https://docs.stepsecurity.io
+
+### Restrict egress traffic to allowed endpoints
+
+Once allowed endpoints are set in the workflow file,
+
+- Harden-Runner blocks egress traffic at the DNS (Layer 7) and network layers (Layers 3 and 4).
+- It blocks DNS exfiltration, where attacker tries to send data out using DNS resolution
+- Blocks outbound traffic using IP tables
-
+
-5. If outbound network call is made to an endpoint not in the allowed list or if source code is tampered, you will see an annotation in the workflow run.
+### Detect tampering of source code during build
+
+Harden-Runner monitors file writes and can detect if a file is overwritten.
+
+- Source code overwrite is not expected in a release build
+- All source code files are monitored, which means even changes to IaC files (Kubernetes manifest, Terraform) are detected
+- You can enable notifications to get one-time alert when source code is overwritten
-
+
+### Run your job without sudo access
+
+GitHub-hosted runner uses passwordless sudo for running jobs.
+
+- This means compromised build tools or dependencies can install attack tools
+- If your job does not need sudo access, you see a policy
+ recommendation to disable sudo in the insights page
+- When you set `disable-sudo` to `true`, the job steps run without sudo access to the Ubuntu VM
+
+### Get security alerts
+
+Install the [Harden Runner App](https://github.com/marketplace/harden-runner-app) to get security alerts.
+
+- Email and Slack notifications are supported
+- Notifications are sent when outbound traffic is blocked or source code is overwritten
+- Notifications are not repeated for the same alert for a given workflow
+
## Support for private repositories
+Private repositories are supported if they have a commercial license. Check out the [documentation](https://docs.stepsecurity.io/harden-runner/installation/business-enterprise-license) for more details.
+
Install the [Harden Runner App](https://github.com/marketplace/harden-runner-app) to use Harden-Runner GitHub Action for `Private` repositories.
- If you use Harden-Runner GitHub Action in a private repository, the generated insights URL is NOT public.
@@ -90,8 +138,7 @@ If you have questions or ideas, please use [discussions](https://github.com/step
1. Harden-Runner GitHub Action only works for GitHub-hosted runners. Self-hosted runners are not supported.
2. Only Ubuntu VM is supported. Windows and MacOS GitHub-hosted runners are not supported. There is a discussion about that [here](https://github.com/step-security/harden-runner/discussions/121).
-3. Detecting overwriting of source code only checks for a subset of file extensions right now. These files extensions are ".c", ".cpp", ".cs", ".go", ".java". We will be adding more extensions and options around detecting overwriting of source code in future releases.
-4. Harden-Runner is not supported when [job is run in a container](https://docs.github.com/en/actions/using-jobs/running-jobs-in-a-container) as it needs sudo access on the Ubuntu VM to run. It can be used to monitor jobs that use containers to run steps. The limitation is if the entire job is run in a container. That is not common for GitHub Actions workflows, as most of them run directly on `ubuntu-latest`.
+3. Harden-Runner is not supported when [job is run in a container](https://docs.github.com/en/actions/using-jobs/running-jobs-in-a-container) as it needs sudo access on the Ubuntu VM to run. It can be used to monitor jobs that use containers to run steps. The limitation is if the entire job is run in a container. That is not common for GitHub Actions workflows, as most of them run directly on `ubuntu-latest`.
## Testimonials
@@ -107,7 +154,7 @@ Some important workflows using harden-runner:
| |Repository |Link to insights|
|--|----------|----------------|
|1.|[nvm-sh/nvm](https://github.com/nvm-sh/nvm/blob/master/.github/workflows/lint.yml)|[Link to insights](https://app.stepsecurity.io/github/nvm-sh/nvm/actions/runs/1757959262)|
-|2.|[yannickcr/eslint-plugin-react](https://github.com/yannickcr/eslint-plugin-react/blob/master/.github/workflows/release.yml)|[Link to insights](https://app.stepsecurity.io/github/yannickcr/eslint-plugin-react/actions/runs/1930818585)
+|2.|[jsx-eslint/eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/.github/workflows/release.yml)|[Link to insights](https://app.stepsecurity.io/github/yannickcr/eslint-plugin-react/actions/runs/1930818585)
|3.|[microsoft/msquic](https://github.com/microsoft/msquic/blob/main/.github/workflows/docker-publish.yml)|[Link to insights](https://app.stepsecurity.io/github/microsoft/msquic/actions/runs/1759010243)
|4.|[ossf/scorecard](https://github.com/ossf/scorecard/blob/main/.github/workflows/codeql-analysis.yml)|[Link to insights](https://app.stepsecurity.io/github/ossf/scorecard/actions/runs/2006162141)
|5.|[Automattic/vip-go-mu-plugins](https://github.com/Automattic/vip-go-mu-plugins/blob/master/.github/workflows/e2e.yml)|[Link to insights](https://app.stepsecurity.io/github/Automattic/vip-go-mu-plugins/actions/runs/1758760957)
@@ -118,8 +165,4 @@ Harden-Runner GitHub Action downloads and installs the StepSecurity Agent.
- The code to monitor file, process, and network activity is in the Agent.
- The agent is written in Go and is open source at https://github.com/step-security/agent
-- The agent's build is reproducible. You can view the steps to reproduce the build [here](http://app.stepsecurity.io/github/step-security/agent/releases/latest).
-
-## 1-minute Demo Video
-
-https://user-images.githubusercontent.com/25015917/156026587-79356450-9b35-4254-9c2e-7f2cc8d81059.mp4
+- The agent's build is reproducible. You can view the steps to reproduce the build [here](http://app.stepsecurity.io/github/step-security/agent/releases/latest)
diff --git a/images/banner.png b/images/banner.png
index 34b21d3622a94af4ace3b0c9317d35858b1c7d14..c23e9dee77123cc260240447da3ed5ee569c69a0 100644
GIT binary patch
literal 28236
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