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:
actionis the exception type:RISK_ACCEPTED,WORKAROUND,FALSE_POSITIVE, orDISABLE. 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:
cveMrnsfor CVEs,advisoryMrnsfor vendor advisories,queryMrnsfor checks, orcontrolMrnsfor compliance controls. ThefindingMrnvalues from the findings queries go in these lists. validUntilis 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.nameis optional.justificationis 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: truealso returns the exceptions set on individual assets in the space. - Access: any role that can view the space, such as Viewer.
- Pagination: while
hasNextPageistrue, add"after": "END_CURSOR"to the variables, using the previous page'sendCursor.
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
- Create Tickets: open a ticket for findings that need a fix.
Last updated on