Keeping dependencies updated is an important part of application security. Modern applications rely on third-party libraries for authentication, database access, logging, networking, and many other functions. When a package contains a known vulnerability, every application using an affected version may need investigation.
Finding the vulnerable package is only the first step. Developers also need to determine which version is affected, whether the application actually uses that dependency, and which version contains the required fix.
GitHub Dependabot alerts help identify vulnerable dependencies in repositories. The GitHub REST API allows teams to retrieve these alerts programmatically, making it possible to build security reports, automate dependency reviews, and identify affected packages across multiple repositories.
This article explains how to retrieve Dependabot alerts through the GitHub API, interpret affected version ranges, identify fixed versions, and build a practical workflow for dependency security reviews.
Understanding GitHub Dependabot Alerts
Dependabot alerts notify repository maintainers when GitHub identifies a dependency associated with a known vulnerability.
Depending on the ecosystem and available vulnerability information, an alert may include details such as the affected package, vulnerable version range, severity, advisory information, and a recommended patched version.
For example, a .NET application may depend on a library that has a known vulnerability in a particular release range. An alert can help developers determine whether the resolved package version falls within that range.
What Information Does an Alert Contain?
The GitHub Dependabot alerts API can return fields such as:
Field | Purpose |
|---|
number
| Identifies the alert within the repository |
state
| Indicates whether the alert is open, dismissed, or fixed |
dependency
| Provides information about the affected dependency |
security_advisory
| Contains information about the security advisory |
security_vulnerability
| Contains vulnerability details, including affected version information where available |
created_at
| Indicates when the alert was created |
fixed_at
| Indicates when the alert was marked as fixed, when available |
html_url
| Provides the GitHub page associated with the alert |
The exact fields and values depend on the API response and the vulnerability data available for the dependency.
An alert is a useful starting point, but it does not automatically prove that the application is exploitable. Developers must still inspect the dependency graph, the application's usage, and the affected execution paths.
Understand Affected and Patched Package Versions
Before writing automation, it is important to understand how vulnerability information describes affected versions.
A security advisory may identify a vulnerable version range and a patched version.
For example, an illustrative advisory might describe the following situation:
Package version | Example status |
|---|
2.1.0 | Affected |
2.2.0 | Affected |
2.3.0 | Affected |
2.4.0 | Fixed version |
2.5.0 | Later version |
These versions are examples only and do not represent a real vulnerability.
The important distinction is between the version currently used by the application and the version that contains the fix.
Read the Vulnerable Version Range
Dependabot vulnerability information may include fields such as vulnerable_version_range and first_patched_version.
For example, a response might contain a structure similar to this:
{
"security_vulnerability": {
"package": {
"name": "example-library",
"ecosystem": "npm"
},
"vulnerable_version_range": ">= 2.1.0, < 2.4.0",
"first_patched_version": {
"identifier": "2.4.0"
},
"severity": "high"
}
}
This is an illustrative example, not a real GitHub alert.
In this example, versions beginning at 2.1.0 and earlier than 2.4.0 fall within the stated vulnerable range. Version 2.4.0 is identified as the first patched version.
Do not interpret every version range using simple string comparison. Version identifiers may follow ecosystem-specific rules, including prerelease conventions and package-specific version semantics.
When analyzing a real alert, use the advisory's version range and patched-version information, then verify the actual resolved package version using the package manager or lock file.
Why the First Patched Version Matters
The first patched version provides a useful upgrade target, but it is not the only factor to consider.
A newer version may contain additional fixes, while a major-version upgrade may introduce breaking changes. Some advisories may not provide a patched version for every affected release line.
Before upgrading, verify that the proposed version is supported and compatible with the application.
Prepare GitHub API Authentication
To retrieve Dependabot alerts programmatically, you need an authentication method with the required repository permissions.
The GitHub REST API supports access through appropriately authorized tokens, including fine-grained personal access tokens and GitHub App installation tokens.
For a private repository, the token must have the necessary access to that repository and permission to read Dependabot alerts. Organization policies may impose additional restrictions.
Store the Token Securely
For local testing, supply the token through an environment variable rather than hard-coding it in a script.
For example, in PowerShell:
$env:GITHUB_TOKEN = "YOUR_TOKEN"
Replace the placeholder with a valid token through a secure local process. Avoid saving real credentials in source control or shared scripts.
For production automation, use an approved secret manager or CI/CD secret store. Prefer short-lived credentials when they meet the workflow's requirements.
Retrieve Dependabot Alerts Using the GitHub REST API
The GitHub REST API provides an endpoint for listing repository Dependabot alerts.
The endpoint follows this structure:
GET /repos/OWNER/REPOSITORY/dependabot/alerts
Replace OWNER and REPOSITORY with the repository owner and repository name.
A request can also specify query parameters to filter alerts by state or control pagination. Check the API's current documentation for supported parameters, permission requirements, and response details before deploying the integration.
Example Using GitHub CLI
GitHub CLI can call the REST API without requiring you to write a separate HTTP client.
gh api repos/OWNER/REPOSITORY/dependabot/alerts \
--paginate \
--jq '.[] | {
number,
state,
package: .dependency.package.name,
ecosystem: .dependency.package.ecosystem,
severity: .security_vulnerability.severity,
vulnerable_range: .security_vulnerability.vulnerable_version_range,
patched_version: .security_vulnerability.first_patched_version.identifier
}'
Replace OWNER and REPOSITORY with the actual values.
The --paginate option requests subsequent pages when more results are available. The --jq expression selects relevant fields from each returned alert.
The example assumes the response includes the referenced fields. In real responses, some values may be missing or null, so automation should handle absent fields without failing.
Retrieve Only Open Alerts
For a report focused on unresolved vulnerabilities, you can filter the results by alert state.
gh api "repos/OWNER/REPOSITORY/dependabot/alerts?state=open" \
--paginate \
--jq '.[] | {
number,
package: .dependency.package.name,
severity: .security_vulnerability.severity,
vulnerable_range: .security_vulnerability.vulnerable_version_range,
patched_version: .security_vulnerability.first_patched_version.identifier
}'
This query focuses on open alerts, which are usually the most relevant when preparing a remediation report.
However, an open alert is not necessarily a newly introduced vulnerability. It may have existed for some time, so a team should compare results with previous reports when tracking newly discovered issues.
Build a Dependency Vulnerability Report With PowerShell
For teams that need a reusable report, PowerShell can retrieve the API response and extract package information.
The following example requests Dependabot alerts for one repository and produces a summary.
$Owner = "YOUR_ORGANIZATION"
$Repo = "YOUR_REPOSITORY"
$Token = $env:GITHUB_TOKEN
if ([string]::IsNullOrWhiteSpace($Token)) {
throw "Set the GITHUB_TOKEN environment variable first."
}
$Headers = @{
Accept = "application/vnd.github+json"
Authorization = "Bearer $Token"
"X-GitHub-Api-Version" = "<SUPPORTED_API_VERSION>"
}
$Uri = "https://api.github.com/repos/$Owner/$Repo/dependabot/alerts?state=open&per_page=100"
$Alerts = Invoke-RestMethod `
-Method Get `
-Uri $Uri `
-Headers $Headers
$Report = foreach ($Alert in $Alerts) {
$Vulnerability = $Alert.security_vulnerability
$Package = $Alert.dependency.package
[PSCustomObject]@{
AlertNumber = $Alert.number
State = $Alert.state
Package = $Package.name
Ecosystem = $Package.ecosystem
Severity = $Vulnerability.severity
VulnerableRange = $Vulnerability.vulnerable_version_range
FirstPatchedVersion = $Vulnerability.first_patched_version.identifier
CreatedAt = $Alert.created_at
}
}
$Report |
Sort-Object Severity, Package |
Format-Table -AutoSize
Replace the owner and repository placeholders with the actual values. Set the API version to one currently supported by GitHub.
This example retrieves one page of results, up to the specified page size. If the repository has more alerts, the script must follow the API's pagination links or use another pagination-aware implementation to retrieve all results.
Also note that sorting severity values alphabetically does not necessarily sort them from most severe to least severe. For a production report, define an explicit severity ranking rather than relying on alphabetical order.
The script is intended for reporting. It does not automatically upgrade packages or dismiss alerts.
Identify the Actual Package Version Used by the Application
Dependabot alerts describe a vulnerable dependency, but developers still need to determine which version the application resolves.
A package may be referenced directly in a project file or introduced through another dependency.
Check .NET Dependencies
For a .NET application, inspect the project file and resolved dependency information.
For example:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Example.Library"
Version="2.2.0" />
</ItemGroup>
</Project>
This project file illustrates a direct package reference. The package name and version are examples only.
You can inspect resolved package information with the .NET CLI:
dotnet list package --include-transitive
The command helps identify direct and transitive dependencies in supported project configurations. Check the syntax supported by your installed .NET SDK, because package-listing commands can vary across SDK versions.
If the project uses a NuGet lock file, inspect the resolved version recorded there as well.
Direct and Transitive Dependencies
A direct dependency is explicitly referenced by your project. A transitive dependency is introduced through another package.
For example, your application might reference Package A, which depends on Package B. If Package B has a vulnerability, the application may be affected even though Package B does not appear directly in the project file.
When investigating an alert, identify which dependency introduced the vulnerable package and determine whether a safe update is available.
Do not assume that changing a direct package version will always resolve a transitive vulnerability. Review the complete dependency graph and the version constraints imposed by other packages.
Upgrade Vulnerable Dependencies Safely
Once you have identified the affected package and patched version, plan the update.
Start by reviewing the package's compatibility requirements and release information. Determine whether the fix is available in the current supported release line or whether the application needs a larger upgrade.
For a .NET project, a package update may look like this:
dotnet add package Example.Library --version 2.4.0
dotnet restore
dotnet build --configuration Release
dotnet test --configuration Release
The package version is illustrative and must be replaced with a verified version appropriate for the actual vulnerability and application.
These commands update the package reference, restore dependencies, build the project, and run tests. If the project uses centralized package management, update the relevant central package version instead of changing an individual project file.
After upgrading:
Review the project and lock file changes.
Confirm that the resolved version is outside the affected range.
Run unit and integration tests.
Check for breaking changes and configuration requirements.
Review whether the alert has been marked as fixed.
Confirm that the updated dependency is included in the intended release.
An API report can identify a possible fix, but the package manager and the application's test suite help verify that the change is effective.
Automate Dependabot Reporting in GitHub Actions
A scheduled workflow can retrieve alert information and generate a report for a security review.
For example, an organization might run a weekly job that checks selected repositories and produces a list of unresolved high-severity vulnerabilities.
The workflow should use a token with the minimum permissions needed to read Dependabot alerts. It should not grant write permissions unless the automation genuinely needs to modify repository state.
A basic workflow can run a reporting script on a schedule or through a manual trigger.
name: Dependency Security Report
on:
workflow_dispatch:
schedule:
- cron: '0 6 * * 1'
permissions:
contents: read
jobs:
report:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up GitHub CLI
run: gh --version
- name: Retrieve Dependabot alerts
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh api "repos/${GITHUB_REPOSITORY}/dependabot/alerts?state=open" \
--paginate \
--jq '.[] | [
.number,
.dependency.package.name,
.security_vulnerability.severity,
.security_vulnerability.vulnerable_version_range
] | @tsv'
This example demonstrates retrieval, not a complete reporting system. The action reference is shown as a readable version tag; pin it to a verified full commit SHA if required by your repository's security policy.
The workflow's permissions and token access must be sufficient for the Dependabot alerts endpoint. If the built-in token cannot access the required information in your configuration, use an appropriately authorized GitHub App or another approved credential.
The scheduled time uses GitHub Actions cron syntax and is interpreted in UTC. Adjust it to your team's reporting schedule.
For production use, consider saving the output as an artifact, generating a structured report, comparing it with previous results, and notifying the responsible team when new high-risk alerts appear. Avoid printing secrets or sensitive repository information unnecessarily.
Common Mistakes to Avoid
Comparing Versions as Plain Text
Version identifiers are not ordinary strings. For example, lexical string comparison may not produce the correct order for versions such as 2.9.0 and 2.10.0.
Use the package ecosystem's versioning rules and the advisory's affected range.
Assuming the First Patched Version Is Always a Drop-In Replacement
A patched version may introduce breaking changes or require a newer runtime.
Check compatibility before upgrading and run the appropriate tests.
Ignoring Transitive Dependencies
A vulnerable package may be introduced indirectly through another library.
Inspect the resolved dependency graph instead of looking only at direct package references.
Retrieving Only the First Page
The API may return results across multiple pages. A report that reads only the first page can miss vulnerabilities.
Use pagination and verify that the complete result set has been retrieved.
Treating Every Open Alert as a New Vulnerability
An alert may have existed for weeks or months.
Compare current results with historical reports if your goal is to identify newly introduced or newly discovered issues.
Automatically Dismissing Alerts
Closing an alert without verifying the remediation can hide a real problem.
Confirm that the affected dependency is no longer vulnerable or document the reason for an authorized dismissal.
Best Practices for Dependency Security Reporting
A dependable process for reviewing Dependabot alerts should include the following practices:
Retrieve alerts through an appropriately authorized API token.
Record the package name, ecosystem, affected range, severity, and patched version.
Follow pagination to collect all relevant alerts.
Compare alert data with the application's resolved dependency graph.
Distinguish direct dependencies from transitive dependencies.
Verify the patched version and compatibility before upgrading.
Run builds, tests, and relevant security checks after remediation.
Track unresolved alerts and assign remediation owners.
Compare reports over time to identify newly introduced risks.
Avoid automatically dismissing alerts without technical evidence.
For larger organizations, consider centralizing reporting across repositories. Keep repository access limited to the repositories the reporting process needs, and protect the resulting reports according to their sensitivity.
Advantages and Limitations of the Dependabot Alerts API
The API makes it possible to collect dependency vulnerability information without manually opening every repository. Teams can generate reports, compare alerts across repositories, and integrate dependency security into existing dashboards and workflows.
It also helps connect vulnerability information with remediation processes by exposing package details and version information where available.
However, an alert report is not a complete security assessment. It may not establish whether the vulnerable code path is reachable, whether application-specific mitigations exist, or whether a dependency update is compatible with the application.
The API also depends on the vulnerability information available to GitHub and the repository's security configuration.
Use alert data as an input to a broader dependency management process, not as a replacement for application testing and security review.
Summary
The GitHub Dependabot alerts API helps development teams identify vulnerable dependencies and determine which packages require investigation.
By retrieving alert information, reviewing vulnerable version ranges, checking patched-version details, and comparing results with the application's resolved dependency graph, teams can create a more reliable remediation process.
Use GitHub CLI, PowerShell, or GitHub Actions to automate reporting, but account for pagination, token permissions, missing fields, and version-specific behavior. After upgrading a dependency, restore packages, build the application, run tests, and confirm that the vulnerable version is no longer used.
The objective is to turn dependency alerts into actionable security work. A well-designed process helps teams identify affected packages, prioritize remediation, and verify that the fix works before the updated application reaches production.
Join the conversation! Your thoughts help the community grow.