├── LICENSE.txt └── README.md /LICENSE.txt: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Othneil Drew (For README.md template) 4 | Copyright (c) 2020 Deniz Onur Duzgun (For the content) 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in all 14 | copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 | SOFTWARE. 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![awesome-runners](https://img.shields.io/badge/listed%20on-awesome--runners-blue.svg)](https://github.com/jonico/awesome-runners) 2 | [![Contributors][contributors-shield]][contributors-url] 3 | [![Forks][forks-shield]][forks-url] 4 | [![Stargazers][stars-shield]][stars-url] 5 | [![Issues][issues-shield]][issues-url] 6 | [![MIT License][license-shield]][license-url] 7 | 8 | 9 |
10 |

11 | 12 | Logo 13 | 14 | 15 |

Github Self-Hosted Runners Configuration

16 | 17 |

18 | Guideline of best practices to follow to use Github Self-Hosted Runners in a secure way. 19 |
20 |
21 | Report an issue 22 |

23 |

24 | 25 | 26 | ## Table of contents 27 | 28 | 29 | * [About the project](#about-the-project) 30 | * [Confidentiality](#confidentiality) 31 | * [Using self-hosted runners only in trusted GitHub Actions](#using-self-hosted-runners-only-in-trusted-github-actions) 32 | * [Limit access to self-hosted runners](#limit-access-to-self-hosted-runners) 33 | * [Disable forks](#disable-forks) 34 | * [Enabling branch protections](#enabling-branch-protections) 35 | * [Do not store secrets in the host runner](#do-not-store-secrets-in-the-host-runner) 36 | * [Run the self-hosted runner on hardened hosts only](#run-the-self-hosted-runner-on-hardened-hosts-only) 37 | * [Integrity](#integrity) 38 | * [Use the latest and greatest runner](#use-the-latest-and-greatest-runner) 39 | * [Availability](#availability) 40 | * [High availability](#high-availability) 41 | * [Automatically clear and remove workspaces](#automatically-clear-and-remove-workspaces) 42 | * [Authentication](#authentication) 43 | * [Secure the authentication token of the self-hosted runner](#secure-the-authentication-token-of-the-self-hosted-runner) 44 | * [Authorization](#authorization) 45 | * [Only use the technologies you need](#only-use-the-technologies-you-need) 46 | * [Audit](#audit) 47 | * [Checklist](#checklist) 48 | * [Support section](#support-section) 49 | * [Contributing](#contributing) 50 | * [License](#license) 51 | * [Contact](#contact) 52 | 53 | 54 | 55 | ## About the project 56 | Looking for a guideline to configure your GitHub Self-Hosted Runners in a secure way? 57 | 58 | Here is a :fire: list of things to do! 59 | 60 | 61 | ## Confidentiality 62 | ##### Using self-hosted runners only in trusted GitHub Actions 63 | Self-hosted runners are using the dedicated host as the runner. 64 | Only verified GitHub Actions must use self-hosted runners to reduce the use of a potential malicious open-source GitHub Action that might access our private network. 65 | 66 | ##### Limit access to self-hosted runners 67 | Restrict the use of self-hosted runners to specific repositories only. 68 | https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups 69 | 70 | ##### Disable forks 71 | Disable forks since forks of your public repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow. 72 | 73 | ##### Enabling branch protections 74 | Obviously, we don't want anyone to add changes to a GitHub Action. A great way to have more control over your GitHub Actions is to create branch protection on your repositories. Having a mandatory approver to a PR will reduce the chances of someone trying to force push code changed. 75 | 76 | ##### Do not store secrets in the host runner 77 | When a GitHub Action uses the self-hosted runner, it clones the code in a workdir `_work`. 78 | We must ensure that no secrets (application, system, ..) are accessible in this folder. 79 | 80 | ##### Run the self-hosted runner on hardened hosts only 81 | The host of the self-hosted runner must be a hardened OS. 82 | Hardening of the OS is the act of configuring an OS securely, updating it, creating rules and policies to help govern the system in a secure manner, and removing unnecessary applications and services. This is done to minimize a computer OS's exposure to threats and to mitigate possible risk. 83 | https://www.cisecurity.org/cis-benchmarks/ 84 | 85 | 86 | ## Integrity 87 | ##### Use the latest and greatest runner 88 | Ensure that the host machine always uses the latest version of the self-hosted runner. 89 | https://github.com/actions/runner/releases/latest 90 | 91 | ![image](https://user-images.githubusercontent.com/59659739/100800872-2ffc4c80-33f5-11eb-8ed5-95b3a91d863a.png) 92 | 93 | > [!TIP] 94 | > If it works with your GitHub Actions workflows, consider using a [rootless dind action runner](https://github.com/actions-runner-controller/actions-runner-controller/pkgs/container/actions-runner-controller%2Factions-runner-dind-rootless) provided by GitHub as a base self-hosted runner image. 95 | 96 | 97 | ## Availability 98 | ##### High availability 99 | Since self-hosted runners are essential to talk with the internal network of an enterprise, they need to be highly available. 100 | https://github.com/philips-labs/terraform-aws-github-runner 101 | 102 | ##### Automatically clear and remove workspaces 103 | Since the self-hosted runner clones the source code in a workspace, we need to ensure that this workspace doesn't get overpopulated and consumes all the available space of the host. 104 | 105 | 106 | ## Authentication 107 | ##### Secure the authentication token of the self-hosted runner 108 | The authentication token used to configure the runner needs to be secured and restricted since it has write-access permissions on the repository. 109 | Using Hashicorp Vault may be a good solution for this. 110 | 111 | 112 | ## Authorization 113 | ##### Only use the technologies you need 114 | Keep the self-hosted runner simple and authorize only the things you need. For example, if you don't need npm don't install it inside the runner. 115 | 116 | 117 | ## Audit 118 | https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#auditing-github-actions-events 119 | 120 | 121 | ## Checklist 122 | - [ ] Using self-hosted runners only in trusted GitHub Actions 123 | - [ ] Limit access to self-hosted runners 124 | - [ ] Disable forks 125 | - [ ] Enabling branch protections 126 | - [ ] Run the self-hosted runner on hardened hosts only 127 | - [ ] Use the latest and greatest runner 128 | - [ ] High Availability 129 | - [ ] Automatically clear and remove workspaces 130 | - [ ] Secure the authentication token of the self-hosted runner 131 | - [ ] Only use the technologies you need 132 | 133 | 134 | ## Support section 135 | [Github Enterprise Support](https://enterprise.github.com/support) offers very usefull assistance on everything you search. :+1: 136 | 137 | * [Documentations](https://help.github.com/en) 138 | * [Request creation](https://enterprise.githubsupport.com/hc/en-us/requests/new) 139 | 140 | Also, GitHub offers a [Premium Support](https://help.github.com/en/github/working-with-github-support/about-github-premium-support-for-github-enterprise-cloud) with a 24/7 hours of operation availability time. 141 | 142 | 143 | ## Contributing 144 | Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**. 145 | 146 | 1. Fork the Project 147 | 2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`) 148 | 3. Commit your Changes (`git add . && git commit -m 'Add some AmazingFeature'`) 149 | 4. Push to the Branch (`git push origin feature/AmazingFeature`) 150 | 5. Open a Pull Request 151 | 152 | 153 | ## License 154 | Distributed under the MIT License. See `LICENSE.txt` for more information. 155 | 156 | 157 | ## Contact 158 | [Deniz Onur Duzgun](https://github.com/dduzgun-security) 159 | [Maxime Georjon](https://github.com/mxge) 160 | [Khalid Nazmus Sakib](https://github.com/knsakibnbc) 161 | 162 | 163 | 164 | [contributors-shield]: https://img.shields.io/github/contributors/dduzgun-security/github-self-hosted-runners.svg?style=flat-square 165 | [contributors-url]: https://github.com/dduzgun-security/github-self-hosted-runners/graphs/contributors 166 | [forks-shield]: https://img.shields.io/github/forks/dduzgun-security/github-self-hosted-runners?style=flat-square 167 | [forks-url]: https://github.com/dduzgun-security/github-self-hosted-runners/network/members 168 | [stars-shield]: https://img.shields.io/github/stars/dduzgun-security/github-self-hosted-runners.svg?style=flat-square 169 | [stars-url]: https://github.com/dduzgun-security/github-self-hosted-runners/stargazers 170 | [issues-shield]: https://img.shields.io/github/issues/dduzgun-security/github-self-hosted-runners.svg?style=flat-square 171 | [issues-url]: https://github.com/dduzgun-security/github-self-hosted-runners/issues 172 | [license-shield]: https://img.shields.io/github/license/dduzgun-security/github-self-hosted-runners.svg?style=flat-square 173 | [license-url]: https://github.com/dduzgun-security/github-self-hosted-runners/blob/master/LICENSE.txt 174 | --------------------------------------------------------------------------------