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)

Searching Database…

660 ·GitHub
Gh-secure
Что это такое?gh-secure — расширение GitHub CLI, которое примерно за 2 минуты включает пять рекомендуемых функций безопасности репозитория: защиту веток, приватные отчёты об уязвимостях, сканирование секретов, Dependabot и сканирование кода.
Это отдельное приложение или плагин для чего-то ещё?Это расширение gh, поэтому оно работает как подкоманда GitHub CLI (gh), а не как отдельная самостоятельная программа.
Как его установить и запустить?Установите GitHub CLI, авторизуйтесь через gh auth login, затем установите и запустите расширение из своего терминала (интерактивный режим или неинтерактивный режим -y) в репозитории, который хотите защитить.
Что нужно перед запуском?Нужен установленный и авторизованный GitHub CLI (gh), плюс права администратора или мейнтейнера на целевом репозитории; для репозиториев организации может дополнительно понадобиться OAuth-скоуп admin:org.
Что может пойти не так при включении этих функций?Можно получить ошибки 403 Forbidden, если нет прав администратора/мейнтейнера (организациям может понадобиться скоуп admin:org), сканирование кода может не заработать, если языки репозитория не поддерживаются, а у некоторых организаций есть политики, блокирующие включение защиты веток.
Работает ли он на любой ОС?Это расширение gh на основе shell, поэтому работает всюду, где работает GitHub CLI — Windows, macOS и Linux.
Он трогает мой исходный код или отправляет данные куда-то?Нет — он лишь меняет настройки репозитория (правила веток, переключатели сканирования, Dependabot) через GitHub API, используя ваш существующий сессионный токен gh; исходный код он не изменяет.
Можно включить только отдельные функции вместо всех пяти?Да, можно передать конкретные имена функций или их сокращения (например, bp, vr, ss, dep, cs), чтобы включить только их; если ничего не указано, включаются все пять.
Можно ли использовать его с ИИ-ассистентами вместо терминала?Да — в README сказано, что им можно пользоваться из GitHub Copilot CLI, приложения GitHub Copilot App или любого другого ИИ-ассистента с доступом к этому инструменту.
Можно ли посмотреть изменения до их применения?Да, флаг -n/--dry-run имитирует изменения без реального применения, а все изменения позже можно откатить из настроек репозитория.
Не сломает ли включение защиты веток мои существующие rulesets?Инструмент сначала проверяет активные rulesets и предупреждает перед включением классической защиты веток, чтобы избежать пересекающихся или конфликтующих правил.
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, security-tools, shell, command-line, devops, command-line-tool, security
Creator
GitHubSecurityLab
Size
2.6 MB
Stars
660
Updated
CommitOct 02
Age
3mo
Commits · 90 Days