-## 3,000+ open source projects use Harden-Runner
+## 3,500+ open source projects use Harden-Runner
+
+Harden-Runner is trusted by leading open source projects and enterprises to secure their CI/CD pipelines.
+
+### Trusted by
+
| [](https://app.stepsecurity.io/github/cisagov/skeleton-generic/actions/runs/7588528684) | [](https://app.stepsecurity.io/github/microsoft/ebpf-for-windows/actions/runs/7587031851) | [](https://app.stepsecurity.io/github/GoogleCloudPlatform/functions-framework-ruby/actions/runs/7576989995) | [](https://app.stepsecurity.io/github/DataDog/stratus-red-team/actions/runs/7446169664) | [](https://app.stepsecurity.io/github/intel/cve-bin-tool/actions/runs/7590975903) | [](https://app.stepsecurity.io/github/kubernetes-sigs/cluster-api-provider-azure/actions/runs/7591172950) | [](https://app.stepsecurity.io/github/nodejs/node/actions/runs/7591405720) | [](https://app.stepsecurity.io/github/aws/aperf/actions/runs/7631366761) |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **CISA**
-## Hands-On Tutorials
+#### Hands-On Tutorials
You can use [GitHub Actions Goat](https://github.com/step-security/github-actions-goat) to try Harden-Runner. You only need a GitHub Account and a web browser.
@@ -81,7 +130,7 @@ Hands-on Tutorials for GitHub Actions Runtime Security:
1. [Filter Egress Network Traffic](https://github.com/step-security/github-actions-goat/blob/main/docs/Solutions/RestrictOutboundTraffic.md)
2. [Detect File Tampering](https://github.com/step-security/github-actions-goat/blob/main/docs/Solutions/MonitorSourceCode.md)
-## Support for Self-Hosted Runners and Private Repositories
+### Support for Self-Hosted Runners and Private Repositories
Hardening for self-hosted runners and GitHub-hosted runners used in private repositories is supported with a commercial license. Check out the [documentation](https://docs.stepsecurity.io/stepsecurity-platform/billing) for more details.
@@ -91,7 +140,7 @@ Hardening for self-hosted runners and GitHub-hosted runners used in private repo
Read this [case study on how Kapiche uses Harden-Runner](https://www.stepsecurity.io/case-studies/kapiche/) to improve software supply chain security in their private repositories.
-### Self-Hosted Actions Runner Controller (ARC) Runners
+#### Self-Hosted Actions Runner Controller (ARC) Runners
> Explore demo workflows using self-hosted ARC Runner and ARC Harden-Runner [here](https://docs.stepsecurity.io/harden-runner/how-tos/enable-runtime-security-arc).
@@ -99,21 +148,21 @@ Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates self-
- Instead of adding the Harden-Runner GitHub Action in each job, 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 do need to add the Harden-Runner GitHub Action to jobs where you want to enable `block` mode.
-- Please email support@stepsecurity.io for instructions on how to install the ARC-Harden-Runner daemonset on your Kubernetes cluster.
+- The instructions for installing the ARC-Harden-Runner daemonset are shown in the dashboard. To enable access to these instructions, please email support@stepsecurity.io.
-### Self-Hosted VM Runners (e.g. on EC2)
+#### Self-Hosted VM Runners (e.g. on EC2)
> Explore demo workflows using self-hosted VM Runners and Harden-Runner [here](https://docs.stepsecurity.io/harden-runner/how-tos/enable-runtime-security-vm).
- 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 packer or as a post-install step when using the https://github.com/philips-labs/terraform-aws-github-runner project to setup 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 do need to add the Harden-Runner GitHub Action to jobs where you want to enable `block` mode.
-- Please email support@stepsecurity.io for instructions on how to install the Harden-Runner agent on your self-hosted VM runners. This agent is different than the one used for GitHub-hosted runners.
+- The instructions for installing the Harden-Runner agent on your self-hosted VM runners are shown in the dashboard. To enable access to these instructions, please email support@stepsecurity.io. This agent is different than the one used for GitHub-hosted runners.
## Features at a glance
For details, check out the documentation at https://docs.stepsecurity.io
-### 📶 View outbound network traffic
+### View outbound network traffic
> Applies to both GitHub-hosted and self-hosted runners
@@ -123,21 +172,21 @@ Harden-Runner monitors all outbound traffic from each job at the DNS and network
- For self-hosted runners, no changes are needed to workflow files to monitor egress traffic
- A filtering (block) egress policy is suggested in the insights page based on the current and past job runs
-### 🌐 View outbound HTTPS traffic
+### View outbound HTTPS traffic
-> Applies to GitHub-hosted and self-hosted VM runners
+> Applies to GitHub-hosted and self-hosted VM runners
Harden-Runner can monitor outbound HTTPS requests. This feature is supported with a commercial license.
- HTTPS events are monitored using eBPF (no MITM proxy is used)
-- If a HTTP PUT/ POST/ PATCH call is made to `github.com` or `api.github.com` hosts to a HTTP Path with a different organization than where the workflow is running, the call is marked as anomalous
-- As of now, only HTTPS calls to `github.com` and `api.github.com` hosts are monitoried.
+- If a HTTP PUT/ POST/ PATCH call is made to GitHub APIs to a HTTP Path with a different organization than where the workflow is running, the call is marked as anomalous
+- As of now, only HTTPS calls to `github.com`, `api.github.com`, `*.pkg.github.com`, and `ghcr.io` hosts are monitoried.
-### 📋 View the name and path of every file written during the build process
+### View recommendation for minimum GITHUB_TOKEN permissions
+
+> Applies to GitHub-hosted runners
+
+Harden-Runner monitors outbound HTTPS requests using eBPF and uses the PATHs and VERBs of these HTTPS calls to recommend the minimum GITHUB_TOKEN permissions for each job in your workflow. This feature is supported with a commercial license.
+
+- GITHUB_TOKEN is an automatically generated secret used to authenticate to GitHub APIs from GitHub Actions workflows.
+- Harden-Runner can monitor the VERBs (e.g., `GET`, `POST`) and PATHs (e.g., `/repos/owner/repo/issues`) for calls made to the GitHub APIs from the runner.
+- Each GitHub Actions API call requires a corresponding GITHUB_TOKEN permission. For instance, a GET request to the `/repos/org/repo/info/refs?service=git-upload-pack` endpoint requires the `contents: read` permission.
+- The recommendation for the minimum GITHUB_TOKEN permissions are show in the `Recommendations` tab.
+
+
+ 
+
-### 🔄 View process names and arguments
+### View process names and arguments
> Applies to both GitHub-hosted and self-hosted runners
View process names, PIDs, and process arguments. This feature is supported with a commercial license.
- Harden-Runner tracks every process that is run during the build process.
-- Clicking on any file reveals a list of processes that wrote to it.
-- You can walk up the process tree and view process arguments to understand the build process and detect suspicious activity.
+- Clicking on any process ID (PID) in the network events, file events, or HTTPS events shows the process that caused the event, along with the process arguments.
+- You can walk up the process tree by clicking `View Parent Process` to understand the build process and detect suspicious activity.
-### 🚫 Run your job without sudo access
+### Run your job without sudo access
> Applies to GitHub-hosted runners
@@ -215,7 +278,7 @@ GitHub-hosted runner uses passwordless sudo for running jobs.
recommendation to disable sudo in the insights page
- When you set `disable-sudo` to `true`, the job steps run without sudo access to the GitHub-hosted Ubuntu VM
-### 🔔 Get security alerts
+### Get security alerts
> Applies to both GitHub-hosted and self-hosted runners
diff --git a/images/token-perms-recommendation.png b/images/token-perms-recommendation.png
new file mode 100644
index 0000000..fedf206
Binary files /dev/null and b/images/token-perms-recommendation.png differ