Enterprise security management teams

Note

This is an unofficial tool created by Field Security Specialists, and is not officially supported by GitHub.

These scripts provide an emulated Enterprise security manager team to GitHub Enterprise (Cloud or Server) administrators by using the existing organization Security Manager role.

The scripts will give you a list of all organizations in the enterprise as a CSV to work with programmatically, add you to some or all organizations as an owner, and can create/manage a team with the Security Manager role to see all GitHub Advanced Security alerts throughout the entire enterprise without having admin rights to that code.

Note

This uses the security manager role and parts of the GraphQL API that is available in GitHub.com (free/pro/teams and enterprise), as well as GitHub Enterprise Server versions 3.5 and higher.

Scripts

1. org-admin-promote.py replaces some of the functionality of ghe-org-admin-promote, a built-in shell command on GHES that promotes an enterprise admin to own some/all organizations in the enterprise. It also outputs a CSV file similar to the all_organizations.csv report, to better inventory organizations.
2. manage-sec-team.py creates a team in each organization, assigns it the security manager role, and then adds the people you want to that team (and removes the rest).
3. org-admin-demote.py takes the text file of orgs that the user wasn't already an owner of and "un-does" that promotion to org owner. By default, it removes the admin from those organizations. It can instead retain the admin as an organization member, preserving security manager team membership.

How to use it

Note

You need to be an Enterprise administrator to use these scripts

1. Read ☝️ and decide what you want to do.

2. Create a classic personal access token with the admin:enterprise and admin:org scopes using an Enterprise administrator account.

3. Clone this repository to a machine that has Python 3 installed.

4. Install the requirements.

   python3 -m pip install --upgrade pip
   pip install -r requirements.txt

5. Choose inputs as arguments to the scripts as follows:

   • The server URL (for GHES, EMU, or data residency) in --github-url.
     • For GHEC this is not required.
   • Call the scripts with the correct GitHub PAT:
     • Place it in GITHUB_TOKEN in your environment, or
     • create a file and save your token there to read it, and call the script with the --token-file argument.
   • See progress with the --progress flag.
   • Promote/demote scripts:
     • Limit the promotion to a subset of organization slugs/names using the --orgs or --orgs-file arguments.
       • For --orgs/-o, list them space separated after the argument.
       • For --orgs-file/-f, put a new-line separated list of organizations in a file and provide the path.
     • Use the enterprise slug as the first argument:
       • This is string URL version of the enterprise identity. It's available in the enterprise admin url (for cloud and server), e.g. https://github.com/enterprises/ENTERPRISE-SLUG-HERE.
     • By default, a list of all of the organizations in scope, and the unmanaged set, will be output to all_orgs.csv and unmanaged_orgs.txt respectively.
       • You can use the --orgs-csv and --unmanaged-orgs arguments to place these elsewhere.
     • For org-admin-demote.py, use --target-role member to retain the enterprise admin as an organization member after removing owner access. The default, --target-role unaffiliated, preserves the existing behavior and removes the admin from the organization.
   • Security manager team script:
     • Put the name of the security manager team and the team members to add in --team-name and --team-members.
     • --sec-team-members (and --sec-team-members-file) are optional. If neither is supplied, the security managers team will still be created in each organization and assigned the security manager role, but its membership will not be modified. This is useful when team membership is managed via Team Sync.
     • If you are using GHES 3.15 or below, use the --legacy flag to use the legacy security managers API.
     • Use the list of orgs output by org-admin-promote.py in --unmanaged-orgs, if you changed the output path.

6. Run them in the following order:

   1. org-admin-promote.py to add the enterprise admin to all organizations as an owner, creating a CSV of organizations.
   2. manage-sec-team.py to create a security manager team on all organizations and manage the members.
   3. org-admin-demote.py will remove the enterprise admin's owner access from all the organizations the promotion script added them to. It removes the admin from those organizations by default, or retains organization and security manager team membership with --target-role member.

Assumptions

• The security manager team isn't already an existing team that's using team sync for enterprise or for organizations.
• Because team membership requires organization membership, the default unaffiliated target also removes the admin from the security managers team. If the enterprise admin should remain in that team, run org-admin-demote.py with --target-role member.

Example

This is what a successful run looks like. Here's the inputs:

• The enterprise admin is named ghe-admin.
• The security team is named security-managers (the default) and has two members luigi and hubot.
• The organizations break down as such:
  • acme org was already configured correctly.
  • testorg-00001 needed the team created, with ghe-admin removed and luigi and hubot added.
  • testorg-00002 was already created.
• We've used the --progress flag

$ ./manage-sec-team.py --sec-team-members luigi hubot --progress
✓ Team security-managers updated as a security manager for acme
Creating team security-managers
✓ Team security-managers updated as a security manager for testorg-00001
Removing ghe-admin from security-managers
Adding luigi to security-managers
Adding hubot to security-managers
Creating team security-managers
✓ Team security-managers updated as a security manager for testorg-00002
Removing ghe-admin from security-managers
✓ Team security-managers updated as a security manager for testorg-00003

Demotion examples

Remove the enterprise admin from the organizations recorded in unmanaged_orgs.txt:

./org-admin-demote.py ENTERPRISE_SLUG

Remove owner access while retaining the enterprise admin as an organization member and preserving its security manager team membership:

./org-admin-demote.py ENTERPRISE_SLUG --target-role member

Both modes operate only on the organization IDs recorded by org-admin-promote.py. The demotion script does not modify teams or team memberships directly.

Architecture Footnotes

• Scripts that do things are in the root directory.
• Functions that do small parts are in /src, grouped roughly by what part of GitHub they work on.
• Python code is formatted with black.
• Python dependencies are minimal by default. There are two:
  • requests is a simple and popular HTTP library.
  • defusedcsv is used over csv to mitigate spreadsheet application exploitation in older versions.
• The .csv files and .txt files are in the .gitignore file to avoid accidental commits into the repo.

TLS / custom certificates

If you are running against a GitHub Enterprise Server instance that uses a self‑signed certificate or an internal certificate authority, you can provide a custom root CA (or certificate bundle) with the --ca-bundle argument on all three scripts:

./org-admin-promote.py ENTERPRISE_SLUG --github-url https://ghe.example.com --ca-bundle /path/to/internal-ca.pem
./manage-sec-team.py --github-url https://ghe.example.com --ca-bundle /path/to/internal-ca.pem --sec-team-members alice bob
./org-admin-demote.py ENTERPRISE_SLUG --github-url https://ghe.example.com --ca-bundle /path/to/internal-ca.pem

The value passed must be a readable PEM file containing the certificate(s). If omitted, the Python default trust store is used.