Checks

This endpoint allows you to collect checks for specified accounts.

There is a 10k limit to the maximum number of overall results that can be returned. Paging will not work for higher than this limit. To fetch larger numbers, segment your requests using account and region filtering. On larger accounts, filter requests per account, per region, per service.

The consistentPagination query parameter ensures that no duplicate checks are returned when paginating with the API. Setting this to false increases performance but could also introduce duplicates.

The filter query parameter is the basis for filtering.

For example, the following is a request for a page of checks filtered by service EC2:

GET /checks?accountIds=r1gyR4cqg&page[size]=100&page[number]=0&filter[services]=EC2

Multiple filter values can be combined in a comma-separated list. For example the following is a request for a page of checks in us-west-2 or us-west-1 regions:

GET /checks?accountIds=r1gyR4cqg&page[size]=100&page[number]=0&filter[regions]=us-west-1,us-west-2

Furthermore, multiple filters can be applied to a single request. For example, the following is a request to get checks for us-west-2 region when the status of the check is SUCCESS, and it's for EC2 or IAM service in security category with HIGH risk level

GET /checks?accountIds=r1gyR4cqg&page[size]=100&page[number]=0&filter[regions]=us-west-2&filter[statuses]=SUCCESS&filter[categories]=security&filter[riskLevels]=HIGH&filter[services]=EC2,IAM

The table below give more information about filter options:

Example Request:

curl -g -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/checks?accountIds=r1gyR4cqg&page[size]=100&page[number]=0&filter[regions]=us-west-2&filter[ruleIds]=EC2-001,EC2-002&filter[statuses]=SUCCESS&filter[categories]=security&filter[riskLevels]=HIGH&filter[services]=EC2&filter[createdDate]=1502572157914

Example Response:

Note the size of this response can be quite large and the example below is purposefully truncated.

The check property providerResourceId is only returned for a limited amount of AWS rules. This property represents the AWS ARN of the related resource.

{
  "data": [
    {
      "type": "checks",
      "id": "ccc:94qQ4DnOB:AG-003:APIGateway:us-east-1:pl63negesk",
      "attributes": {
        "region": "us-east-1",
        "status": "FAILURE",
        "risk-level": "LOW",
        "pretty-risk-level": "Low",
        "message": "API Security Automations - WAF Bad Bot API has stages without active tracing enabled",
        "resource": "pl63negesk",
        "descriptorType": "apigateway-restapi",
        "link-title": "myApigateway-eastus",
        "resourceName": "API Gateway REST API",
        "last-modified-date": 1561697456359,
        "created-date": 1561697456359,
        "categories": ["operational-excellence"],
        "last-updated-date": null,
        "failure-discovery-date": 1561697456359,
        "ccrn": "ccrn:aws:94qQ4DnOB:APIGateway:us-east-1:pl63negesk",
        "tags": [],
        "cost": 0,
        "waste": 0,
        "rule-title": "Tracing Enabled",
        "link": "https://us-east-1.console.aws.amazon.com/apigateway/home?region=us-east-1#/apis/pl63negesk/resources",
        "provider": "aws",
        "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/APIGateway/tracing.html#B1nHYYpwx",
        "providerResourceId": "arn:aws:apigateway:us-west-1::/restapis/pl63negesk/*",
        "service": "APIGateway"
      },
      "relationships": {
        "rule": {
          "data": {
            "type": "rules",
            "id": "AG-003"
          }
        },
        "account": {
          "data": {
            "type": "accounts",
            "id": "94qQ4DnOB"
          }
        }
      }
    }
  ],
  "meta": {
    "total": 714,
    "page-number": 0,
    "page-size": 100
  }
}

Example Request:

curl -g -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/checks?accountIds=e13vR4c3g&page[size]=100&page[number]=0&&filter[regions]=eastus&filter[ruleIds]=KeyVault-004&filter[services]=KeyVault&filter[statuses]=SUCCESS&filter[categories]=security&filter[riskLevels]=HIGH

Example Response:

{
  "data": [
    {
      "type": "checks",
      "id": "ccc:5pgWNtDMj:KeyVault-004:KeyVault:eastus:/subscriptions/8dfbsdfe-we13-46we-9963-188128793ef40/resourceGroups/myDevResources/providers/Microsoft.KeyVault/vaults/myDevKeyVault-eastus",
      "attributes": {
        "region": "eastus",
        "status": "FAILURE",
        "risk-level": "MEDIUM",
        "pretty-risk-level": "Medium",
        "message": "AuditEvent logging is not enabled for Azure Key Vault 'myDevKeyVault-eastus'",
        "resource": "/subscriptions/8dfbsdfe-we13-46we-9963-188868997f40/resourceGroups/myDevResources/providers/Microsoft.KeyVault/vaults/myDevKeyVault-eastus",
        "descriptorType": "keyvault-vaults",
        "link-title": "myDevKeyVault-eastus",
        "resourceName": "KeyVault Vault",
        "last-modified-date": 1588560354122,
        "created-date": 1588560354122,
        "categories": ["security"],
        "last-updated-date": null,
        "failure-discovery-date": 1588560354122,
        "ccrn": "ccrn:azure:5pgWNtDMj:KeyVault:eastus:/subscriptions/8dfbsdfe-we13-46we-9963-188868997f40/resourceGroups/myDevResources/providers/Microsoft.KeyVault/vaults/myDevKeyVault-eastus",
        "tags": [],
        "cost": 0,
        "waste": 0,
        "rule-title": "Enable AuditEvent Logging for Azure Key Vaults",
        "link": "https://portal.azure.com/#resource//subscriptions/8dfbsdfe-we13-46we-9963-188868997f40/resourceGroups/myDevResources/providers/Microsoft.KeyVault/vaults/myDevKeyVault-eastus",
        "provider": "azure",
        "resolution-page-url": "https://wdevelopment.cloudconformity.com/knowledge-base/azure/KeyVault/enable-audit-event-logging-for-azure-key-vaults.html#Jo29j"
      },
      "relationships": {
        "rule": { "data": { "type": "rules", "id": "KeyVault-004" } },
        "account": { "data": { "type": "accounts", "id": "dlkf19" } }
      }
    }
  ],
  "meta": { "total": 1, "page-number": 0, "page-size": 100 }
}

This endpoint is used to create a custom checks. You may pass one check or an array of checks in the JSON body.

IMPORTANT:    Some guidelines about using this endpoint:

1. Checks are created as long as your inputs are valid. The onus is on you to ensure the checks you enter are meaningful and useful.
2. Each check object you enter will require a check.relationships.account. If you provide an account which you don't have WRITE access to, the check will not be saved.
3. Check Ids are constructed from the parameters entered and follow the format:
   1. ccc:accountId:ruleId:service:region:resourceId
   2. If you add a check with the same accountId, ruleId, service, region, AND resourceId as another existing check in the database, this new check WILL write over the existing check.
   3. Since resource is an optional attribute, checks entered without resource will not have the resourceId part of the check Id.
4. Time-to-live (TTL):
   1. Custom Checks support configuration of a time-to-live (TTL). TTL allows users to automatically delete checks at a set date/time.
   2. TTL is defined in epoch milliseconds and should be set as a time in the future, e.g. January 1 2023 1:00:00 AM GMT -> "ttl": 1672534800000
   3. The maximum configurable TTL is the current time plus 12 months.
   4. If TTL is not defined, the TTL value defaults to 12 months from the current time.
   5. TTL is mutable when updating an existing custom check.
   6. Custom Checks whose TTL has passed are deleted every 30 minutes via a background process.

This endpoint allows you to get the details of the specified check.

Note:

The Cloud Conformity ID of a check for an Azure or AWS account may contain the forward slash character / which needs to be replaced with the encoded character %2F when passed in the request URL.

The filter query parameter is the basis for filtering.

For example, the following is a request for a check with its 10 most recent notes:

GET /checks/ccc:r2gyR4cqg:IAM-017:IAM:global:groups-test&filter[notes]=true&filter[notesLength]=10

The table below give more information about filter options:

Example Request to view details of a check for an AWS account:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
'https://us-west-2-api.cloudconformity.com/v1/checks/ccc:r2gyR4cqg:IAM-017:IAM:global:groups-test'

Example Response:

{
    "data": {
        "type": "checks",
        "id": "ccc:r2gyR4cqg:IAM-017:IAM:global:groups-test",
        "attributes": {
            "region": "global",
            "status": "FAILURE",
            "risk-level": "LOW",
            "pretty-risk-level": "High",
            "message": "IAM Group test contains no user",
            "last-modified-date": 1500166639466,
            "created-date": 1500166639466
            "last-updated-date": 1500166639466,
            "failure-discovery-date": 1498910777689,
            "last-updated-by": "SYSTEM",
            "resolved-date": 1518409298274,
            "resolved-by": null,
            "ccrn": "ccrn:aws:r1gyR4cqg:IAM:global:groups-test",
            "extradata": null,
            "tags": [],
            "cost": 0,
            "waste": 0,
            "not-scored": false,
            "ignored": null,
            "rule-title": "Password Policy Present",
            "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/IAM/unused-iam-group.html#",
            "providerResourceId": "arn:aws:iam::1234567890:group/groups-test",
            "service": "IAM"
        },
        "relationships": {
            "rule": {
                "data": {
                    "type": "rules",
                    "id": "IAM-017"
                }
            },
            "account": {
                "data": {
                    "type": "accounts",
                    "id": "r1gyR4cqg"
                }
            }
        }
    }
}

Example Request to view details of a check for an Azure account with ID
ccc:r2gyR4cqg:SecurityCenter-008:SecurityCenter:global:/subscriptions/9f7bcadb-3626-46dx-9917-1397384797f40/providers/Microsoft.Authorization/policyAssignments/SecurityCenterBuiltIn:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
'https://us-west-2-api.cloudconformity.com/v1/checks/ccc:r2gyR4cqg:SecurityCenter-008:SecurityCenter:global:%2Fsubscriptions%2F9f7bcadb-3626-46dx-9917-1397384797f40%2Fproviders%2FMicrosoft.Authorization%2FpolicyAssignments%2FSecurityCenterBuiltIn'

This endpoint is used to either update one custom check OR suppress/unsuppressed one normal check.

IMPORTANT:    Some guidelines about using this endpoint:

1. When updating a custom check, you must leave region, resource, service attributes and relationship.account and relationship.rule unchanged. These are unique identifier parameters for custom checks and must be always present and unchanged once check is created.
2. Suppression of check via this endpoint only works with FAILING checks and not successful checks. Besides, note is required for suppression of a normal check, while it is optional for suppression of a custom check.
3. skipUpdatingEnabledSuppression attribute can be applied to the suppressed check. Boolean. Is not a required attribute. Using skipUpdatingEnabledSuppression: true will prevent updating suppressed and suppressed-until attributes for the suppressed check. Only use if you would like to prevent overwriting enabled suppressed check. Default value for skipUpdatingEnabledSuppression: false.
4. Time-to-live (TTL):
   1. Custom Checks support configuration of a time-to-live (TTL). TTL allows users to automatically delete checks at a set date/time.
   2. TTL is defined in epoch milliseconds and should be set as a time in the future, e.g. January 1 2023 1:00:00 AM GMT -> "ttl": 1672534800000
   3. The maximum configurable TTL is the current time plus 12 months.
   4. If TTL is not defined, the TTL value defaults to 12 months from the current time.
   5. TTL is mutable when updating an existing custom check.
   6. Custom Checks whose TTL has passed are deleted every 30 minutes via a background process.

Note: the Cloud Conformity ID of a check for an Azure or AWS account may contain the forward slash character / which needs to be replaced with the encoded character %2F when passed in the request URL. e.g to update a check for an Azure account with the ID: ccc:r2gyR4cqg:SecurityCenter-008:SecurityCenter:global:/subscriptions/9f7bcadb-3626-46dx-9917-1397384797f40/providers/Microsoft.Authorization/policyAssignments/SecurityCenterBuiltIn the URL in the request body should be: https://us-west-2-api.cloudconformity.com/v1/checks/ccc:r2gyR4cqg:SecurityCenter-008:SecurityCenter:global:%2Fsubscriptions%2F9f7bcadb-3626-46dx-9917-1397384797f40%2Fproviders%2FMicrosoft.Authorization%2FpolicyAssignments%2FSecurityCenterBuiltIn

Example request for updating a custom check:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
    "data": {
        "type": "checks",
        "attributes": {
            "region": "us-west-2",
            "resource": "sg-956d00ea",
            "risk-level": "VERY_HIGH",
            "status": "FAILURE",
            "service": "EC2",
            "categories": ["security"],
            "rule-title": "Custom Rule about EC2 SGs",
            "message": "Updated message about this check",
            "resolution-page-url": "https://test.com/custom-001.html#",
            "extradata": [
                {
                    "label": "This will show up on the UI",
                    "name": "nameForReference",
                    "type": "META",
                    "value": "string or number or boolean"
                },
                {
                    "label": "It is good to be descriptive",
                    "name": "forReference",
                    "type": "META",
                    "value": "hello world!"
                }
            ],
            "tags": ["key0::value0", "key1::value1"],
            "ttl": 1672534800000
        },
        "relationships": {
            "rule": {
                "data": {
                    "type": "rules",
                    "id": "CUSTOM-001"
                }
            },
            "account": {
                "data": {
                    "type": "accounts",
                    "id": "H19NxM15-"
                }
            }
        }
    }
}' \
https://us-west-2-api.cloudconformity.com/v1/checks/ccc:H19NxM15-:CUSTOM-001:EC2:us-west-2:sg-956d00ea

Example Response:

{
    "data": {
        "type": "checks",
        "id": "ccc:H19NxM15-:CUSTOM-001:EC2:us-west-2:sg-956d00ea",
        "attributes": {
            "region": "us-west-2",
            "status": "FAILURE",
            "service": "EC2",
            "risk-level": "VERY_HIGH",
            "pretty-risk-level": "Very High",
            "rule-title": "Custom Rule about EC2 SGs",
            "message": "Updated message about this check",
            "resource": "sg-956d00ea",
            "categories": ["security"],
            "last-modified-date": 1526566995282,
            "created-date": 1521660152755,
            "failure-discovery-date": 1521660152755,
            "resolution-page-url": "https://test.com/custom-001.html#",
            "extradata": [
                {
                    "label": "This will show up on the UI",
                    "name": "nameForReference",
                    "type": "META",
                    "value": "string or number or boolean"
                },
                {
                    "label": "It is good to be descriptive",
                    "name": "forReference",
                    "type": "META",
                    "value": "hello world!"
                }
            ],
            "tags": ["key0::value0", "key1::value1"],
            "ttl": 1672534800000
        },
        "relationships": {
            "rule": {
                "data": {
                    "type": "rules",
                    "id": "CUSTOM-001"
                }
            },
            "account": {
                "data": {
                    "type": "accounts",
                    "id": "H19NxM15-"
                }
            }
        }
    }
}

Example request for suppressing a check:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
    "data": {
        "type": "checks",
        "attributes": {
            "suppressed": true,
            "suppressed-until": 1526574705655,
            "skipUpdatingEnabledSuppression": true
        }
    },
    "meta": {
        "note": "suppressed for 1 week, failure not-applicable during project xyz"

    }
}; \

https://us-west-2-api.cloudconformity.com/v1/checks/ccc:H19NxM15:EC2-013:EC2:ap-southeast-2:

Example Response:

{
    "data": {
        "type": "checks",
        "id": "ccc:H19NxM15:Config-001:Config:us-west-2:",
        "attributes": {
            "region": "us-west-2",
            "status": "FAILURE",
            "risk-level": "HIGH",
            "pretty-risk-level": "High",
            "message": "AWS Config is not enabled for us-west-2 region ",
            "last-modified-date": 1526571108174,
            "created-date": 1513472920569,
            "categories": [
                "security"
            ],
            "suppressed": true,
            "last-updated-date": null,
            "failure-discovery-date": 1526571108174,
            "failure-introduced-by": null,
            "resolved-by": null,
            "last-updated-by": null,
            "extradata": null,
            "tags": [],
            "ttl": 1672534800000,
            "cost": 0,
            "waste": 0,
            "suppressed-until": 1526574705655,
            "not-scored": false,
            "rule-title": "AWS Config Enabled",
            "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/Config/aws-config-enabled.html#"
        },
        "relationships": {
            "rule": {
                "data": {
                    "type": "rules",
                    "id": "Config-001"
                }
            },
            "account": {
                "data": {
                    "type": "accounts",
                    "id": "HJtqfslfG"
                }
            }
        }
    }
}

This endpoint allows you to delete the specified check.

This endpoint allows you to get the check evolution statistics.

Note: There are 5 parameters for fetching the check evolution statistics.

   Some guidelines about using this endpoint:

1. If a user provides groupId, accountIds at the same time, the precedence order is groupId, accountIds.
2. If a user does not provide any of groupId, accountIds, the endpoint will show check evolution statistics of user's organisation.
3. If a user does not provide any of from, to, the endpoint will show check evolution statistics with date range from 30 days ago until now.
4. If a user provides to with a date string 2021-05-19T00:00:01 along with timezone Australia/Sydney, the date range will not include the date 2021-05-19 since the UTC time for this is still on 2021-05-18. If a user provides to with a date string 2021-05-19T10:00:01 along with timezone Australia/Sydney, the date range will include the date 2021-05-19.
5. newFailureCount in the response means the number of new failed checks created since the last summary date.
6. newSuccessCount in the response means the number of new succeeded checks created since the last summary date.
7. newCount in the response means the total number of new failed checks and new succeeded checks created since the last summary date.
8. introducedCount in the response means the number of existing failed checks where failures were introduced since the last summary date.
9. checks in the response means the average check count for each bot run in a day.
10. failureCount in the response means the average failure check count for each bot run in a day.
11. successCount in the response means the average success check count for each bot run in a day.
12. resolvedCount in the response means the total number of resolved check count since the last summary date

Example Request to view evolution statistics for a Conformity group:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey 5ZRjUvX9kuyWzbdRVZDumcmowz7GjbeGNa8JRtH59UxWsbU7QexD5JPmuZy4yoVH" \
'https://us-west-2-api.cloudconformity.com/v1/checks/evolution?from=2021-05-19T10:00:01&to=2021-05-20T10:00:01&timezone=Asia/Shanghai&groupId=JdRZBzbRa'

Example Response:

{
    "data": [
        {
            "security": 75,
            "performance-efficiency": 83,
            "reliability": 83,
            "operational-excellence": 78,
            "cost-optimisation": 85,
            "sustainability": 79,
            "date": 1621382400000,
            "checks": 22081,
            "compliance": 73,
            "cost": "480.77",
            "waste": "83.92",
            "newCount": 1489,
            "newFailureCount": 634,
            "newSuccessCount": 855,
            "resolvedCount": 58,
            "introducedCount": 684,
            "successCount": 16758,
            "failureCount": 5323
        },
        {
            "security": 75,
            "performance-efficiency": 83,
            "reliability": 83,
            "operational-excellence": 78,
            "cost-optimisation": 84,
            "sustainability": 79,
            "date": 1621468800000,
            "checks": 21977,
            "compliance": 73,
            "cost": "486.00",
            "waste": "86.00",
            "newCount": 414,
            "newFailureCount": 252,
            "newSuccessCount": 162,
            "resolvedCount": 27,
            "introducedCount": 277,
            "successCount": 16630,
            "failureCount": 5347
        }
    ]
}

This endpoint allows you to replay existing checks through a specified Communication Channel.

This can be useful when you want to bulk-ingest existing checks into a recently created Communication Channel.

This is expected to be a one-time operation as new checks can be forwarded automatically to Communication Channels through automatic notifications.

Note:

• The following Communication Channel's are supported:
  • Jira
  • Zendesk
  • Service Now
  • Webhook
  • AWS SNS
• This endpoint is idempotent for ticketing channels (Jira, Zendesk, and Service Now) and won't duplicate tickets if they already exist. However non-ticketing channels (Webhooks, or AWS SNS) are non-idempotent and will resend checks any time this endpoint is called.
• Only account level Communication Channel's are supported at this time.
• Only users with write access to the specified account (for which the communication setting is configured) can use this endpoint.
• It may take several minutes for checks to appear in your Communication Channel following a successful replay request.

Filtering:

Basic filtering options (see filter in request specification) are provided to allow a subset of checks to be replayed.

Note: Filtering provided in this endpoint is in addition to filtering already configured on the Communication Channel setting.