Skip to Content
GraphQL API

Create and Review Exceptions with the Mondoo API

Create exceptions for vulnerabilities and checks, list exceptions waiting for review, and approve or reject them with the Mondoo GraphQL API.

An exception tells Mondoo that you've decided how to handle a finding, so it stops affecting risk scores. To learn how exceptions work, including the space settings that control approval, read Exceptions.

Each recipe is a complete curl command. To run them, set MONDOO_API_TOKEN and install jq as described in Make your first request. If your organization is in the EU region, replace us.api.mondoo.com with eu.api.mondoo.com.

Create an exception

Use this mutation to accept the risk of a vulnerability across a whole space until a date you choose. Get the vulnerability's MRN from the vulnerabilities list.

QUERY='
mutation CreateException($input: ExceptionMutationInput!) {
  createException(input: $input) {
    exceptionGroup {
      mrn
      status
      validUntil
    }
  }
}'
VARIABLES='{
  "input": {
    "scopeMrn": "//captain.api.mondoo.app/spaces/YOUR_SPACE_ID",
    "action": "RISK_ACCEPTED",
    "cveMrns": ["//vadvisor.api.mondoo.app/cves/CVE-2024-3094"],
    "name": "Accept CVE-2024-3094 until the Q1 upgrade",
    "justification": "The affected package is not reachable from the network. Upgrade planned for Q1.",
    "validUntil": "2027-03-31T00:00:00Z"
  }
}'

curl -s https://us.api.mondoo.com/query \
  -H "Authorization: Bearer $MONDOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg query "$QUERY" --argjson variables "$VARIABLES" '{query: $query, variables: $variables}')" | jq
  • Scope: a space MRN for a space-wide exception, or an asset MRN for an exception on one asset.
  • Access: the Editor or Owner role, or another role with the Exception Requester or Exception Manager permission. To see every role, read Roles and permissions.

Set these fields in input:

  • action is the exception type: RISK_ACCEPTED, WORKAROUND, FALSE_POSITIVE, or DISABLE. They match the four exception types in the Mondoo App.
  • Put the MRNs of the findings to except in the list that matches their kind: cveMrns for CVEs, advisoryMrns for vendor advisories, queryMrns for checks, or controlMrns for compliance controls. The findingMrn values from the findings queries go in these lists.
  • validUntil is when the exception expires, as an RFC 3339 timestamp. Leave it out for an exception that doesn't expire, if the space allows non-expiring exceptions.
  • name is optional. justification is the reason that reviewers see.

If the space requires exception approvals, the new exception has the status NEW and doesn't take effect until someone approves it.

List exceptions waiting for review

Use this query to find the exceptions in a space that are waiting for approval, for example to post a daily reminder to reviewers.

QUERY='
query PendingExceptions($input: ListExceptionGroupsInput!, $after: String) {
  listExceptionGroups(input: $input, first: 50, after: $after) {
    totalCount
    edges {
      node {
        mrn
        title
        action
        status
        justification
        validUntil
        createdAt
        author {
          name
          email
        }
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}'
VARIABLES='{
  "input": {
    "scopeMrn": "//captain.api.mondoo.app/spaces/YOUR_SPACE_ID",
    "includeChildScopes": true,
    "filter": { "statuses": ["NEW"] }
  }
}'

curl -s https://us.api.mondoo.com/query \
  -H "Authorization: Bearer $MONDOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg query "$QUERY" --argjson variables "$VARIABLES" '{query: $query, variables: $variables}')" | jq
  • Scope: a space MRN. includeChildScopes: true also returns the exceptions set on individual assets in the space.
  • Access: any role that can view the space, such as Viewer.
  • Pagination: while hasNextPage is true, add "after": "END_CURSOR" to the variables, using the previous page's endCursor.

To list exceptions in other states, change statuses. For example, ["APPROVED"] returns approved exceptions, and ["EXPIRED"] returns the ones whose time limit has passed. To see whether an exception currently applies, add the isActive field to the query.

Approve or reject an exception

Use this mutation to review an exception. Get its MRN from the list of exceptions waiting for review. To reject it instead, set action to REJECTED.

QUERY='
mutation ReviewException($input: ExceptionReviewInput!) {
  applyExceptionReview(input: $input)
}'
VARIABLES='{
  "input": {
    "exceptionMrn": "EXCEPTION_MRN",
    "action": "APPROVED"
  }
}'

curl -s https://us.api.mondoo.com/query \
  -H "Authorization: Bearer $MONDOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg query "$QUERY" --argjson variables "$VARIABLES" '{query: $query, variables: $variables}')" | jq
  • Access: the Owner role, or another role with the Exception Reviewer or Exception Manager permission. The Editor role can't review exceptions. To see every role, read Roles and permissions.

The mutation returns true when the review is recorded. Unless the space allows users to approve their own exceptions, the identity that reviews an exception must be different from the one that created it. To approve exceptions that a script creates, review them with a different token or in the Mondoo App.

Next steps

Last updated on

On this page