GitHub Advanced Security (GHAS) is a suite of security features integrated into GitHub, designed to enhance the security posture of software development projects. It provides a comprehensive set of tools to identify and address security vulnerabilities throughout the development lifecycle, emphasizing a "developer-first" approach to security. For more information, refer to GitHub’s official documentation.

Integration Methods: API, HTTP Collector

Tables: Data Security Finding [2006], Application Security Posture Finding [2007]

This integration supports the following events.

This integration supports the following versions.

Note:

GitHub is a cloud-based platform that gets continuously updated. As of this document preparation, the latest version is v3.16.

Prerequisites

• The user should have a fine-grained access token for "Code scanning & Secret Scanning alerts".

• The user should have access to the DataBee console.

Configuration Overview

1. Generate fine-grained access tokens with the required scope.

2. Add the GitHub Advanced Security data feed in the DataBee console with the below parameters.

   DataBee Parameter	GitHub Parameter
   Token	Fine-grained Access Token
   Organization Name	Organization Name

   This integration supports two ways to ingest data – API or HTTP Collector (Webhook). This document details both approaches.

GitHub Advanced Security Configuration (API ingestion)

Create a Fine-grained access token

1. Login to your GitHub account.

2. In the upper-right corner of GitHub, click your profile photo.

   

3. Click on Settings.

   

4. In the left sidebar, click Developer settings.

   

5. In the left sidebar, under Personal access tokens, click Fine-grained tokens.

   

6. Click on Generate new token.

   

7. Fill in the form details as mentioned below.

   • Token name: Enter a name for the token.

   • Expiration: Select an expiration date for the token.

   • Description (optional): Add a note to describe the purpose of the token.

   • Resource owner: Select a resource owner. The token will only be able to access resources owned by the selected resource owner. Organizations that are a member will not appear unless they have opted in to fine-grained personal access tokens. For more details, see "Setting a personal access token policy for your organization."

   • If the selected resource owner belongs to an organization that requires approval for fine-grained personal access tokens, provide a justification in the text box below the resource owner.

   

   Note:

   Ensure that the token expiration is set to a larger number of days.

8. Repository access: Choose which repositories the token can access.  Currently, we’ve selected the All repositories option. Update this selection based on your requirements.

   

9. Under the Permissions section, click on + Add permissions.

10. Search Code scanning alerts, enable the checkbox, and make sure the read-only access is enabled.

    

11. Search for Secret scanning alerts, enable the checkbox, and make sure the read-only access is enabled.

    

12. Click on Generate Token.

    

13. Copy the generated API token for later use.

    

Get the Organization Name

1. In the upper-right corner of any page on GitHub, click your profile photo, then click Organizations.

   

2. Copy the Organization name for which you created the Fine-grained access token.

   

DataBee Configuration (API ingestion)

1. Login to the DataBee UI, navigate to Data > Add New Data Feed button.
    

2. Search for the GitHub Advanced Security and click it as shown below.
    

3. Click on the API Ingest option for collection.
    

4. Enter feed contact information and click Next.
    

5. In the configuration page, confirm the following:

   • API Base URL: This is the base URL that DataBee will interact with

   • Authorization Method: Bearer Token

   • Token: Paste the Personal Access Token generated earlier in the GitHub console.

   • Event Types: Preselected for all the event types that integration pulls.

   • Organization Name: Paste Organization Name.

   

6. Click Submit.

DataBee Configuration (webhook ingestion)

In case of webhooks method in GitHub, please use the HTTP Collector. To learn more about HTTP Collector, refer to this article.

Note:

To use the HTTP collector, certain parameters need to be forwarded to DataBee for proper routing. This includes an API KEY, datasource id, tenant id and other information. DataBee receives this in the HTTP header. However, Github sends these as query parameters.

Currently, a translation layer in the middle is needed to transpose these keys from query parameter to http headers. Please refer to the MITM Proxy document.

1. Login to the DataBee UI, navigate to Data > Add New Data Feed button.
    

2. Search for the GitHub Advanced Security and click it as shown below.
    

3. Select HTTP Collector.

   

4. Configure Data Feed.

   1. Data Feed Name/Owner details: In this section, you need to add the data feed name, owner name, and email ID

   2. Configuration of data feed: Select the file type from the dropdown. Please use JSON format, set the split delimiter to (\n), and enable the Process array objects as individual log checkbox.

   3. The Endpoint URL, Tenant ID, and API Key will be automatically generated by the UI. Please save a copy for future reference.

   4. Click Submit.

   

   

5. Go to Data > Data Feeds > Click on the respective data feeds > ID (Datasource ID). Copy to clipboard for future use.

   

GitHub Advanced Security Configuration – HTTP Collector

Creating the webhooks

1. Login to your GitHub account.

2. In the upper-right corner of GitHub, click your profile photo.

   

3. Click on Organizations.

   

4. Click on Webhooks.

   

5. Payload URL & Content-Type – Paste the generated Payload URL from the MITM Proxy, select the appropriate content type from the dropdown, and enter the secret if applicable.

   

6. To enable Advanced Security events, select Let me select individual events and enable the Code scanning alerts and Secret scanning alerts options.

   

7. Click on Update webhook.

   

Troubleshooting Tips

• Invalid or expired token: If you encounter an invalid or expired token error, it may be due to using an incorrect or expired fine-grained personal access token. Double-check that the token you pasted is valid and has not expired.

• Pending approval: If you selected an organization as the resource owner and that organization requires approval for fine-grained personal access tokens, your token will remain in a pending state until reviewed by an organization administrator. While pending, the token can only access public resources.

• If you are an organization owner, your request is approved automatically.

• For more details, see Reviewing and revoking personal access tokens in your organization.