-
Notifications
You must be signed in to change notification settings - Fork 50
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #372 from step-security/readme-update
Readme update
- Loading branch information
Showing
5 changed files
with
40 additions
and
31 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -13,9 +13,9 @@ | |
|
|
||
| </div> | ||
|
|
||
| ## GitHub Actions Runtime Security | ||
| ## Harden Github-hosted and self-hosted runners | ||
|
|
||
| Harden-Runner provides runtime security for GitHub-hosted and self-hosted environments. | ||
| Harden-Runner provides network egress filtering and runtime security for GitHub-hosted and self-hosted runners. | ||
|
|
||
| For self-hosted environments, Harden-Runner supports: | ||
|
|
||
|
|
@@ -26,9 +26,9 @@ For self-hosted environments, Harden-Runner supports: | |
|
|
||
| ## Explore open source projects using Harden-Runner | ||
|
|
||
| | [](https://app.stepsecurity.io/github/cisagov/skeleton-generic/actions/runs/6199340224) | [](https://app.stepsecurity.io/github/microsoft/ebpf-for-windows/actions/runs/5559160177) | [](https://app.stepsecurity.io/github/GoogleCloudPlatform/functions-framework-ruby/actions/runs/5546354505) | [](https://app.stepsecurity.io/github/DataDog/stratus-red-team/actions/runs/5387101451) | [](https://app.stepsecurity.io/github/intel/cve-bin-tool/actions/runs/5579910614) | [](https://app.stepsecurity.io/github/kubernetes-sigs/cluster-api-provider-azure/actions/runs/5581511101) | [](https://app.stepsecurity.io/github/nodejs/node/actions/runs/5563468674) | [](https://app.stepsecurity.io/github/Mastercard/flow/actions/runs/5542112873) | | ||
| | [](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/Mastercard/flow/actions/runs/7539664931) | | ||
| | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | **CISA**<br>[Explore](https://app.stepsecurity.io/github/cisagov/skeleton-generic/actions/runs/6199340224) | **Microsoft**<br>[Explore](https://app.stepsecurity.io/github/microsoft/ebpf-for-windows/actions/runs/5559160177) | **Google**<br>[Explore](https://app.stepsecurity.io/github/GoogleCloudPlatform/functions-framework-ruby/actions/runs/5546354505) | **DataDog**<br>[Explore](https://app.stepsecurity.io/github/DataDog/stratus-red-team/actions/runs/5387101451) | **Intel**<br>[Explore](https://app.stepsecurity.io/github/intel/cve-bin-tool/actions/runs/5579910614) | **Kubernetes**<br>[Explore](https://app.stepsecurity.io/github/kubernetes-sigs/cluster-api-provider-azure/actions/runs/5581511101) | **Node.js**<br>[Explore](https://app.stepsecurity.io/github/nodejs/node/actions/runs/5563468674) | **Mastercard**<br>[Explore](https://app.stepsecurity.io/github/Mastercard/flow/actions/runs/5542112873) | | ||
| | **CISA**<br>[Explore](https://app.stepsecurity.io/github/cisagov/skeleton-generic/actions/runs/7588528684) | **Microsoft**<br>[Explore](https://app.stepsecurity.io/github/microsoft/ebpf-for-windows/actions/runs/7587031851) | **Google**<br>[Explore](https://app.stepsecurity.io/github/GoogleCloudPlatform/functions-framework-ruby/actions/runs/7576989995) | **DataDog**<br>[Explore](https://app.stepsecurity.io/github/DataDog/stratus-red-team/actions/runs/7446169664) | **Intel**<br>[Explore](https://app.stepsecurity.io/github/intel/cve-bin-tool/actions/runs/7590975903) | **Kubernetes**<br>[Explore](https://app.stepsecurity.io/github/kubernetes-sigs/cluster-api-provider-azure/actions/runs/7591172950) | **Node.js**<br>[Explore](https://app.stepsecurity.io/github/nodejs/node/actions/runs/7591405720) | **Mastercard**<br>[Explore](https://app.stepsecurity.io/github/Mastercard/flow/actions/runs/7539664931) | | ||
|
|
||
| ## Hands-On Tutorials | ||
|
|
||
|
|
@@ -47,8 +47,8 @@ Harden-Runner monitors process, file, and network activity to: | |
|
|
||
| | | Countermeasure | Prevent Security Breach | | ||
| | --- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | 1. | Block egress traffic at the DNS (Layer 7) and network layers (Layers 3 and 4) to prevent exfiltration of code and CI/CD credentials | To prevent [Codecov breach](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/ExfiltratingCICDSecrets.md) scenario | | ||
| | 2. | Detect if source code is being tampered during the build process to inject a backdoor | To detect [SolarWinds incident](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/TamperingDuringBuild.md) scenario | | ||
| | 1. | Detect anomalous traffic and block egress traffic at the DNS (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) scenario | | ||
| | 2. | Detect if source code is being tampered during the build process to inject a backdoor | To detect the [SolarWinds incident](https://github.com/step-security/github-actions-goat/blob/main/docs/Vulnerabilities/TamperingDuringBuild.md) scenario | | ||
| | 3. | Detect poisoned workflows and compromised dependencies | 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) | | ||
|
|
||
| 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. | ||
|
|
@@ -57,7 +57,7 @@ Read this [case study](https://infosecwriteups.com/detecting-malware-packages-in | |
|
|
||
| ### GitHub-Hosted Runners | ||
|
|
||
| 1. Add `step-security/harden-runner` GitHub Action to your GitHub Actions workflow file as the first step in each job. | ||
| 1. Add the `step-security/harden-runner` GitHub Action to your GitHub Actions workflow file as the first step in each job. | ||
|
|
||
| ```yaml | ||
| steps: | ||
|
|
@@ -72,61 +72,70 @@ Read this [case study](https://infosecwriteups.com/detecting-malware-packages-in | |
| <img src="images/buildlog1.png" alt="Link in build log" > | ||
| </p> | ||
| 3. Click on the link ([example link](https://app.stepsecurity.io/github/microsoft/msquic/actions/runs/5577342236)). You will see a process monitor view of network and file events correlated with each step of the job. | ||
| 3. Click on the link ([example link](https://app.stepsecurity.io/github/microsoft/msquic/actions/runs/7588119198)). You will see a process monitor view of network and file events correlated with each step of the job. | ||
| <p align="left"> | ||
| <img src="images/insights-5.png" alt="Insights from harden-runner" > | ||
| <img src="images/insights.png" alt="Insights from harden-runner" > | ||
| </p> | ||
| 4. Under the insights section, you'll find a Recommended Policy. You can either update your workflow file with this Policy, or alternatively, use the [Policy Store](https://docs.stepsecurity.io/harden-runner/how-tos/block-egress-traffic#2-add-the-policy-using-the-policy-store) to apply the policy without modifying the workflow file. | ||
| 4. Under the process monitor view, 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 alternatively, use the [Policy Store](https://docs.stepsecurity.io/harden-runner/how-tos/block-egress-traffic#2-add-the-policy-using-the-policy-store) to apply the policy without modifying the workflow file. From now on, any outbound calls not in the allowed list will be blocked. | ||
| <p align="left"> | ||
| <img src="images/rec-policy1.png" alt="Policy recommended by harden-runner" > | ||
| <img src="images/rec-policy.png" alt="Policy recommended by harden-runner" > | ||
| </p> | ||
| ### Self-Hosted Actions Runner Controller (ARC) Runners | ||
| ## Support for Self-Hosted Runners and Private Repositories | ||
| > 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). | ||
| 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. | ||
| Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates and scales self-hosted runners for GitHub Actions. | ||
| - To use Harden-Runner in a `Private` repository, you must install the [StepSecurity Actions Security GitHub App](https://github.com/apps/stepsecurity-actions-security). | ||
| - This is needed to access the GitHub Actions API and to authenticate users to access the insights URL for private repositories. | ||
| - If you use Harden-Runner GitHub Action in a private repository, the generated insights URL is NOT public. Only those who have access to the repository can view it. | ||
|
|
||
| - Instead of adding the Harden-Runner GitHub Action in each workflow, you'll need to install the ARC Harden-Runner daemonset on your Kubernetes cluster. | ||
| - Upon installation, the ARC Harden-Runner daemonset constantly monitors each workflow run; 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 for `block` mode. | ||
| - You can access security insights and runtime detections under the `Runtime Security` tab in your dashboard. | ||
| 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 VM Runners (e.g. on EC2) | ||
| ### Self-Hosted Actions Runner Controller (ARC) Runners | ||
|
|
||
| > Explore demo workflows using self-hosted VM Runners and Harden-Runner [here](https://docs.stepsecurity.io/harden-runner/how-tos/enable-runtime-security-vm). | ||
| > 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). | ||
|
|
||
| - Instead of adding the Harden-Runner GitHub Action in each workflow, you'll need to install the Harden-Runner agent on your runner image (e.g. AMI). This is typically done using packer. | ||
| - The Harden-Runner agent monitors each job 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 for `block` mode. | ||
| - You can access security insights and runtime detections under the `Runtime Security` tab in your dashboard. | ||
| Actions Runner Controller (ARC) is a Kubernetes operator that orchestrates self-hosted runners for GitHub Actions. | ||
|
|
||
| ## Support for Self-Hosted Runners and Private Repositories | ||
| - 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 [email protected] for instructions on how to install the ARC-Harden-Runner daemonset on your Kubernetes cluster. | ||
|
|
||
| Runtime security for self-hosted runners and private repositories are supported with a commercial license. Check out the [documentation](https://docs.stepsecurity.io/stepsecurity-platform/billing) for more details. | ||
| ### Self-Hosted VM Runners (e.g. on EC2) | ||
|
|
||
| - Install the [StepSecurity Actions Security GitHub App](https://github.com/apps/stepsecurity-actions-security) 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. | ||
| - You need to authenticate first to access insights URL for private repository. Only those who have access to the repository can view it. | ||
| > Explore demo workflows using self-hosted VM Runners and Harden-Runner [here](https://docs.stepsecurity.io/harden-runner/how-tos/enable-runtime-security-vm). | ||
|
|
||
| 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. | ||
| - 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 [email protected] 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. | ||
|
|
||
| ## Features at a glance | ||
|
|
||
| For details, check out the documentation at https://docs.stepsecurity.io | ||
|
|
||
| ### 👀 Monitor egress traffic | ||
| ### 👀 View outbound network traffic | ||
|
|
||
| > Applies to both GitHub-hosted and self-hosted runners | ||
|
|
||
| Harden-Runner monitors all outbound traffic from each job at the DNS and network layers | ||
|
|
||
| - After the workflow completes, each outbound call is correlated with each step of the job, and shown in the insights page | ||
| - 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 past job runs | ||
| - A filtering (block) egress policy is suggested in the insights page based on the current and past job runs | ||
|
|
||
| ### ⚠️ Detect anomalous outbound network traffic | ||
|
|
||
| > Applies to both GitHub-hosted and self-hosted runners | ||
|
|
||
| Harden-Runner creates a baseline of outbound traffic for each job during the first few runs that it monitors | ||
|
|
||
| - After the baseline is created, any new outbound destinations are marked as anomalous in the insights page | ||
| - You can view the list of all anomalous outbound network traffic in the `Runtime detections` page on the dashboard | ||
|
|
||
| ### 🚦 Filter egress traffic to allowed endpoints | ||
| ### 🚦 Filter outbound network traffic to allowed endpoints | ||
|
|
||
| > Applies to both GitHub-hosted and self-hosted runners | ||
|
|
||
|
|
||
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.