Ingest GitHub Advanced Security security events and audit logs

  • Latest Dynatrace
  • How-to guide

Dynatrace integration with GitHub Advanced Security (GHAS) enables users to unify and contextualize vulnerability findings across DevSecOps tools and products, facilitating centralized prioritization, visualization, and automation of security findings.

GitHub Advanced Security includes Code Security and Secret Protection which generate vulnerability findings for development artifacts, such as code and containers. Dynatrace observes the runtime entities associated with those artifacts. Ingesting and enriching vulnerability findings helps users focus on high-impact risks affecting production applications.

The first version of this integration ingests and contextualizes Dependabot alerts, which are free for public repositories and part of the Code Security premium offering.

Hub

Explore in Dynatrace Hub

Ingest GitHub Advanced Security (GHAS) security events and audit logs.

How it works

how it works

The Dynatrace GHAS integration is an extension deployed in a Dynatrace ActiveGate that periodically collects security findings and audit logs using the GitHub REST API.

Security findings are ingested into the Dynatrace platform via a dedicated OpenPipeline security ingest endpoint.

The OpenPipeline ingest endpoint processes and maps the security findings according to the Semantic Dictionary conventions.

These are stored in a bucket called default_securityevents (for details, see: Built-in Grail buckets).

Optionally, the collected audit logs are ingested via a dedicated extensions log ingest pipeline and stored in the appropriate semantic format.

Prerequisites

See below for the GitHub and Dynatrace requirements.

GitHub requirements

For the extension to collect security data, authentication credentials with proper permissions are required. You have two options, described below.

recommended

The GitHub app-based authentication

  • Allows granular permission control

  • Can collect organization level audit logs

  • Has higher API rate limits

To register and install a GitHub app, follow the steps below.

  1. Follow the steps in Registering a GitHub app with the following values:
  • For GitHub App Name, enter DynatraceAppSec-<Your Company>, making sure to replace <Your Company> with your own value.
  • For Homepage URL, enter https://dynatrace.com.
  • Clear Webhook > Active.
  • Enable the following permissions:
    • Repository permissions:
      • Contents: Read-only
      • Dependabot alerts: Read-only
    • Organization permissions
      • Administration: Read-only
  • To set the location where the app will be installed, select one of the following:
    • Any account (allows you to install the app in multiple organizations and even user account, which will simplify your monitoring configurations)
    • Only this account (the app is installed in the current account; this means you'll need multiple apps and monitoring configurations to cover multiple organizations under an enterprise)

  1. Select the General tab and go to the newly registered app settings.

  2. Copy the client ID (you'll need it when setting up the monitoring configuration).

  3. Under Private keys, generate a private key (you'll need it when setting up the monitoring configuration)

    The private key allows authenticated requests from the extension; make sure to secure it.

Install the GitHub app on any accounts (users or organizations) you want to monitor.

Dynatrace requirements

  • ActiveGate version 1.310+ that needs to be able to

    • Run Extensions 2.0 framework
    • Reach the GitHub API endpoint URLs

  • Permissions:

    • To run Extensions: Go to Dynatrace Hub Hub, select Extensions Extensions, and display Technical information.
    • To query ingested data: storage:security.events:read.

  • Generate an access token with the openpipeline.events_security scope and save it for later. For details, see Dynatrace API - Tokens and authentication.

Get started

  1. In Dynatrace, search for GitHub Advanced Security and select Install.

  2. Follow the on-screen instructions to configure the extension.

  3. Verify configuration by running the following queries in Notebooks:

    • For audit logs:

      fetch logs
      | filter log.source=="GitHub Advanced Security"

    • For finding events:

      fetch security.events
      | filter dt.system.bucket == "default_securityevents"
      | filter event.provider=="GitHub Advanced Security"
      AND event.type=="VULNERABILITY_FINDING"

    • For scan events:

      fetch security.events
      | filter dt.system.bucket == "default_securityevents"
      | filter event.provider=="GitHub Advanced Security"
        AND event.type=="VULNERABILITY_SCAN"

  4. Once the extension is installed and working, you can access and manage it in Dynatrace via the Extensions Extensions app. For details, see About Extensions.

Use cases

With the ingested data, you can accomplish various use cases, such as

Frequently asked questions (FAQ)

Which data model is used for the security logs and events coming from GHAS integration?

  • Vulnerability finding events store the individual vulnerability findings reported by various GHAS products per affected artifacts and component.

  • Vulnerability scan events indicate coverage of scans for individual artifacts.

  • Audit logs represent the user activity logs in the GHAS products.

Which GHAS security findings are imported into Dynatrace?

  • If the extension is configured to ingest data at an interval of n hours, then whenever the extension runs all Dependabot alerts updated in the last n hours will be ingested.

  • On the first ingest, we consider alerts updated in the last m hours, where m is the first ingest interval configured in the monitoring configuration.

  • If no scans occurred, no findings will be ingested, even if the project has open issues. Consult the GitHub Docs to see when a scan will occur.

Which extension fields are added to the core fields of the events ingested from GHAS?

The github namespace is added for extracting several GHAS-specific attributes for user convenience on top of the original issue JSON, which is stored in the event.original_content field.

Examples:

  • github.dependency.relationship

  • github.dependency.scope

  • github.epss.percentage

  • github.epss.percentile

  • github.ecosystem

What GHAS asset types are supported by Dynatrace for runtime contextualization?

CODE_ARTIFACT: All the findings from GitHub Advanced Security products coming from the assessment of code artifacts are mapped set with CODE_ARTIFACT value in the object.type field, and the artifact and component namespaces are added with the corresponding fields:

  • artifact.repository.name represents the repository name which hosts the artifact.

  • artifact.path is the full path of the file representing the code artifact.

  • component.name represents the name of the vulnerable library within a code artifact.

  • component.version includes the version of the vulnerable component.

    GitHub only provides limit values and not the exact version, for example, <1.4. This limits the possibility of matching runtime components, as the version isn't matched in this case.

How is the risk score for GHAS findings normalized?

The Dynatrace risk levels and scores are mapped from the original GHAS severity and score.

  • dt.security.risk.level - is taken from the GHAS severity level and mapped from the original values in finding.severity.

  • dt.security.risk.score - is taken from the GHAS severity level and mapped to static scores. The CVSS score reported by GHAS is available in finding.score; however, this may not always match the reported severity.

dt.security.risk.level (mapped from finding.severity)dt.security.risk.score (mapped from dt.security.risk.level)
critical -> CRITICAL10.0
high -> HIGH8.9
medium -> MEDIUM6.9
low -> LOW3.9
Related tags
Threat Observability