gh-secure README

The project's README from github.com/GitHubSecurityLab/gh-secure. As one markdown file: README.md.

gh-secure

Protect your project in 2 minutes

A GitHub CLI extension to enable security features on public repositories, following best practices from the GitHub Security Lab.

Everything we'll cover is free for open source

No security or coding skills needed

Only an open source project on GitHub where you have admin access.

How do I use it?

Running the tool will enable security features for your repository in 2 minutes or less.

You can use it from your terminal, with an interactive mode or a "just do it" mode.

gh-secure CLI demo

You can also use it from the GitHub Copilot CLI or the GitHub Copilot App, or any other AI assistant who has access to the tool. Ask for an overview of your repository's security, ask for details on specific features, and ask the tool to enable the missing features for you.

gh-secure Copilot App demo

Installation

gh extension install GitHubSecurityLab/gh-secure

Prerequisites

Usage

gh secure                                  # Interactive mode, all features
gh secure --yes                            # Enable all features, no prompts
gh secure branch-protection dependabot     # Enable only these two features
gh secure bp ss cs -y                      # Enable 3 features, no prompts
gh secure --repo owner/repo code-scanning  # Enable CodeQL on specific repo
gh secure --yes --dry-run                  # Preview what would be enabled
gh secure status                           # Check current feature status
gh secure status --repo owner/repo         # Check status of specific repo

Flags

Flag Description
-r, --repo <owner/repo> Target repository (default: current repo)
-y, --yes Enable selected features without prompting for confirmation
-n, --dry-run Simulate changes without applying them
-v, --version Print version
-h, --help Show help message

Feature Names

Pass one or more feature names to enable only specific features. If none are specified, all features are included.

Feature Shorthand
branch-protection bp
vulnerability-reporting vr
secret-scanning ss
dependabot dep
code-scanning cs

Security Features

This tool enables five security features based on GitHub Security Lab recommendations:

1. Branch Protection

Branch protection blocks unwanted changes to your project. Prevent accidental or malicious commits that may introduce vulnerabilities or disrupt the stability of your project. Branch rules give you flexible control over who can force push, delete, etc. If your repository already has active rulesets, gh secure will warn you before enabling legacy branch protection to avoid overlapping or conflicting rules. Documentation

2. Private Vulnerability Reporting

Security Policy and Private Vulnerability Reporting (PVR) create a safe path for reporting vulnerabilities before they go public. Make it easy for people external to the project, such as users and security researchers, to report security bugs privately. Documentation

3. Secret Scanning

Sensitive data like API keys, tokens, and passwords can accidentally be committed to your repository. Secret scanning with push protection guards over 300 token types and patterns from more than 180 service providers. Documentation

4. Dependabot

Dependabot keeps your dependencies safe effortlessly. Automatically checks your dependencies for known vulnerabilities and create pull requests to update them to safe versions. This saves you the hassle of manual checks and blocks threats. Documentation

5. Code Scanning (CodeQL)

GitHub code scanning automatically detects common security vulnerabilities in your project and in your pull requests. Resolve them manually or with the help of Copilot Autofix AI-powered suggestions, before they are exploited against you and your users. Documentation

Troubleshooting

"403 Forbidden" Errors

Ensure you have admin or maintain permissions on the repository. For org repos, you may need admin:org scope — run gh auth refresh -s admin:org.

Code Scanning Fails

Ensure the repository contains supported languages and that code scanning is available for your plan.

Branch Protection Fails

Some organizations have policies that restrict branch protection. Contact your org admin. If your repository uses rulesets, you may not need legacy branch protection at all — gh secure will detect active rulesets and prompt you before enabling it.

Resources

FAQ

What permissions do I need and why?

You need admin or maintain permissions on the target repository. This is because enabling security features (branch protection rules, code scanning, secret scanning, Dependabot, and vulnerability reporting) requires write access to repository settings. For organization repositories, you may also need the admin:org OAuth scope — run gh auth refresh -s admin:org to add it.

How do I authenticate?

gh-secure uses the GitHub CLI authentication. Run gh auth status to check your current session. If you are not authenticated, run gh auth login and follow the prompts. The tool inherits whatever token and scopes your gh session has.

What are the implications of these changes for my project?

Enabling these features adds protective guardrails but does not change your source code:

All of these settings can be reverted at any time from your repository settings, with no impact on the project.

Will my project be secure?

These features significantly raise the security baseline of your project, but no tool can guarantee complete security. They help you detect and prevent common issues — leaked secrets, known vulnerable dependencies, code-level vulnerabilities, and unauthorized changes — but security is an ongoing process. Regularly review alerts, keep dependencies up to date, and follow the GitHub Security Documentation for additional best practices.

License

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.

Maintainers

See CODEOWNERS or reach out to the GitHub Security Lab team.

Support

See SUPPORT.md for details on how to get help with this project.

gh-secure (GitHubSecurityLab/gh-secure)

devsecops
Searching Database…

669 ·GitHub
Gh-secure
What is this?gh-secure is a GitHub CLI extension that turns on five recommended security features on a repository — branch protection, private vulnerability reporting, secret scanning, Dependabot, and code scanning — in about 2 minutes.
Is this a standalone app or a plugin for something else?It is a gh extension, so it runs as a subcommand of the GitHub CLI (gh) rather than as its own standalone program.
How do I install and run it?Install the GitHub CLI, authenticate with gh auth login, then install and run the extension from your terminal (interactive mode or a non-interactive '-y' mode) in the repo you want to secure.
What do I need before running it?You need the GitHub CLI (gh) installed and authenticated, plus admin or maintainer permissions on the target repository; for org repos you may also need the admin:org OAuth scope.
What can go wrong when enabling these features?You can hit 403 Forbidden errors if you lack admin/maintain permissions (orgs may need the admin:org scope), code scanning can fail if the repo's languages aren't supported, and some orgs have policies that block branch protection from being enabled.
Does it run on any OS?It is a shell-based gh extension, so it works wherever the GitHub CLI runs — Windows, macOS, and Linux.
Does it touch my source code or send data anywhere?No — it only changes repository settings (branch rules, scanning toggles, Dependabot) via the GitHub API using your existing gh session token; it does not modify your source code.
Can I enable only specific features instead of all five?Yes, you can pass specific feature names or shorthands (e.g. bp, vr, ss, dep, cs) to enable just those; if none are specified, all five are enabled.
Can I use it with AI assistants instead of the terminal?Yes — the README says it can be used from the GitHub Copilot CLI, the GitHub Copilot App, or any other AI assistant that has access to the tool.
Can I preview changes before applying them?Yes, the -n/--dry-run flag simulates the changes without actually applying them, and all changes can be reverted later from repository settings.
Will enabling branch protection break my existing rulesets?The tool checks for active rulesets first and warns you before enabling legacy branch protection, to avoid overlapping or conflicting rules.
What are similar projects?cynative, bashka, codex-security, Anthropic-Cybersecurity-Skills, gh-dash, 0, Myrqen, just
Which topics is it in?security-automation, application-security, devsecops, infosec, github, cli-tool, shell, security-tools, command-line, devops, command-line-tool, security
Creator
GitHubSecurityLab
Size
2.6 MB
Stars
669
Updated
CommitOct 02
Age
3mo
Commits · 90 Days