GitHub Settings

This is the individual plugin for polling github settings for organizations and repositories to test for configuration flags that are going to fail compliance checks.

For the moment, it is solely limited to authenticated Github organizations with a Github PAT, but in the future it should query security plans & repositories for specific settings

This page is for operators who run the plugin-github-settings plugin with the CCF Agent, and for developers who write policies for it. It documents v0.6.0 and is generated from the plugin's README at v0.6.0.

How it works

Usage

You can use this plugin by passing it to the compliance agent

agent --plugin=[PATH_TO_YOUR_BINARY]

Requirements

Prerequisites

• GoReleaser https://goreleaser.com/install/
• Github Fine Grain Personal Access Token with the following scopes:
  • read:org for the organization to be queried. Note - you might need to be an administrator of the GH Org to work correctly
  • read:members to be able to read teams

IP allow-list data

GitHub organization IP allow-list collection is disabled by default. Enable it only when the plugin is configured with a Classic Personal Access Token with organization administrator permissions. Classic PATs are broad credentials, so prefer leaving collect_ip_allow_list set to false unless IP allow-list policies are required.

Fine-grained Personal Access Tokens and GitHub App installation tokens may be able to read other organization settings, but GitHub does not currently allow them to query organization.ipAllowListEntries through GraphQL.

If IP allow-list data cannot be fetched, the plugin continues with partial data and policies that depend on ip_allow_list should report a skip reason instead of evaluating incomplete evidence.

Configuration

Plugin Configuration

The plugin configuration must be created and managed by the agent, but expects the following configuration keys to be set, otherwise it will fail.

Plugins read their configuration from environment variables, when the path matches the yaml structure.

In the example above, setting an empty token, and an environment variable CCF_PLUGINS_GITHUB_CONFIG_TOKEN will use the environment variable.

export CCF_PLUGINS_GITHUB_CONFIG_TOKEN="github_pat_1234..."
export CCF_PLUGINS_GITHUB_CONFIG_COLLECT_IP_ALLOW_LIST="false"

---
plugins:
  github:
    config:
      token: "" # Will be read from the CCF_PLUGINS_GITHUB_CONFIG_TOKEN environment variable
      organization: test-org # The name of the organization
      collect_ip_allow_list: false # Set to true only when using a Classic PAT and IP allow-list evidence is required

Policies

The policy bundles that work with this plugin, at their newest releases. The controls are the ones the bundle's policies list in their metadata.

Bundle	Latest version	Controls covered	Compatible plugin lines
plugin-github-settings-policies	v0.4.1	none listed	latest