Configure Dependabot security updates on your GitHub repo

By Madis Kõosaar
github certification advanced-security

Prepearing for GitHub Advanced Security certification - Configure Dependabot security updates on your GitHub repo

Manage your dependencies on GitHub

The dependency graph

  • The dependency graph is a summary of a repository’s manifest and lock files.
  • The dependency graph is automatically generated for public repositories and includes the following information:
    • Dependencies, which are the ecosystem and packages the repository depends on.
    • Dependents, which are the repositories and packages that depend on the repository.

The dependency graph uses the information from your lock and manifest files to provide a list of three kinds of dependencies:

  • direct dependencies
  • indirect dependencies
  • vendored dependencies

Enable the dependency graph for private repositories

You need to be a repository administrator to enable the dependency graph for private repositories.

  • Navigate to your GitHub repository.
  • Click your repository Settings.
  • Click Security & Analysis.
  • Click Enable in the dependency graph section.

Note

  • Dependent information is not included for private repositories.

View the dependency graph

In your repository by following these steps:

  • Navigate to your GitHub repository.
  • Click your repository Insights.
  • Click Dependency graph.
  • You can select the Dependencies or Dependents tab from the Dependency graph view.

Supported package ecosystem for the dependency graph

  • This table lists the recommended and supported formats for files containing your dependencies.
  • By using these formats depencecy graph is more accurate and it can report vulnerabilitites for both direct and indirect dependencies.
  • It is recommended to commit the lock file in your repository as that contains the excat version dependecnies.
  • When using manifest file (or equivalent) then indirect dependencies are not included in checks for vulnerable dependencies.

The GitHub Advisory Database

  • GitHub collects information on vulnerabilities and includes it in the GitHub Advisory Database
  • It is a curated list of security vulnerabilities related to packages tracked by the GitHub dependency graph.
    • This database uses the Common Vulnerability Scoring System (CVSS)
    • The database is populated from the following 4 sources:
      • The National Vulnerability Database
      • A combination of machine learning and human reviews to detect vulnerabilities in public commits on GitHub
      • Security advisories reported on GitHub
      • The npm Security advisories database

Dependabot

  • Tool that automates managing your repository’s dependencies.
  • For Dependabot to work, the dependency graph must be enabled in a repository.
  • uses the dependency graph and the GitHub Advisory Database to provide three features:
    • Dependabot alerts: notify you about vulnerable dependencies in public repositories.
    • Security updates: automatically update or generate a pull request to update vulnerable dependencies.
    • Version updates: automatically update all the packages used by your repository.

Dependabot alerts

GitHub helps to automate this process by monitoring your dependencies and then sending Dependabot alerts when vulnerabilities are detected in your repository.

Dependabot alerts are generated under two conditions:

  • A new vulnerability is added to the GitHub Advisory Database.
  • The dependency graph for a repository changes.

Also pull requests attempts to merge changes to the main branch that contain dependency updates a alert is generated if this would introduce a vulnaribiltiy.

Note GitHub’s security features do not claim to catch all vulnerabilities.

Set up Dependabot alerts

Dependabot alerts are enabled for public repositories by default. Admins/owners can setup alerts for private repositories and for some GitHub Enterprise Server repositories. Enabling these features grants GitHub permission to perform read-only analysis of those specific repositories.

Set up Dependabot alerts for private repositories

To set up Dependabot alerts for private repositories, you need to enable both the dependency graph and Dependabot alerts.

  • Log in to your GitHub account and select your profile photo from the upper-right.
  • Click Settings, then click Code security & analysis under Security in the left-side menu.
  • Click Enable all to the right of the feature you want to enable.
  • If you would like these settings to be applied to all new repositories in your organization, then select the Enable by default for new private repositories checkbox.
  • Click Enable FEATURE to enable the feature for all the repositories you own.

Set up Dependabot alerts for organizations

An organization owner, can enable the dependency graph and Dependabot alerts for all repositories in your organization at once:

  • Log in to your GitHub account and select your profile photo from the upper-right.
  • Click Your organizations.
  • Click Settings next to the organization for which you would like to enable Dependabot alerts.
  • Click Security & analysis from the left sidebar. The ‘Configure security and analysis features’ page displays
  • Click Enable all next to the feature you want to turn on.
  • If you would like these settings to be applied to all new repositories in your organization, then select the Enable by default for new private repositories checkbox.
  • Click Enable FEATURE to enable the feature for all the repositories in your organization.

Set up Dependabot alerts for GitHub Enterprise Server with GitHub Connect

A GitHub Enterprise owner who is also an owner of the connected GitHub Cloud organization or enterprise account can use Github Connect to enable the dependency graph and Dependabot alerts for GHS instance. GH Connect lets you share certain features and data between GHS instae and GitHub Cloud org or enterpise account on GH.

View Dependabot alerts

Dependabot alerts are displayed in the Security tab for the repository and in the repository’s dependency graph.

Grant access to Dependabot alerts

  • By default, only repository owners and administrators are able to receive and dismiss Dependabot alerts
  • Administrators and owners can also grant other teams and users with access to the repository, permissions to view and dismiss Dependabot alerts
  • Navigate to the main page of the repository.
  • In the left-hand side, click Security and analysis.
  • In the Access to alerts section, type the name of the person or team that you would like to be able to manage Dependabot alerts in the search bar. Make your selection.
  • Click Save changes.

Resolve Dependabot alerts

  • When enabled create process to regulary review and resolve Dependabot alerts.

The following steps explain how to resolve Dependabot alerts:

  • Navigate to the main page of the repository.
  • Click the Security tab for the repository.
  • Click Dependabot alerts from the security sidebar. A list of the Dependabot alerts for that repository will display.
  • Click the alert you would like to view.
  • Review the alert details. In some cases, the alert may contain a pull request with an automated security update.
  • Resolve the alert by taking one of the following actions:
    • Review and merge the pull request.
    • Click Create Dependabot security update to manually fix the vulnerability.
    • Click the Dismiss dropdown and choose a reason for dismissing the vulnerability.

Dependabot security updates

Dependabot security updates help you to fix the vulnerabilities identified by Dependabot alerts. Version updates help manage different versions of dependent packages. You can enable two related features so that Dependabot automatically raises pull requests to try to help with your dependency management:

  • Dependabot security updates are automated pull requests that help you update dependencies with known vulnerabilities.
  • Dependabot version updates are automated pull requests that keep your dependencies updated, even when they don’t have any vulnerabilities.

Supported repositories

GitHub automatically enables Dependabot security updates for every repository that meets the following prerequisites:

  • The repository isn’t a fork.
  • The repository isn’t archived.
  • The repository is public or it’s private and you’ve enabled the read-only analysis by the dependency graph, and vulnerability alerts in the repository’s settings.
  • Dependabot security updates aren’t disabled for the repository.

Manually enable security updates

  • Can enable security updates manually on private repositories

  • Make sure you’ve enabled the dependency graph and Dependabot alerts on your repository

    • Log in to your GitHub account and select your profile photo from the upper-right.
    • Click Settings > Security & analysis.
    • Click Enable for Dependabot security updates.

View and resolve security updates

  • Resolve security updates by taking one of the following actions:
    • Review and merge the pull request, PRs also use dependency label.
    • Review and merge a proposed fix into your project like release notes, changelog entries, and commit details.
    • Details of which vulnerability a pull request resolves are hidden from anyone who doesn’t have access to Dependabot alerts for the repository.
    • Merging a security update pull request automatically closes the related Dependabot alert.

View dependencies being monitored by Dependabot

  • Creating and checking your dependabot.yml file into your repository.
  • View dependencies being monitored by Dependabot
    • Navigate to the main page of the repository.
    • Under your repository name, click Insights.
    • Click Dependency graph in the left sidebar.
    • Click Dependabot.
    • Click the three dots next to a package manager to view the files being monitored.

  • The Last checked TIME ago link in the Dependabot tab enables you to see the log files that Dependabot generated.
  • Can rerun the version check by clicking the Check for updates.

Version updates

  • Helps to manage your dependencies by automatically generating a pull request whenever there’s a new version of a package or application that your project depends on.
  • Looks at the semantic versionic of the dependency
  • To enable version updates, you need to create a dependabot.yml file, which will essentially tell Dependabot where to find the manifest, or other package definition file.

Enable version updates for private repositories

  • Need write premissions can enable Dependabot version updates
  • Need to check in dependabot.yml into .github folder
  • dependabot.yml need to contain
    • version: Should be set to 2.
    • registries: Optional if you have dependencies in a private registry.
    • updates: entry for each dependency you want Dependabot to monitor.

For each package manager, include:

  • package-ecosystem: Specifies the package manager.
  • directory: Specifies the location of the manifest or other definition files.
  • schedule.interval: Specifies how often to check for new versions.

Example:

# Basic dependabot.yml file with

# minimum configuration for two package managers



version: 2

updates:

  // Enable version updates for npm

  - package-ecosystem: "npm"

    // Look for `package.json` and `lock` files in the `root` directory

    directory: "/"

    // Check the npm registry for updates every day (weekdays)

    schedule:

      interval: "daily"



  // Enable version updates for Docker

  - package-ecosystem: "docker"

    // Look for a `Dockerfile` in the `root` directory

    directory: "/"

    //# Check for updates once a week

    schedule:

      interval: "weekly"

Version updates on forks

  • These are not automatically enabled on forks
  • this safeguard enables fork owners from unintetnionally enabling version updates when they pull changes inlcuding dependabot.yml.
  • To enable on the fork repo: :
    • Navigate to the main page of the repository where you want to enable version updates.
    • From the main page, select Insights.
    • Click Dependency graph from the left sidebar.
    • Click Dependabot.
    • Click Enable Dependabot.

Allow Dependabot to access private repositories

  • Dependabot must have access to the repository that contains the dependencies
  • Dependabot generally can’t update dependencies that are located in private repositories or private package registries.
    • If the dependency is in a private repository located in the same organization as the package that uses it, then you can grant Dependabot access.

To allow Dependabot to access a private GitHub repository:

  • Go to the security and analysis settings for your organization.
  • Under “Grant Dependabot access to private repository”, click Add private repositories or Add internal and private repositories.
  • Start typing the name of the repository you want to allow.
  • Click the repository you want to allow.
  • Optionally, to remove a repository from the list, go to the right of the repository and click X.

Security update compatibility scores

  • Dependabot security updates may include compatibiltiy scores to let you know if it will cause breaking changes
  • This score is calculated from continuous integration (CI) tests in other public repositories where the same security update has been generated.
  • The compatibility score is the percentage of CI runs that passed when updating between specific versions of the dependency.

Manage Dependabot notifications and reports

  • View information about vulnerable dependencies in your repository’s Security tab.
  • GitHub notifies repository owners and users with admin permissions by default anytime a new alert is detected.
  • To receive a Dependabot alert, admins must be watching the repository, have enabled notifications for security alerts or all activity on the repository, and must not be ignoring the repository.

By default, users receive notifications in the following manner:

  • By email, an email is sent when Dependabot is enabled for a repository, when a new manifest file is committed to the repository, and when a new vulnerability with a critical or high severity is found.
  • in the user interface, a warning is shown in your repository’s file and code views if there are any vulnerable dependencies.
  • on the command line, warnings are displayed as callbacks when you push to repositories with any vulnerable dependencies.
  • in your inbox, as web notifications. A web notification is sent when Dependabot is enabled for a repository, when a new manifest file is committed to the repository, and when a new vulnerability with a critical or high severity is found.
  • on GitHub for mobile, as web notifications.

Configure notifications for Dependabot alerts

  • Can customize notifications:
    • Settings > Notifications.

Triage notifications

  • Can use the notifications inbox on GitHub and GitHub for mobile to triage your notifications
  • You must enable web and mobile notifications from your notifications settings Manage notifications > Notification settings, then Web and Mobile checkbox from the ‘Watching’ section.

The following options are available for triaging your security alerts notifications:

  • Triage multiple notifications at once.
  • Mark completed notifications as ‘Done’ and remove them from your inbox. To view all of your notifications marked as ‘Done’, use the is:done query.
  • Save a notification to review later. Saved notifications are flagged in your inbox and kept indefinitely. To view all of your saved notifications, use the is:saved query.
  • Unsubscribe and remove a notification from your inbox.
  • Preview the issue, pull request, or team discussion where the notification originates from on GitHub.com from within the notifications inbox.
  • See one of the latest reasons you’re receiving a notification from your inbox with a reasons label.
  • Create custom filters to focus on different notifications when you want.
  • Group notifications in your inbox by repository or date to get a quick overview with less context switching.

View dependency information with the GraphQL API

  • Can use the GraphQL API to retrieve and export Dependabot alert information.
  • Need to create an OAuth token with the following scopes
    • user
    • public_repo
    • repo
    • repo_deployment
    • repo:status
    • read:repo_hook
    • read:org
    • read:public_key
    • read:gpg_key

The GraphQL API has a single endpoint that doesn’t change:

https://api.github.com/graphql

GraphQL Explorer

  • The GraphQL Explorer is the recommended tool for communicating with the GraphQL API
  • You can download and install the GraphiQL app from https://github.com/skevy/graphiql-app.
  • Configuring the app:
    • Get a properly configured OAuth token.
    • Launch GraphiQL.
    • In the upper-right corner of GraphiQL, click Edit HTTP Headers.
    • In the Key field, enter ‘Authorization’. In the Value field, enter Bearer <token>, where <token> is your generated OAuth token.
    • Click the checkmark to the right of the token to save it.
    • To return to the editor, click outside of the ‘Edit HTTP Headers’ modal.
    • In the GraphQL Endpoint field, enter https://api.github.com/graphql.
    • In the Method dropdown, select Post.

Write GraphQL queries

query {
  JSON objects to return
}

Example API query

example of a complex API query that fetches the vulnerable dependency for a repository.

query {
  repository(name: "${repo}", owner: "${org}") { 
    vulnerabilityAlerts(first: 100) {
      nodes { 
        createdAt 
        dismissedAt 
        securityVulnerability { 
          package { 
            name 
          } 
          severity 
          vulnerableVersionRange 
          advisory { 
            ghsaId 
            publishedAt 
            identifiers { 
              type 
              value 
            } 
          } 
        } 
      } 
    } 
  }
}

Note

  • Information about resolved alerts isn’t stored in the API and can’t be retrieved.
  • Can also create GitHub Actions that automate the process of retrieving dependency information based on some event or at some interval.

Configure Dependabot exercise

The excerice can be found here