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 supports configuring GitHub Advanced Security, Secret Scanning, and Dependabot 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 four main commands for managing security configurations across enterprise organizations:

Commands

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

Persistent Flags

These flags are available on all commands:

• --org-list string (-l) - Path to CSV file containing organization names to target (one per line, no header)
• --concurrency int (-c) - Number of concurrent requests (1-20, default: 1)
• --enterprise-slug string (-e) - GitHub Enterprise slug (e.g., github). Skips interactive prompt when provided
• --github-enterprise-server-url string (-u) - GitHub Enterprise Server URL (e.g., github.company.com). Skips interactive prompt when provided
• --dependabot-alerts-available string (-a) - Whether Dependabot Alerts are available in your GHES instance (true/false). Skips interactive prompt when provided
• --dependabot-security-updates-available string (-s) - Whether Dependabot Security Updates are available in your GHES instance (true/false). Skips interactive prompt when provided

Generate Command Flags

The generate command has additional flags:

• --copy-from-org string (-o) - Organization name to copy an existing configuration from
• --force (-f) - 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

# Apply an existing security configuration to repositories
gh security-config apply

# Modify a security configuration interactively
gh security-config modify

# Delete a security configuration interactively
gh security-config delete

# Use flags to skip interactive prompts
gh security-config generate -e my-enterprise -u github.mycompany.com -a true -s false

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, apply, modify, delete)

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.

Error Handling and Requirements

Dependabot Feature Availability

Dependabot Alerts and Security Updates have different availability requirements:

• Dependabot Alerts: Available when GitHub Connect, Dependency Graph, and Dependabot are enabled
• Dependabot Security Updates: Available when Dependabot Alerts and GitHub Actions are enabled

Checking Availability: Navigate to Enterprise settings → Settings → Code security and analysis to verify which features are available.

Apply 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 an existing security configuration to apply
3. Repository Selection: Choose which repositories should have the configuration applied
4. Confirmation: Review the operation summary and confirm application

Note

The apply operation will attach the specified security configuration to repositories across ALL organizations in the enterprise where the configuration exists. This allows you to apply configurations that were created manually, or without targeting repositories initially.

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. Name Update: Update the configuration name (optional)
5. Description Update: Update the configuration description (optional)
6. Settings Update: Interactively update each security setting with options to keep current values
7. 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
Dependabot Alerts	Detect vulnerable dependencies	enabled, disabled, not_set
Dependabot Security Updates	Automatically create pull requests to update vulnerable dependencies	enabled, disabled, not_set
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
• none: Create the configuration without applying it to any 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.