Documentation
Homepage for OTP Guard documentation.
🔐Github Security Best Practices
Frequently Asked Questions
What is OTP Guard? What does it do?
OTP Guard is a step-up authentication system for pull requests that adds a second factor - a "step-up" - to ensure that PRs are approved only by authorized users. OTP Guard interoperates seamlessly within the Github branch protection system, ensuring that unauthorized PRs cannot be merged.
What does OTP Guard protect against if a user is already required to be logged into Github?
OTP Guard is step-up authentication, meaning it requires a second factor at critical points in an organization's workflow - such as before merging a PR. Possessing Github session cookies alone does not imply that an authorized user is driving the action. For example, info-stealer malware can steal cookies, which would bypass any Github authentication check beyond the initial login.
Doesn't Github already have a 2FA requirement?
Github does have a 2FA requirement, but it does not protect pull requests. Pull requests are the gateway to your company's codebase, and effective security requires a belt-and-suspenders approach. Moreover, Github organization admins currently cannot require a physical, phishing-resistant second factor such as a Yubikey to be associated with Github team members.
Git already has commit signing. How does OTP Guard differ?
Git commit signing can be an important tool but OTP Guard covers different cases. Git commit signing is not always easy to set up, whereas getting started with OTP Guard takes only a few clicks. This makes OTP Guard suitable even for non-technical users such as content editors. OTP Guard also works well to ensure an authorized person-in-the-middle for automated PRs such as Dependabot, or open source projects where commit signatures would be impractical to enforce for all contributors.
What about Github web signatures for commits?
The signing keys for these web signatures are held by Github and depend only on the presence of a logged-in user. As such, they are no more secure than Github's existing log-in security mechanisms. Github log-in security is good, but it does not cover the same areas that OTP Guard does.
If a developer is compromised enough to have their Github cookies stolen, isn't it already game over?
Not with OTP Guard. A second factor, especially a physical one such as a Yubikey, can be used to authorize PRs and stop attackers in their tracks. They would not be able to approve and merge nefarious code without also accessing an OTP Guard authenticator. Malware can't push a button.
Can a hacked team member simply enroll a new authenticator with OTP Guard?
The first authenticator is "free" but enrolling secondary authenticators requires a step-up with an existing authenticator to unlock the enrollment. If a team member loses access to their existing authenticators, then an orgnization admin will need to remove the existing authenticators from their account in order to re-enroll.
Admin-approved authenticators may also help with this. Contact us if this is a feature that you need.
What permissions does OTP Guard require? Why should I trust you with my code?
Good news - you should not trust OTP Guard with your code. We don't need it, and can't see it. The Github API has a granular permissions model, and OTP Guard only requires minimal permissions.
Read access to repository metadata. This permission is required by Github.
Read access to pull requests. This includes the PR title, description, author, status, commit list and commit messages. However, this does not include the contents of the commits, or the contents of PR review messages. Your code stays with you.
Read access to organization members. This is so OTP Guard can determine which users should have what permissions, since permissions are inherited from the Github organization.
Read and write access to checks. This is how OTP Guard requires PRs to be authorized before merging.
How much friction does OTP Guard introduce for developers?
Validating a pull request in OTP Guard only takes seconds, and can easily be done alongside the existing PR process. The payoff is peace of mind: your developers are the ones pushing those buttons, not hackers.
Security requires a belt-and-suspenders approach; there is no magical wand to secure all the things. This includes best practices such as limiting access, keeping permissions up-to-date, and making sure secrets are not present in the code. See Github Security Best Practices for more tips on defense in depth.
Last updated
