List All Account 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:
Name | Values |
---|---|
filter[regions] | AWS Regions: global | us-east-2 | us-east-1 | us-west-1 | us-west-2 | ap-south-1 | ap-northeast-2 | ap-southeast-1 | ap-southeast-2 | ap-northeast-1 | ca-central-1 | eu-central-1 | eu-west-1 | eu-west-2 | sa-east-1 Azure Regions: eastasia | southeastasia | centralus | eastus | eastus2 | westus | northcentralus | southcentralus | northeurope | westeurope | japanwest | japaneast | brazilsouth | australiaeast | australiasoutheast | southindia | centralindia | westindia | canadacentral | canadaeast | uksouth | ukwest | westcentralus | westus2 | koreacentral | koreasouth | francecentral | francesouth | australiacentral | australiacentral2 | southafricanorth | southafricawest GCP Regions: asia-east1 | asia-east2 | asia-northeast1 | asia-northeast2 | asia-northeast3 | asia-south1 | asia-southeast1 | asia-southeast2 | australia-southeast1 | europe-central2 | europe-north1 | europe-west1 | europe-west2 | europe-west3 | europe-west4 | europe-west6 | northamerica-northeast1 | southamerica-east1 | us-central1 | us-east1 | us-east4 | us-west1 | us-west2 | us-west3 | us-west4 | global | asia | asia1 | eur3 | eur5 | europe | nam3 | nam6 | nam9 | us For more information about regions, please refer to Cloud Conformity Region Endpoint |
filter[services] | AWS Services: ACM | APIGateway | AccessAnalyzer | AutoScaling | Backup | Budgets | CloudConformity | CloudFormation | CloudFront | CloudTrail | CloudWatch | CloudWatchEvents | CloudWatchLogs | Comprehend | ComputeOptimizer | Config | ConfigService | CostExplorer | DAX | DMS | DocumentDB | DynamoDB | EBS | EC2 | ECR | ECS | EFS | EKS | ELB | ELBv2 | EMR | ElastiCache | ElasticBeanstalk | Elasticsearch | Firehose | Glue | GuardDuty | Health | IAM | Inspector | KMS | Kinesis | Lambda | MQ | Macie | Miscellaneous | Neptune | Organizations | RDS | RTM | Redshift | ResourceGroup | Route53 | Route53Domains | S3 | SES | SNS | SQS | SSM | SageMaker | SecretsManager | SecurityHub | Shield | StorageGateway | Support | TrustedAdvisor | VPC | WAF | WellArchitected | WorkSpaces | XRay Azure Services: AKS | AccessControl | ActiveDirectory | ActivityLog | Advisor | AppInsights | AppService | CosmosDB | KeyVault | Locks | Monitor | MySQL | Network | Policy | PostgreSQL | RecoveryServices | RedisCache | Resources | Search | SecurityCenter | Sql | StorageAccounts | Subscriptions | VirtualMachines GCP Services: BigQuery | CloudIAM | CloudKMS | CloudSQL | CloudStorage | CloudVPC | ComputeEngine For more information about services, please refer to Cloud Conformity Services Endpoint |
filter[categories] | security | cost-optimisation | reliability | performance-efficiency | operational-excellence | sustainability For more information about categories, please refer to Cloud Conformity Services Endpoint |
filter[riskLevels] | LOW| MEDIUM | HIGH | VERY_HIGH | EXTREME For more information about risk levels, please refer to Cloud Conformity Services Endpoint |
filter[statuses] | SUCCESS | FAILURE |
filter[ruleIds] | Example: EC2-001 | EC2-002 | KeyVault-001 | StorageAccounts-001 | etc For a complete list of rules, please refer to Cloud Conformity Services Endpoint |
filter[resource] | Filter by resource Id For an exact match, e.g "johnSmith", a wildcard, e.g "joh?Sm*h" or when used with filter[resourceSearchMode]=regex, a regular expression, e.g "joh.?Sm.*h". Regular expressions should be URL encoded before sending. For more information about filters, please refer to Filter and Search |
filter[resourceSearchMode] | Set the search mode for the resource filter. Valid values are "text" or "regex". Text supports an exact match or the wildcard characters * and ? Defaults to "text" |
filter[message] | Filter by message. Will find messages that contain all words regardless of the order. e.g "new message" will find "message new" and "new message" |
filter[suppressedFilterMode] | "v1" | "v2" Whether to use the "v1" or "v2" suppressed functionality. "v1" : Using suppressed=true will return both suppressed and unsuppressed checks, suppressed=false will just return unsuppressed checks. "v2" : Using suppressed=true return will just return suppressed checks. Defaults to "v1". |
filter[suppressed] | true | false Whether or not include all suppressed checks. The default value is true for "v1" and omitted for "v2" |
filter[createdDate] | The date when the check was created The numeric value of the specified date as the number of milliseconds since January 1, 1970, 00:00:00 UTC |
filter[createdLessThanDays] | Deprecated. Use filter[newerThanDays] instead. |
filter[createdMoreThanDays] | Deprecated. Use filter[olderThanDays] instead. |
filter[newerThanDays] | The filter[olderThanDays] and filter[newerThanDays] range refers to days to go back from today. It converts the number of days entered to the date when the check was created and assigned a status, or where the status changed from "Success" to "Failure" or from "Failure" to "Success". You can use this filter by entering values for the number of days you wish to view before filter[olderThanDays] and after filter[newerThanDays] . You must pass at least 2 days up to 1 day to see any checks for a specific time duration. To display checks from a particular day up to today, pass the number of days in filter[newerThanDays] and leave filter[olderThanDays] blank. Number. e.g. 5. |
filter[olderThanDays] | To display all checks for up to a particular day, pass a number of days to go back from today in filter[olderThanDays] and leave filter[newerThanDays] blank. Number. e.g. 5. |
filter[tags] | Any assigned metadata tags to your resources |
filter[compliances] | An array of supported standard or framework ids. Possible values: ["AWAF" | "GCPWAF" |"CISAWSF-1_5_0" | "CISAWSF-2_0" | "CISAZUREF-1_5_0" | "CISAZUREF-2_0" | "CISAZUREF-2_1" | "CISGCPF-1_3_0" | "CISGCPF-2_0" | "CISGCPF-3_0" | "CIS-V8" | "PCI" | "PCI-V4" | "HIPAA" | "GDPR" | "APRA" | "NIST4" | "NIST5" | "SOC2" | "NIST-CSF" | "NIST-CSF-2_0" | "ISO27001" | "ISO27001-2022" | "AGISM" | "HITRUST" | "ASAE-3150" | "MAS" | "FEDRAMP" | "ENISA" | "NIS-2" | "FISC-V9" | "LGPD" | "AZUREWAF-2024"] |
filter[withChecks] | true | false Displays only controls from PDF reports with one or more associated checks. If withoutChecks is also set to true, then filter has no effect and all checks will be displayed. The default value is false . |
filter[withoutChecks] | true | false Displays only controls from PDF reports with 0 associated checks. If withChecks is also set to true, then filter has no effect and all checks will be displayed. The default value is false . |
filter[filterTags] | An array of assigned metadata tags to your resources (this filter matches against the key, the value or the full tag, by separating the key from the value with a "::", ie. key::value) |
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 }
}
query Parameters
OK
Bad Request. Cannot process request due to a client error.
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Unprocessable Entity
Bad Request. Cannot process request due to a server error.
- 200
- 400
- 401
- 403
- 422
- 500
{- "data": {
- "check": {
- "type": "checks",
- "id": "ccc:H19NxM15-:CUSTOM-001:EC2:us-west-2:sg-956d00ea",
- "attributes": {
- "accountId": "FJagHgv1g",
- "categories": [
- "security"
], - "compliances": [
- "NIST4",
- "AWAF"
], - "cost": 3.1968,
- "created-date": 1521660152755,
- "descriptorType": "s3-bucket",
- "eventId": "Skzp7ra1WW",
- "excluded": false,
- "extradata": [
- {
- "label": "Group Id",
- "name": "GroupId",
- "type": "META",
- "value": "sg-2e885d00"
}
], - "failure-discovery-date": 1521660152755,
- "failure-introduced-by": "someone@test.com",
- "ignored": false,
- "last-updated-date": 1521660152755,
- "last-updated-by": "someone@test.com",
- "last-modified-date": 1521660152755,
- "lastStatusUpdateDate": 1521660152755,
- "link-title": "gm-bucket-4",
- "message": "Bucket S3Bucket allows public 'READ' access.",
- "not-scored": false,
- "notes": [
- {
- "createdBy": "SYmS0YcL-",
- "createdDate": 1511456432526,
- "note": "hello world"
}
], - "organisationId": "F1r9_41ul",
- "pretty-risk-level": "Medium",
- "provider": "aws",
- "providerResourceId": "arn:aws:sns:us-east-1:123456789012:MyTopic",
- "region": "us-west-2",
- "resolved-date": 1521660152755,
- "resolved-by": "someone@test.com",
- "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/IAM/unused-iam-group.html#",
- "resource": "S3Bucket",
- "resourceName": "KeyVault Vault",
- "risk-level": "HIGH",
- "rule-title": "Custom Rule about EC2 SGs",
- "service": "S3",
- "status": "SUCCESS",
- "suppressed": true,
- "suppressed-until": 1521660152755,
- "tags": [
- "key0::value0",
- "key1::value1"
], - "ttl": 1521660152755,
- "waste": 54.32
}
}, - "relationships": {
- "rule": {
- "data": {
- "type": "rules",
- "id": "CUSTOM-001"
}
}, - "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}
}
}, - "meta": {
- "total": 1,
- "page-number": 0,
- "page-size": 100
}
}
Create Custom Checks
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:
- 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.
- 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. - Check Ids are constructed from the parameters entered and follow the format:
- ccc:accountId:ruleId:service:region:resourceId
- If you add a check with the same
accountId
,ruleId
,service
,region
, ANDresourceId
as another existing check in the database, this new check WILL write over the existing check. - Since resource is an optional attribute, checks entered without resource will not have the
resourceId
part of the check Id.
- Time-to-live (TTL):
- Custom Checks support configuration of a time-to-live (TTL). TTL allows users to automatically delete checks at a set date/time.
- 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
- The maximum configurable TTL is the current time plus 12 months.
- If TTL is not defined, the TTL value defaults to 12 months from the current time.
- TTL is mutable when updating an existing custom check.
- Custom Checks whose TTL has passed are deleted every 30 minutes via a background process.
Request Body schema: application/vnd.api+json
Array of objects (check-request-post) |
OK
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Unprocessable Entity
Bad Request. Cannot process request due to a server error.
- Payload
{- "data": [
- {
- "type": "checks",
- "attributes": {
- "categories": [
- "security"
], - "extradata": [
- {
- "label": "Group Id",
- "name": "GroupId",
- "type": "META",
- "value": "sg-2e885d00"
}
], - "message": "Bucket S3Bucket allows public 'READ' access.",
- "not-scored": false,
- "region": "us-west-2",
- "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/IAM/unused-iam-group.html#",
- "resource": "S3Bucket",
- "risk-level": "HIGH",
- "rule-title": "Custom Rule about EC2 SGs",
- "service": "S3",
- "status": "SUCCESS",
- "tags": [
- "key0::value0",
- "key1::value1"
], - "ttl": 1672534800000
}, - "relationships": {
- "rule": {
- "data": {
- "type": "rules",
- "id": "CUSTOM-001"
}
}, - "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}
}
}
]
}
- 200
- 401
- 403
- 422
- 500
{- "data": [
- {
- "check": {
- "type": "checks",
- "id": "ccc:H19NxM15-:CUSTOM-001:EC2:us-west-2:sg-956d00ea",
- "attributes": {
- "accountId": "FJagHgv1g",
- "categories": [
- "security"
], - "cost": 3.1968,
- "created-date": 1521660152755,
- "descriptorType": "s3-bucket",
- "eventId": "Skzp7ra1WW",
- "excluded": false,
- "extradata": [
- {
- "label": "Group Id",
- "name": "GroupId",
- "type": "META",
- "value": "sg-2e885d00"
}
], - "failure-discovery-date": 1521660152755,
- "failure-introduced-by": "someone@test.com",
- "ignored": false,
- "last-updated-date": 1521660152755,
- "last-updated-by": "someone@test.com",
- "last-modified-date": 1521660152755,
- "lastStatusUpdateDate": 1521660152755,
- "link-title": "gm-bucket-4",
- "message": "Bucket S3Bucket allows public 'READ' access.",
- "not-scored": false,
- "notes": [
- {
- "createdBy": "SYmS0YcL-",
- "createdDate": 1511456432526,
- "note": "hello world"
}
], - "organisationId": "F1r9_41ul",
- "pretty-risk-level": "Medium",
- "provider": "aws",
- "providerResourceId": "arn:aws:sns:us-east-1:123456789012:MyTopic",
- "region": "us-west-2",
- "resolved-date": 1521660152755,
- "resolved-by": "someone@test.com",
- "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/IAM/unused-iam-group.html#",
- "resource": "S3Bucket",
- "resourceName": "KeyVault Vault",
- "risk-level": "HIGH",
- "rule-title": "Custom Rule about EC2 SGs",
- "service": "S3",
- "status": "SUCCESS",
- "suppressed": true,
- "suppressed-until": 1521660152755,
- "tags": [
- "key0::value0",
- "key1::value1"
], - "ttl": 1521660152755,
- "waste": 54.32
}
}, - "relationships": {
- "rule": {
- "data": {
- "type": "rules",
- "id": "CUSTOM-001"
}
}, - "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}
}
}
]
}
Get Check Details
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:
Name | Values |
---|---|
filter[notes] | Flag to return the notes associated with a check. Accepts true or false . Defaults to false . |
filter[notesLength] | The number of most recent notes to return. Accepts a number. Defaults to 100 , and has a maximum of 100 and a minimum of 1 |
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'
OK
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Bad Request. Cannot process request due to a server error.
- 200
- 401
- 403
- 500
{- "data": {
- "check": {
- "type": "checks",
- "id": "ccc:H19NxM15-:CUSTOM-001:EC2:us-west-2:sg-956d00ea",
- "attributes": {
- "accountId": "FJagHgv1g",
- "categories": [
- "security"
], - "compliances": [
- "NIST4",
- "AWAF"
], - "cost": 3.1968,
- "created-date": 1521660152755,
- "descriptorType": "s3-bucket",
- "eventId": "Skzp7ra1WW",
- "excluded": false,
- "extradata": [
- {
- "label": "Group Id",
- "name": "GroupId",
- "type": "META",
- "value": "sg-2e885d00"
}
], - "failure-discovery-date": 1521660152755,
- "failure-introduced-by": "someone@test.com",
- "ignored": false,
- "last-updated-date": 1521660152755,
- "last-updated-by": "someone@test.com",
- "last-modified-date": 1521660152755,
- "lastStatusUpdateDate": 1521660152755,
- "link-title": "gm-bucket-4",
- "message": "Bucket S3Bucket allows public 'READ' access.",
- "not-scored": false,
- "notes": [
- {
- "createdBy": "SYmS0YcL-",
- "createdDate": 1511456432526,
- "note": "hello world"
}
], - "organisationId": "F1r9_41ul",
- "pretty-risk-level": "Medium",
- "provider": "aws",
- "providerResourceId": "arn:aws:sns:us-east-1:123456789012:MyTopic",
- "region": "us-west-2",
- "resolved-date": 1521660152755,
- "resolved-by": "someone@test.com",
- "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/IAM/unused-iam-group.html#",
- "resource": "S3Bucket",
- "resourceName": "KeyVault Vault",
- "risk-level": "HIGH",
- "rule-title": "Custom Rule about EC2 SGs",
- "service": "S3",
- "status": "SUCCESS",
- "suppressed": true,
- "suppressed-until": 1521660152755,
- "tags": [
- "key0::value0",
- "key1::value1"
], - "ttl": 1521660152755,
- "waste": 54.32
}
}, - "relationships": {
- "rule": {
- "data": {
- "type": "rules",
- "id": "CUSTOM-001"
}
}, - "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}
}
}
}
Update Check
This endpoint is used to either update one custom check OR suppress/unsuppressed one normal check.
IMPORTANT: Some guidelines about using this endpoint:
- When updating a custom check, you must leave
region
,resource
,service
attributes andrelationship.account
andrelationship.rule
unchanged. These are unique identifier parameters for custom checks and must be always present and unchanged once check is created. - 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. skipUpdatingEnabledSuppression
attribute can be applied to the suppressed check. Boolean. Is not a required attribute. UsingskipUpdatingEnabledSuppression: true
will prevent updatingsuppressed
andsuppressed-until
attributes for the suppressed check. Only use if you would like to prevent overwriting enabled suppressed check. Default value forskipUpdatingEnabledSuppression: false
.- Time-to-live (TTL):
- Custom Checks support configuration of a time-to-live (TTL). TTL allows users to automatically delete checks at a set date/time.
- 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
- The maximum configurable TTL is the current time plus 12 months.
- If TTL is not defined, the TTL value defaults to 12 months from the current time.
- TTL is mutable when updating an existing custom check.
- 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"
}
}
}
}
}
path Parameters
Request Body schema: application/vnd.api+json
object (check-request-patch) |
OK
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Bad Request. Cannot process request due to a server error.
- Payload
{- "data": {
- "type": "checks",
- "attributes": {
- "suppressed": true,
- "suppressed-until": 1526574705655
}
}, - "meta": {
- "note": "suppressed for 1 week, failure not-applicable during project xyz"
}
}
- 200
- 401
- 403
- 500
{- "data": {
- "check": {
- "type": "checks",
- "id": "ccc:H19NxM15-:CUSTOM-001:EC2:us-west-2:sg-956d00ea",
- "attributes": {
- "accountId": "FJagHgv1g",
- "categories": [
- "security"
], - "compliances": [
- "NIST4",
- "AWAF"
], - "cost": 3.1968,
- "created-date": 1521660152755,
- "descriptorType": "s3-bucket",
- "eventId": "Skzp7ra1WW",
- "excluded": false,
- "extradata": [
- {
- "label": "Group Id",
- "name": "GroupId",
- "type": "META",
- "value": "sg-2e885d00"
}
], - "failure-discovery-date": 1521660152755,
- "failure-introduced-by": "someone@test.com",
- "ignored": false,
- "last-updated-date": 1521660152755,
- "last-updated-by": "someone@test.com",
- "last-modified-date": 1521660152755,
- "lastStatusUpdateDate": 1521660152755,
- "link-title": "gm-bucket-4",
- "message": "Bucket S3Bucket allows public 'READ' access.",
- "not-scored": false,
- "notes": [
- {
- "createdBy": "SYmS0YcL-",
- "createdDate": 1511456432526,
- "note": "hello world"
}
], - "organisationId": "F1r9_41ul",
- "pretty-risk-level": "Medium",
- "provider": "aws",
- "providerResourceId": "arn:aws:sns:us-east-1:123456789012:MyTopic",
- "region": "us-west-2",
- "resolved-date": 1521660152755,
- "resolved-by": "someone@test.com",
- "resolution-page-url": "https://www.cloudconformity.com/conformity-rules/IAM/unused-iam-group.html#",
- "resource": "S3Bucket",
- "resourceName": "KeyVault Vault",
- "risk-level": "HIGH",
- "rule-title": "Custom Rule about EC2 SGs",
- "service": "S3",
- "status": "SUCCESS",
- "suppressed": true,
- "suppressed-until": 1521660152755,
- "tags": [
- "key0::value0",
- "key1::value1"
], - "ttl": 1521660152755,
- "waste": 54.32
}
}, - "relationships": {
- "rule": {
- "data": {
- "type": "rules",
- "id": "CUSTOM-001"
}
}, - "account": {
- "data": {
- "type": "accounts",
- "id": "H19NxM15-"
}
}
}
}
}
Delete Check
This endpoint allows you to delete the specified check.
OK
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Bad Request. Cannot process request due to a server error.
- 200
- 401
- 403
- 500
{- "meta": [
- {
- "status": "success",
- "message": "Check successfully deleted"
}
]
}
Get Check Evolution Statistics
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:
- If a user provides
groupId
,accountIds
at the same time, the precedence order isgroupId
,accountIds
. - If a user does not provide any of
groupId
,accountIds
, the endpoint will show check evolution statistics of user's organisation. - 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. - If a user provides
to
with a date string 2021-05-19T00:00:01 along withtimezone
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 providesto
with a date string 2021-05-19T10:00:01 along withtimezone
Australia/Sydney, the date range will include the date 2021-05-19. newFailureCount
in the response means the number of new failed checks created since the last summary date.newSuccessCount
in the response means the number of new succeeded checks created since the last summary date.newCount
in the response means the total number of new failed checks and new succeeded checks created since the last summary date.introducedCount
in the response means the number of existing failed checks where failures were introduced since the last summary date.checks
in the response means the average check count for each bot run in a day.failureCount
in the response means the average failure check count for each bot run in a day.successCount
in the response means the average success check count for each bot run in a day.resolvedCount
in the response means the total number of resolved check count since the last summary date
Name | Values |
---|---|
groupId | The group ID to specify the Conformity group where user can get check evolution statistics from. |
accountIds | The account IDs to specify the Conformity accounts where user can get check evolution statistics from. Account Ids are separated by comma. |
from | The date/time string with ISO 8601 date/time format to specify the start of the date range for the check evolution statistics. If only from is provided, the time range will be from from until the present time |
to | The date/time string with ISO 8601 date/time format to specify the end of the date range for the check evolution statistics. If only to is provided, the time range will be from 30 days ago before to until to |
timezone | The timezone string to specify the locale for the date range, e.g. Australia/Sydney. If it is not provided, it will default to UTC. |
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
}
]
}
query Parameters
OK
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Bad Request. Cannot process request due to a server error.
- 200
- 401
- 403
- 500
{- "data": [
- {
- "security": "75",
- "performance-efficiency": "83",
- "reliability": "83",
- "operational-excellence": "78",
- "cost-optimisation": "84",
- "sustainability": "79",
- "date": "1621382400000",
- "checks": "22081",
- "compliance": "73",
- "cost": "474.35",
- "waste": "81.78",
- "newCount": "2001",
- "newFailureCount": "966",
- "newSuccessCount": "1035",
- "resolvedCount": "92",
- "introducedCount": "1049",
- "successCount": "16758",
- "failureCount": "5323"
}
]
}
Replay Checks To Communication Channel
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 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.
Request Body schema: application/vnd.api+json
object |
OK
Unauthorized. The requesting user does not have enough privilege.
Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.
Unprocessable Entity
Bad Request. Cannot process request due to a server error.
- Payload
{- "data": {
- "attributes": {
- "filter": {
- "newerThanDays": 30,
- "olderThanDays": 10
}, - "settingId": "d788778f-1804-4e3e-a0f5-34k3j5k35j:communication:sns-57DryxMDh"
}
}
}
- 200
- 401
- 403
- 422
- 500
{- "data": {
- "status": "Success",
- "numChecks": 136
}
}