GuardRails API Usage Guide

Table of Contents

• Pre-Requisites
• Exchange API key for JWT
• How to use the API

Pre-Requisites

To use the GuardRails API, you need to have a GuardRails account and obtained an API key. Note: For on-premise deployments, the GuardRails API is hosted on port 1444, e.g. https://guardrails.your-company.com:1444/swagger.

More information on how to get started can be found here.

Once you setup your GuardRails account you can generate your api key in the user's setting page in the dashboard.

Exchange API Key for JWT

To access the GuardRails api, you must first get a valid GuardRails JWT. In the example below we are assuming that you are using bash and have curl and jq installed on your computer.

Start by adding your API key to a variable (this will be used in the subsequent command).

export API_KEY="" # The api key can be generated on the user account in the GuardRails dashboard.

Next, make a request (using curl) to get a valid JWT from the api key.

JWT_TOKEN=$(curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data "{ \"apiKey\": \"$API_KEY\" }" \
  https://api.guardrails.io/v2/auth | jq -r '.jwtToken')

echo $JWT_TOKEN

Note: The JWT will expire after 6 hours, after that you will have to make a new request to get a new JWT token.

How to use the API

Now that you have a valid JWT you can start calling the GuardRails API. Here's an example of fetching all accounts (user and organizations) associated with the api key.

curl \
  --request GET \
  --header "Authorization: bearer $JWT_TOKEN" \
  "https://api.guardrails.io/v2/accounts"

Now you should see a list of all the accounts associated with the API key.

Click here to get a list of all available API endpoints.

API Cheat Sheet

This assumes you have followed the steps above and will only mention the URLS with placeholder values and examples.

General API calls

# Obtain the an accountID
/v2/accounts

# Obtain the a repositoryID
/v2/repositories?accountId=<ID>&search=<case sensitive name, e.g reponame>

Get all vulnerabilities for a given repo

# Obtain all vulnerabilities that are of the status VULNERABILITY or MARK_AS_VULNERABILITY
# Note: repositoryIds can contain a comma separated list of IDs

/v2/findings?accountId=<accountId>&repositoryIds=<repoID>&branchName=<main>&status=VULNERABILITY,MARK_AS_VULNERABILITY

This returns a JSON containing the count of the results, as well as the categories that were identified including their individual count amongst other details.

# Obtain the actual results for each category
/v2/findings/<ruleId/category>?accountId=<accountId>&offset=0&limit=10&repositoryIds=<repoID>&branchName=<main>&status=VULNERABILITY,MARK_AS_VULNERABILITY

This will return all the details of the results.

Get the source code snippet of a vulnerability

# With the findingIds from the previous example, you can obtain the code from the VCS, GuardRails doesn't store it.
/v2/findings/codeBlock/<Unique FindingId>?accountId=<accountId>

This will return the code snipped in the content key

Get a list of all Repositories and their vulnerability counts

# For all repos in an account
/v2/scans/lastPerRepo?accountId=<accountId>

# For specific repos in an account
/v2/scans/lastPerRepo?accountId=<accountId>&repoIds=<repoIds1,repoIds2>

This will return the time of the last scan, the name of the default branch it scanned and the total count of Vulnerabilities.

Get a list of dependencies

# Obtain all the dependencies for an account
/v2/dependencies?accountId=<accountId>&limit=10&offset=0

# Obtain all dependencies for an account that have vulnerabilities
/v2/dependencies?accountId=<accountId>&hasVulnerability=true&limit=10&offset=0

# Obtain all dependencies for a specific repo
/v2/dependencies?accountId=<accountId>&repoId=<repoId>&limit=10&offset=0

These calls will return details such as name, version, ecosystem, file path and license.

Show which repos use a dependency

# Obtain a list of all repos that use a certain license
/v2/repositories?accountId=<accountId>&license=["MIT"]&limit=10&offset=0

# Obtain a list of all repos that use a certain dependency
/v2/repositories?accountId=<accountId>&useDependencies=t&dependency=ws&pkg_ecosystem=npm&limit=10&offset=0