Nucleaus is built on GraphQL for API use

Example query
Executing a query using POST requests

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

GraphQL Query

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:

JSON Output

"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

1Create an API access key

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

"Create New API Access" button location screenshot

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".

2Acquire 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.

Bash Script

#!/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.

3POST 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.

Bash Script

#!/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'

Nucleaus is built on GraphQL for API use