Merge pull request #495 from AkhigbeEromo/Update-README

Update README for Improved Clarity and Usability
step-security · Jan 15, 2025 · 18f6947 · 18f6947
2 parents c95a14d + 81f844e
commit 18f6947
Show file tree

Hide file tree

Showing 6 changed files with 126 additions and 301 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
@@ -0,0 +1,21 @@
+## How Harden-Runner Works?
+
+### GitHub-Hosted Runners
+
+For GitHub-hosted runners, Harden-Runner GitHub Action downloads and installs the StepSecurity Agent.
+
+- The code to monitor file, process, and network activity is in the Agent.
+- The community tier agent is open-source and can be found [here](https://github.com/step-security/agent). The enterprise tier agent is closed-source. Both agents are written in Go.
+- 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)
+
+### Self-Hosted Actions Runner Controller (ARC) Runners
+
+- ARC Harden Runner daemonset uses eBPF
+- You can find more details in this [blog post](https://www.stepsecurity.io/blog/introducing-harden-runner-for-kubernetes-based-self-hosted-actions-runners)
+- ARC Harden Runner is NOT open source.
+
+### Self-Hosted VM Runners (e.g. on EC2)
+
+- For self-hosted VMs, you add the Harden-Runner agent into your runner image (e.g. AMI).
+- You can find more details in this [blog post](https://www.stepsecurity.io/blog/ci-cd-security-for-self-hosted-vm-runners)
+- Agent for self-hosted VMs is NOT open source.
diff --git a/docs/limitations.md b/docs/limitations.md
@@ -0,0 +1,14 @@
+## Limitations
+
+### GitHub-Hosted Runners
+
+* 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).
+* 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`. Note: This is not a limitation for Self-Hosted runners.
+
+### Self-Hosted Actions Runner Controller (ARC) Runners
+
+* Since ARC Harden Runner uses eBPF, only Linux jobs are supported. Windows and MacOS jobs are not supported.
+
+### Self-Hosted VM Runners (e.g. on EC2)
+
+* Only Ubuntu VM is supported. Windows and MacOS jobs are not supported.
diff --git a/images/network-events.png b/images/network-events.png
diff --git a/images/network-events1.png b/images/network-events1.png
diff --git a/images/recommended-policy1.png b/images/recommended-policy1.png