GitHub

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

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.

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

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

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

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.

1. Go to GitHub Settings

2. Select Developer settings

3. Select GitHub App, then select 'Your App', and choose Edit.

4.Same permissions as listed above. In addition addd 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

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