Nucleaus is built on graphQL for API use

graphQL queries can be used to retrieve data and set parameters in the Nucleaus platform. Its simplicity and ease of use are a perfect fit for collecting information from the platform to be consumed by a variety of use cases.

Queries can be executed directly in the Nucleaus console at https://console.nucleaus.com/api-playground. The API playground also provides a built-in documentation explorer for the GraphQL schema. Once you have crafted a query that gets the data or performs the action you want, the query can also be run from any tool that can POST to the GraphQL URL https://graphql.nucleaus.com/graphql.

Example query #

This Query in graphQL will produce the first 10 repositories that you have access to from the latest scan along with vulnerability count and by severity. The JSON output example below can be ingested in any system such as Slack, email or Splunk to surface outside of the console this information

query MyRepositories($tenantId: ID!) {
  tenant(id: $tenantId) {
    repositoriesConnection (first: 10, after: null) {
      edges {
        node {
          _id: url
          name
          latestScan {
            summary {
              vulnerabilityCount
              vulnerabilityCountBySeverity {
                critical
                high
                medium
                low
                }
              }
            }
          }
        }
        pageInfo {
          hasNextPage
          startCursor
        }
      }
    }
  }
}

The output from this query would look like 10 lines of this:

"node": {
  "_id": "https://bitbucket.org/nucleaus/flaming-security-mistake.git",
  "name": "Security Mistake",
  "latestScan": {
    "summary": {
      "vulnerabilityCount": 55,
      "vulnerabilityCountBySeverity": {
        "critical": 4,
        "high": 16,
        "medium": 12,
        "low": 23
      }
    }
  }
}

Executing a query using POST requests #

1. Create an API access key #

From the API Access page in the console, click the “Create New API Access”:

Each API access key is assigned a role and set of teams, just like a console user. This allows you to limit the scope of access for that specific API key. Fill in the form with the necessary values and click “Save”.

Your newly created API key will appear in the list of access keys. Click the “View” button to view the access key values.

You can copy the hidden values by clicking the copy to clipboard button, or reveal the value and copy them manually. You will need the “Client ID” and “Client Secret” values.

Once you have both the client ID and secret values for your API access token, you can re-use them to interact with the API. This step only needs to be performed once. Protect these values as they allow access to perform actions on your Nucleaus account,. Do not commit the values to git repositories. Follow best practices for secrets management for your CICD pipeline tool(s) of choice.

2. Acquire a Bearer token #

The client ID and secret values obtained in the previous step are used to request a Bearer token. This token is short-lived, and will expire after a short time (currently this is configured to expire after 24 hours). However, you will need to cache the Bearer token for the duration of your script. Making too many requests for a Bearer token in a short period of time will cause your requests to be rate limited.

#!/bin/sh
# Note: The bash script relies on the jq utility to create/read JSON strings.
# It is becoming commonly available, but if it is not yet available on your
# system view https://stedolan.github.io/jq/download/ for instructions to
# install it.
REQUEST_BODY=$(
  # If CLIENT_ID and CLIENT_SECRET are defined as environment variables, you
  # can skip the next two lines
  CLIENT_ID="********************************" \
  CLIENT_SECRET="********************************" \
  jq -n '
    {
      grant_type: "client_credentials",
      audience: "https://graphql.nucleaus.com",
      client_id: env.CLIENT_ID,
      client_secret: env.CLIENT_SECRET,
    }
  '
)

RESPONSE=$(
  curl -s \
    -H "Content-Type: application/json" \
    -d "$REQUEST_BODY" \
    https://nucleaus.auth0.com/oauth/token
)

ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.access_token')
echo $ACCESS_TOKEN

The command will return a JSON object that contains the property “access_token”. This is the value needed to authorize the GraphQL requests, and should be cached until it expires.

3. POST GraphQL query and parse JSON response #

Now that you have the Bearer token to authorize requests to the GraphQL endpoint, queries can be posted and JSON will be returned.

#!/bin/sh
# This is the access token obtained in the previous step
ACCESS_TOKEN='********************************'

# Your Nucleaus tenant ID is used as a variable in many queries, and can
# be found in the Nucleaus console API playground at
# https://console.nucleaus.com/api-playground
export TENANT_ID='********************************'

RESPONSE=$(curl -s \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d "$(jq -n '
    {
      variables: {
        tenantId: env.TENANT_ID,
      },
      query: "
        query ($tenantId: ID!) {
          tenant(id: $tenantId) {
            repositoriesConnection (first: 10, after: null) {
              edges {
                node {
                  _id: url
                  name
                  latestScan {
                    summary {
                      vulnerabilityCount
                      vulnerabilityCountBySeverity {
                        critical
                        high
                        medium
                        low
                      }
                    }
                  }
                }
              }
              pageInfo {
                hasNextPage
                startCursor
              }
            }
          }
        }
      ",
    }
  ')" \
  https://graphql.nucleaus.com/graphql
)

# Output response data
echo "$RESPONSE" | jq '.data.tenant'

# Use jq to sum the returned number of critical vulnerabilities
echo "$RESPONSE" | jq '[.data.tenant.repositoriesConnection.edges[].node.latestScan | select(.summary != null) | .summary.vulnerabilityCountBySeverity.critical] | add'