GitHub
  • 26 Feb 2024
  • 9 Minutes to read
  • Dark
    Light
  • PDF

GitHub

  • Dark
    Light
  • PDF

Article summary

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

AttributesCybersecurity Asset ManagementSaaS Management
Service Account Required?NoYes
Service Account PermissionsN/AAdmin
Required Adapter FieldsGitHub DomainGitHub Domain, User Name and Password, Multi-factor Authentication

Related Enforcement Actions

Types of Assets Fetched

This adapter fetches the following types of assets:

  • Users
  • SaaS Data


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.
NOTE

To get data from multiple organizations in Github, leave this field blank. In the 'GitHub App's ID' field enter the ID for the Github app that is configured on the various organization.

  • 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.

GithubSM2


Advanced Settings

Note:

Advanced settings can either apply for all connections for this adapter, or you can set different advanced settings and/or different scheduling for a specific connection, refer to ​Advanced Configuration for Adapters.

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.
Note:

For details on general advanced settings under the Adapter Configuration tab, see Adapter Advanced Settings.

APIs

Axonius uses the GitHub API.

Permissions

User Account Token

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

Note

Secrets permissions are optional and allows Axonius to query users based on the keys they do or don't have.

  • 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

GitHub App Token

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

Note

Secrets permissions are optional and allows Axonius to query users based on the keys they do or don't have.

  • 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
  • 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

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.
Note

You must regenerate the token and replace it in the adapter connection before the expiration date (at most, one year from creation).

GitHub_TokenExpiration

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

  2. 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
  3. Set the Resource owner to Organization.

  4. Click Generate Token.

  5. Click Github_CopyButton.
    Github_CopyToken

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

  7. 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.


Was this article helpful?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.