GitHub Security Configuration CLI Extension

A GitHub CLI extension to create and apply security configurations across many organizations in a GitHub Enterprise.

Note

This extension is intended for GitHub Enterprise Server (GHES) 3.15 and currently only supports configuring GitHub Advanced Security and Secret Scanning features as part of a security configuration. For GHES 3.16+ and GitHub Enterprise Cloud (GHEC) it's recommended to use Enterprise Security Configurations instead of this solution.

Pre-requisites

1. GitHub CLI
2. GitHub Advanced Security licenses and availability in your organizations.
3. Confirm that you are authenticated with an account that has access to the enterprise and organizations you would like to interact with. You can check your authentication status by running:

gh auth status

Ensure that you have the necessary scopes (read:enterprise and admin:org). You can add scopes by running:

gh auth login -s "read:enterprise,admin:org"

Important

Enterprise admins do not inherently have access to all of the organizations in the enterprise. You must ensure that your account has the necessary permissions to access the organizations you want to modify. To elevate your permissions for an organization, refer to these GitHub docs.

Installation

To install this extension, run the following command:

gh extension install CallMeGreg/gh-security-config

Usage

The extension provides three main commands for managing security configurations across enterprise organizations:

Commands

• generate - Create and apply new security configurations across organizations
• delete - Remove existing security configurations from organizations
• modify - Update existing security configurations across organizations

Persistent Flags

These flags are available on all commands:

• --org-list string - Path to CSV file containing organization names to target (one per line, no header)
• --concurrency int - Number of concurrent requests (1-20, default: 1)

Generate Command Flags

The generate command has additional flags:

• --copy-from-org string - Organization name to copy an existing configuration from
• --force - Force deletion of existing configurations with the same name before creating new ones

Basic Usage Examples

# Create a new security configuration interactively
gh security-config generate

# Delete a security configuration interactively
gh security-config delete

# Modify a security configuration interactively
gh security-config modify

Organization Targeting

By default, all commands target every organization in the specified enterprise. You can limit the scope using the --org-list flag:

• CSV Format: Create a CSV file with one organization name per line (no header row required)
• Example CSV: See example-organizations.csv for the correct format
• Error Handling: If an organization from the CSV is not found or accessible, the tool will show a warning and continue with other organizations

Copying Security Configurations

The --copy-from-org flag allows you to copy an existing security configuration from one organization and apply it to other organizations in your enterprise. This is useful for:

• Standardizing configurations: Copy a well-tested configuration across multiple organizations
• Quick setup: Avoid recreating similar configurations from scratch
• Configuration migration: Move configurations between organizations

How it works:

1. Source Organization Access: You must be an owner of the source organization to copy configurations
2. Configuration Selection: Choose from available security configurations in the source organization
3. Settings Review: Review the configuration details that will be copied
4. Target Filtering: The source organization is automatically excluded from target organizations to prevent self-copying

Note

When using --copy-from-org, you can still customize the repository attachment scope and default setting for the target organizations, even though the security settings themselves are copied from the source.

Concurrency and Performance

All commands support concurrent requests using the --concurrency flag to improve performance when working with many organizations.

Concurrency Settings

• Default: 1 (sequential processing, maintains existing behavior)
• Range: 1-20 (validated to prevent excessive API usage)
• Usage: Available on all commands (generate, delete, modify)

Performance Benefits

• Faster Execution: Significantly reduces total processing time for large numbers of organizations
• Configurable: Choose concurrency level based on your needs and environment
• Progress Tracking: Real-time progress updates work seamlessly with concurrent processing

Warning

Rate Limiting Considerations: Setting concurrency higher than 1 increases the likelihood of encountering GitHub's secondary rate limits. To avoid rate limiting issues, consider exempting the user from rate limits.

Delete Security Configurations

The extension will guide you through:

1. Enterprise Setup: Enter your GitHub Enterprise slug and server URL (if using GitHub Enterprise Server)
2. Configuration Selection: Specify the name of the security configuration to delete
3. Confirmation: Review the operation summary and confirm deletion (defaults to cancel for safety)

Warning

The delete operation will remove the specified security configuration from ALL organizations in the enterprise. This action cannot be undone. Repositories will retain their security settings but will no longer be associated with the configuration.

Modify Security Configurations

The extension will guide you through:

1. Enterprise Setup: Enter your GitHub Enterprise slug and server URL (if using GitHub Enterprise Server)
2. Configuration Selection: Specify the name of the security configuration to modify
3. Current Settings Display: View the current configuration settings and description
4. Settings Update: Interactively update each security setting with options to keep current values
5. Confirmation: Review the changes and confirm modification before execution

Note

The modify operation will update the specified security configuration across ALL organizations in the enterprise where it exists. Organizations without the configuration will be skipped.

Security Settings

The extension allows you to set the following features within the security configuration:

Setting	Description	Options
GitHub Advanced Security	The enablement status of GitHub Advanced Security	enabled, disabled
Secret Scanning	Detect secrets in code	enabled, disabled, not_set
Secret Scanning Push Protection	Block commits with secrets	enabled, disabled, not_set
Secret Scanning Non-Provider Patterns	Scan for non-provider patterns	enabled, disabled, not_set
Enforcement	Restrict setting changes at the repository level	enforced, unenforced

Repository Attachment Scopes

When attaching configurations to repositories, you can choose:

• all: Apply to all repositories in the organization
• public: Apply only to public repositories
• private_or_internal: Apply only to private and internal repositories

Demo

Development

To build the extension locally:

go build -o gh-security-config

To run the extension locally:

./gh-security-config --help

Contributing

1. Fork the repository
2. Make your changes
3. Submit a pull request

License

This tool is licensed under the MIT License.