GitHub

GitHub provides hosting for software development version control using Git, including distributed version control and source code management (SCM) functionality.

Related Enforcement Actions

• Github - Remove User Extensions

Types of Assets Fetched

This adapter fetches the following types of assets:

• Users
• Devices
• Application Extensions
• Roles
• Groups
• Licenses
• Application Settings
• User Extensions
• SaaS Applications
• Secrets
• Alerts/Incidents
• Application Resources
• Permissions

Parameters

The parameters that you need to fill out will differ based on the capabilities in your Axonius platform. 'General' pertains to users with Cybersecurity Asset Management and/or SaaS Management capabilities.

To learn more about common adapter connection parameters and buttons, see Adding a New Adapter Connection.

General

• GitHub Domain (required, default: https://api.github.com) - The hostname or IP address of the GitHub server.
• Organization (optional) - The organization for the GitHub account. To connect this adapter, either this setting must be set or the Fetch all organizations for logged user setting on the Advanced Configuration screen. You can also fetch data without specifying the Organization, see Fetching data without Specifying the Organization.

• Custom Login URL (optional) - Relevant only to Axonius customers that have the Software Management module enabled. If you have GitHub Enterprise, enter your Custom Login URL here.
• Authorization Token (optional) - Specify the personal access token that has read access. For details, see Creating the Authorization Token. If you authenticate using GitHub App leave this field blank.
• Authenticate using GitHub App - Select to authenticate using the GitHub App. Make sure you add the 'org' scope.
• GitHub App's ID - Github app's ID, can be found under the GitHub app's page. Only use if authenticating with GitHub app.
• App Key File (pem) - Click Upload File to upload the GitHub app's pem key file. You can download this through the GitHub app's page. Only use if authenticating with GitHub App.
  • When an App Key is set up, Axonius also fetches external collaborator data for GitHub apps.
• Verify SSL - Select to verify the SSL certificate offered by the value supplied in GitHub Domain. For more details, see SSL Trust & CA Settings.
• HTTPS Proxy (optional) - A proxy to use when connecting to the value supplied in GitHub Domain.
• For details on the common adapter connection parameters and buttons, see Adding a New Adapter Connection.

SaaS Management

• User Name and Password - Credentials used for the account to fetch SaaS data.
• Multi-factor Authentication - The secret generated in the adapter for setting up 2-factor authentication for the adapter user created to collect SaaS Management data. This is only needed if the customer enabled it in the account assigned to the adapter.

Advanced Settings

General

• Fetch public organizations for users - Select whether to fetch the public organizations each user is a member.

  • If disabled, this adapter will not fetch the public organizations each user is a member of.

• Fetch public gists for users - Select whether to fetch data about public gists for users.

• For each user, show in the user all the repositories they have access in the organization - For each user, show all the repositories in the organization to which they have access.

• Fetch Teams to insert on the Users - Select this option to fetch data for teams that the users belong to.

Cybersecurity Asset Management

• Fetch public organizations for users - Select this option to fetch the names of organizations that the users belong to.
• Fetch all organizations for logged user - Select whether to fetch all organizations for the logged user. To connect this adapter, either this setting must be set or the Organizations setting for each connection's basic configuration.
• Fetch user role and organization data - Select whether to fetch each user role in the organization and additional information about the organization.
• Fetch Repositories as devices (if Application Resources are not available) - Select this option to fetch repositories as devices when application resources are not available.
• Fetch code and secret scanning alerts - Select this option to fetch code scanning and secret scanning alerts from GitHub as Alerts and Incidents assets.
• Fetch repository vulnerabilities - Select this option to fetch dependency vulnerabilities via Github Dependabot alerts, which provide information about the vulnerabilities in the dependencies used in the repository. These vulnerabilities appear as a GitHub Repositories resource type under the Application Resources assets.
• Fetch repository commits - Select this option to fetch for each repository its commit history, if available.

APIs

Axonius uses the GitHub API.

Permissions

User Account Token

Permissions for connections with a token configured via a user account.

• Repository permissions
  • Administration - Read-only
  • Codespaces metadata - Read-only
  • (Optional) Codespaces secrets - Read and write
  • Commit statuses - Read-only
  • Contents - Read-only
  • Metadata - Read-only
  • Pull requests - Read-only
  • (Optional) Secrets - Read-only
• Account permissions
  • Email addresses - Read-only
  • (Optional) GPG keys - Read-only
  • Gists - Read and write
  • (Optional) Git SSH Keys - Read-only
  • Profile - Read and write
  • Plan - Read only (Only for accounts with SaaS Management Capability)
  • (Optional) SSH signing Keys - Read-only

GitHub App Token

Permissions for connections with a token configured via a GitHub app.

• Repository permissions
  • Administration - Read-only
  • Codespaces metadata - Read-only
  • (Optional) Codespaces secrets - Read and write
  • Commit statuses - Read-only
  • Contents - Read-only
  • Metadata - Read-only
  • Pull requests - Read-only
  • (Optional) Secrets - Read-only
• Account permissions
  • Email addresses - Read-only
  • (Optional) GPG keys - Read-only
  • Gists - Read and write
  • (Optional) Git SSH Keys - Read-only
  • Profile - Read and write
  • Plan - Read only (Only for accounts with SaaS Management Capability)
  • (Optional) SSH signing Keys - Read-only
• Organization permissions
  • Administration - Read-only
  • Custom Organization Roles - Read-only - (Only for accounts with SaaS Management Capability)
  • Custom properties - Read-only
  • Custom repository roles -Read-only - (Only for accounts with SaaS Management Capability)
  • Members - Read-only
  • Personal access tokens - Read-only
  • Plan - Read only - (Only for accounts with SaaS Management Capability)
  • Projects - Read-only - (Only for accounts with SaaS Management Capability)
  • Secrets - Read-only
  • Team discussions - Read-only

Alerts

Permissions for receiving alerts.

• Code scanning - Read-only
• Secret scanning - Read-only

Creating the Authorization Token

To create a personal access token:

1. From within a Github app navigate to Personal access tokens > Fine-grained token.
2. Enter a token name.
3. Set the expiration date for one year after the current date.

4. In the Repository Access section, select All repositories.

5. In the Repository permissions set the following permissions:

   • Repository permissions
     • Administration - Read-only
     • Code scanning alerts - Read-only (Only for accounts with SaaS Management Capability)
     • Codespaces metadata - Read-only
     • (Optional) Codespaces secrets - Read and write
     • Commit statuses - Read-only
     • Contents - Read-only
     • Metadata - Read-only
     • Pull requests - Read-only
     • (Optional) Secrets - Read-only
   • Account permissions
     • Email addresses - Read-only
     • (Optional) GPG keys - Read-only
     • Gists - Read and write
     • (Optional) Git SSH Keys - Read-only
     • Profile - Read and write
     • Plan - Read only (Only for accounts with SaaS Management Capability)
     • (Optional) SSH signing Keys - Read-only

6. Set the Resource owner to Organization.

7. Click Generate Token.

8. Click .
   

9. Back in Axonius, paste the copied token into the Authorization Token field.

10. To use a personal access token with an organization that uses SAML single sign-on (SSO), you must first authorize the token to access the organization's SSO. For details, see GitHub Docs - Authorizing a personal access token for use with SAML single sign-on.

To fetch SaaS data:

1. Log into the GitHub User account with the username and password (and MFA if configured).
2. Log into the Organization Github account with the username and password.

Fetching Data Without Specifying the Organization

It is possible to fetch data without specifying the organization. This configuration is meant for Github accounts that have multiple organizations.

If an account has multiple organizations and wants to fetch data from many of them, you need to create the Github app, get the App ID and PEM file, install it on all the organizations you want to fetch from, and use the app as an API.

Before beginning this procedure, ensure that you have the necessary permissions in each organization to install apps. Also, please note that the installation process needs to be done for each organization individually unless you are automating it through an API, which requires an initial installation to get started.

This section provides a general approach to creating, configuring, and using a GitHub App across multiple organizations. For detailed instructions and advanced configurations, refer to the GitHub Developer documentation.

Create a Github App

1. In your GitHub account, navigate to Settings > Developer settings, and select GitHub Apps.
2. Click New GitHub App.
3. Configure your GitHub App
4. Enter a name for your app.
5. Set the Homepage URL (this can be a GitHub repository or documentation URL).
6. (Optional) Set the Callback URL if the app will authenticate with OAuth.
7. Set permissions for the app based on what actions it needs to perform. For API usage, you might need to set specific permissions for repositories, organizations, etc.
8. Subscribe to events that your app needs to be notified about.
9. Click Generate a private key This downloads a .pem file.
10. Store the .pem file for later use in authenticating your app.
11. Locate the App ID on the app's page.

Permissions for the New App

Same permissions as listed above. In addition add the following Organization permissions:

• Administration - Read-only
• Custom Organization Roles - Read-only - (Only for accounts with SaaS Management Capability)
• Custom properties - Read-only
• Custom repository roles -Read-only - (Only for accounts with SaaS Management Capability)
• Members - Read-only
• Personal access tokens - Read-only
• Plan - Read only - (Only for accounts with SaaS Management Capability)
• Projects - Read-only - (Only for accounts with SaaS Management Capability)
• Secrets - Read-only
• Team discussions - Read-only

Under Account Permissions select Access:Read-only for Email addresses and Followers and Access Read and write for Gists and Profile.

Install the App on Your Organizations

1. On your app's settings page, under the General section, locate the installation URL. This URL is used to install the app on any organization where you have sufficient permissions.
2. Log into GitHub as a user with admin rights to the organization.
3. Navigate to the installation URL.
4. Select the organizations from the drop-down menu and follow the prompts to install the app.
5. If your permissions are set to request access on a per-repository basis, specify which repositories the app can access.

Use the App as an API

To use the GitHub App as an API, you'll need to authenticate using the App ID and the private key (PEM file) you downloaded. You'll typically generate a JWT (JSON Web Token) and use it to authenticate API requests.
The GitHub documentation provides extensive guides on authenticating with GitHub Apps, including code examples for generating JWTs and making authenticated API requests.