api-references.md

Additional References

Code scanning API

The code scanning REST API can be used to retrieve information or modify existing information. Explore the options here.

Secret scanning API

The secret scanning API lets you retrieve and update secret scanning alerts from a private repository. Explore the options here

Automating Dependabot

For the Dependabot service, we have both REST and GraphQL endpoints that allow us to configure aspects and retrieve information. This can both be used for managing individual repositories at scale or export vulnerability information into other systems used to manage this information in your organization. We've included a postman collection in this repository for you to explore.

Note The REST API signals a 404 when you client isn't properly authenticated to limit disclosure of private repositories as outlined here. This is the same status code that is returned if features are not enabled.

1. Start by creating a Personal Access Token with the repo scope and store it for use (e.g., in a Postman environment variable).

2. For your repo, determine if vulnerability alerts are enabled.

   Hints

   • Check if vulnerability alerts are enabled for a repository
   • Since this API is currently available for developers preview we need to use the header Accept: application/vnd.github.dorian-preview+json

3. Disable and Enable security updates

   Hints

   • Enable automated security fixes

Solutions

1. Determining if vulnerability alerts are enabled

   curl --location --request GET 'https://api.github.com/repos/<owner>/<repository>/vulnerability-alerts' \
   --header 'Accept: application/vnd.github.dorian-preview+json' \
   --header 'Authorization: Bearer <insert your PAT>'

2. Disabling and enable security updates

   curl --location --request DELETE 'https://api.github.com/repos/<owner>/<repository>/vulnerability-alerts' \
   --header 'Accept: application/vnd.github.dorian-preview+json' \
   --header 'Authorization: Bearer <insert your PAT>'
   
   curl --location --request PUT 'https://api.github.com/repos/<owner>/<repository>/vulnerability-alerts' \
   --header 'Accept: application/vnd.github.dorian-preview+json' \
   --header 'Authorization: Bearer <insert your PAT>'

Next, we are going to use the GraphQL API to retrieve information on vulnerable dependencies in our repository.

1. Retrieve the securityVulnerability objects for your repository.

   If you receive this response, then you need to add the scope read:org to your Personal Access Token.

    {
        "data": {
            "viewer": {
                "organization": null
            }
        }
    }

   Hints

   1. GraphQL is introspective; you can query an object's schema with

      query {
          __type(name: "SecurityVulnerability") {
              name
              kind
              description
              fields {
                  name
              }
          }
      }

   2. A SecurityVulnerability object can be accessed via the RepositoryVulnerabilityAlert object in a Repository object, which itself resides in an Organization object.

Solution

query VulnerabilityAlerts($org: String!, $repo: String!){
  viewer {
    organization(login: $org) {
      repository(name: $repo) {
        name
        vulnerabilityAlerts(first: 10) {
          nodes {
            securityVulnerability {
              advisory {
                ghsaId
                description
              }
              package {
                name
                ecosystem
              }
              severity
              firstPatchedVersion {
                identifier
              }
              vulnerableVersionRange
            }
          }
        }
      }
    }
  }
}

curl --location --request POST 'https://api.github.com/graphql' \
--header 'Authorization: Bearer <insert your PAT>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query VulnerabilityAlerts($org: String!, $repo: String!){\n  viewer {\n    organization(login: $org) {\n      repository(name: $repo) {\n        name\n        vulnerabilityAlerts(first: 10) {\n          nodes {\n            securityVulnerability {\n              advisory {\n                ghsaId\n                description\n              }\n              package {\n                name\n                ecosystem\n              }\n              severity\n              firstPatchedVersion {\n                identifier\n              }\n              vulnerableVersionRange\n            }\n          }\n        }\n      }\n    }\n  }\n}","variables":{"org":"<org-name>","repo":"<repository-name>"}}'