GitHub Advanced Security (GHAS)

📘

TL;DR

To integrate the GitHub Advanced Security (GHAS) with Query:

• Generate a Fine-grained token for a user/admin that has proper permissions and ownership/reader access to all Repos you wish to search security data for.
• Configure a GitHub Advanced Security Connector in the Query UI.
• Use Query Search to parallelize searches and surface details about repo details, SBOMs, secret scanning findings, DependaBot findings, CodeQL findings, and/or security advisories for incident response (IR), threat hunting, investigations, and other security and observability use cases.

Overview

GitHub is a popular (understatement) Source Code Management (SCM) tool used by 10s of millions of developers worldwide, and it also boasts an arsenal of built-in security tools. Depending on your license version (Free vs. Enterprise), you may have access to all of the tools. The tools include DependaBot (Software Composition Analysis), Dependency Graph (SBOM), Secret Scanning, GitHub Code Scanning (CodeQL and others), and GitHub Security Advisories. Teams consume from these services as part of their larger Application Security (AppSec) or Product Security (ProdSec) programs to maintain situational awareness of their software stack, apply patches, and deploy remediations or countermeasures. Query integrates with all of the security features as well as generally provides metadata on Repositories to aid AppSec and ProdSec teams along with Security Operations to take action and discover weaknesses and vulnerabilities.

All federated searches have their searches and results expressed in the terms of the Query Data Model (QDM), which is based on the Open Cybersecurity Schema Framework (OCSF). Each API source is normalized into a specific QDM/OCSF Event Class to standardize and normalize the data for increased situational awareness, ease of aggregation of filtering, and easy pivoting.

Query helps simplify the GitHub data model for AppSec, ProdSec, and SecOps users by providing a single plane from which all search and analysis can be carried out - for ad-hoc searches, threat hunting, audit, vulnerability management, or otherwise! Using Query you can search for all AppSec-related issues by a repo name or search across any number of Advisories, CVEs, CWEs, Hashes, or File Names to surface various types of security data. All searches are fully parallelized and rate limit managed, and Query supports filters that GitHub does not natively support either. Users can also start from more broad searches such as using severity-based searches or searching for any of the above Event Classes without a filter to retrieve data for every repo in your GitHub organization.

🤓

Some details on searches

GitHub lacks a comprehensive list of filters on all possible outputs and values provided in their API responses, to this end, Query provides filter emulation in a post-hoc matter. This may lengthen search times as data must be gathered before it is filtered. For the best performance, consider sticking with searches that are well represented by GitHub APIs natively - such as searching by Resource Name (for Repo names) or by CVE ID or Advisory IDs.

GitHub PATs from an authorization perspective are the exact same as the user from which they are created. If you do not have owner rights or security admin rights on the repos in your Organization or Team, we will be unable to retrieve data. It is recommended to use the PAT of an Organization-wide or Enterprise-wide Administrator and ensure they are added to all repos you wish to monitor.

Prerequisites

To connect a GitHub Advanced Security Connector with Query Federated Search you'll need to located or create a User with admin/ownership rights over specific Repos (or your entire Organization or Enterprise) you wish you search for AppSec data on and generate a fine-grained PAT for them.

1. From GitHub, select the menu underneath your user's icon in the top right corner and select Settings.

2. Scroll to the bottom of the page, in the left-hand navigation pane, select Developer settings.

3. On the new left-hand navigation pane select Personal access tokens --> Fine-grained tokens --> Generate new token (on the top-right) as shown below (FIG. 1).

   

4. Provide a Token name, Description, and select a Resource owner. This is an important step, if your User is an administrator or otherwise has ownership-level access to the Repos you are interested in searching for you can stick with yourself (or another user). Optionally, you can select an Organization, if the non-Public repos you want to search against are owned by the Organization.

5. Choose an Expiration date that matches an internal security policy. You can update these the Connector in the Query UI as the Fine-grained token rolls over.

6. In the Repository access section consider choosing All repositories or Only select repositories. If you choose the latter, this will only work if you want to search across 50 or less repos!

7. In the Permissions section, provide the following Repository permissions listed in the table below and select Generate Token when complete.

8. A pop-up window will appear to verify your permissions, if you matched everything listed in Step 7 select Generate token as shown below (FIG. 2). Note, these permissions are not complete, the screenshot is for demonstration purposes.

   

9. You will only be shown the value for the token once, copy the value and store it securely in a password management or vault solution. If you missed it, delete the Token and start again.

To learn how to configure a GitHub Advanced Security Connector, proceed to the next section.

👍

On NHI security

NHI - or, Non-Human Identities - such as your GitHub fine-grained tokens are extremely sensitive, especially with all of the security-related scopes. Query securely stores the Client Secret in a dedicated AWS Secrets Manager Secret per Connector per Tenant.

While this requires you to configure Connectors per GitHub Advanced Security Connector and continue to enter in your credentials, every copy is stored as securely as each other with minimum necessary permissions that only allows the specific piece of serverless infrastructure to retrieve the secret, it is never cached or persisted outside of the Secret.

Setting up the GitHub Advanced Security Connector

Use the following steps to create a new Query Federated Search Connector for GitHub Advanced Security.

1. Navigate to the Connectors page, select Add Connector, and selectGitHub Advanced Security from the Developer Security category as shown below (FIG. 3). You can also search for GitHub Advanced Security using the search bar in the Add Connector page.

   

2. In the Configure Connector tab, add the following detail as shown below (FIG. 4):

   

   1. Connector Alias Name: The human-readable name you want to give to this connector, you can provide the name of your GitHub organization or enterprise, or different customer names if you're setting up the connectors on behalf of a MSSP.
   2. Default Login: Leave the default value: Default Login.
   3. GitHub Personal Access Token (PAT): The fine-grained access token or PAT, copied in Step 9 of the Prerequisites section.

3. Select Save to save and activate the Connector.

4. Select Test Connection from the bottom-right of the connection pane to ensure that the token is valid, that you have access to any repos, that you have proper permissions for your token, and you are licensed for all features. You will receive failures if you are not licensed for everything but this does not impact your ability to search!

You will now see GitHub Advanced Security added as an available Connector within the Query Search and Query Summary Insights UI.

Querying GitHub Advanced Security Connectors

Within the Query Search UI, all Connectors are enabled by default. To check that your specified Connector(s) for GitHub Advanced Security are enabled, navigate to the Developer Security section of the Selected Connectors dropdown and ensure that your specified GitHub Advanced Security Connector(s) are are selected (denoted by a checkbox) before running your searches as shown below (FIG. 5).

Resources

Troubleshooting Steps

• Ensure that your access token is generated by a User with proper ownership permissions to the repos you are interested in searching against.
• You will likely fail the test connection or receive transient errors if you are not fully licensed for every security tool, this is a known behavior and will not impact your ability to search.

If you have exhausted the above Troubleshooting list, please contact your designated Query Sales Engineer or Customer Success Manager. If you are using a free tenant, please contact Query Customer Success via the Support email in the Help section, or via Intercom within your tenant.