Accounts

Managing Conformity accounts.

Note:

  • The field hasRealTimeMonitoring is planned to be replaced with subscriptionType in the future. We advise new customers to use the new field subscriptionType, existing customers are able to continue using the field hasRealTimeMonitoring until it has been replaced. When an account has the subscriptionType of 'advanced', Real-Time threat monitoring is enabled for the account. When an account has subscriptionType of 'essentials', Real-Time threat monitoring is disabled for the account.

List All Accounts

get/accounts

This endpoint allows you to query all accounts that you have access to.

SecurityApiKeyAuth
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Response samples
application/json
{
  • "data": [
    ]
}

Create An AWS Account

post/accounts

This endpoint is used to register a new AWS account with Cloud Conformity.

Note to Cloud One Users: Upon a successful account creation API request, an Email communication channel is set up pending configuration from the Conformity UI. For details on channel configuration, see: Email Communication.

IMPORTANT:    In order to register a new AWS account, you need to:

  1. Obtain your External ID from Get Organisation External ID

  2. Configure your account using CloudFormation automation (Note: You need to specify ExternalID parameter for both options)

    1. Option 1 Launch stack via the console:

      Launch Stack

    2. Option 2 via the AWS CLI:

      aws cloudformation create-stack --stack-name CloudConformity  --region us-east-1  --template-url https://s3-us-west-2.amazonaws.com/cloudconformity/CloudConformity.template --parameters ParameterKey=AccountId,ParameterValue=717210094962 ParameterKey=ExternalId,ParameterValue=THE_EXTERNAL_ID  --capabilities CAPABILITY_NAMED_IAM
      
  3. Verify stack creation is completed, and then create a new account (see below) with Cloud Conformity using your roleArn and externalId.

Note:

  • Conformity Bot will not run immediately after creating a new AWS account. Once your AWS account is successfully onboarded, it may take up to 24 hours for Conformity Bot to run.
  • the server will not accept both hasRealTimeMonitoring and subscriptionType in the request body. Please provide either hasRealTimeMonitoring or subscriptionType or neither.

Example Request with the old field hasRealTimeMonitoring:

curl -X POST \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
  "data": {
    "type": "account",
    "attributes": {
      "name": "Myaccount",
      "environment": "MyEnv",
      "access": {
        "keys": {
          "roleArn": "YOUR_ROLE_ARN",
          "externalId": "THE_EXTERNAL_ID"
        }
      },
      "hasRealTimeMonitoring": true
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/accounts

Example Request with new field subscriptionType:

curl -X POST \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
  "data": {
    "type": "account",
    "attributes": {
      "name": "Myaccount",
      "environment": "MyEnv",
      "access": {
        "keys": {
          "roleArn": "YOUR_ROLE_ARN",
          "externalId": "THE_EXTERNAL_ID"
        }
      },
      "subscriptionType": "advanced"
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/accounts

Example Response:

{
  "data": {
    "type": "accounts",
    "id": "H19NxMi5-",
    "attributes": {
      "name": "Myaccount",
      "environment": "MyEnv",
      "awsaccount-id": "123456789012",
      "status": "ACTIVE",
      "has-real-time-monitoring": true, // **Note:** This field is planned to be replaced with subscription-type in the future.
      "meta": {
        "is-deprecated-rules-free": true
      },
      "created-date": 1505595441887,
      "settings": {
        "communication": {
          "channels": [
            {
              "name": "email",
              "users": ["H13rFYTvl"],
              "enabled": true,
              "levels": ["EXTREME", "VERY_HIGH", "HIGH"]
            }
          ]
        },
        "rules": {},
        "access": {
          "type": "CROSS_ACCOUNT",
          "stackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/CloudConformity/56db5b90-7ebb-11e7-8a78-500c28902e99"
        }
      }
    },
    "subscription-type": "advanced",
    "cloud-id": "123456789012",
    "relationships": {
      "organisation": {
        "data": {
          "type": "organisations",
          "id": "B1nHYYpwx"
        }
      }
    }
  }
}
SecurityApiKeyAuth
Request
Request Body schema: application/vnd.api+json
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Create An Azure Subscription

post/accounts/azure

This endpoint is used to register a new Azure Subscription with an already onboarded Microsoft Entra ID on Conformity.
Note:

  • Conformity Bot will not run immediately after creating a new Azure account. Once your Azure account is successfully onboarded, it may take up to 24 hours for Conformity Bot to run.
  • Real Time Monitoring is currently not available for Azure subscriptions.
  • The subscriptionType of Azure subscriptions defaults to essentials.
  • Cloud One Users: Upon a successful account creation API request, an Email communication channel is set up pending configuration from the Conformity UI. For details on channel configuration, see: Email Communication.

IMPORTANT:    In order to register a new Azure Subscription, you need to:

  1. Consult the HELP pages to Setup Cloud Conformity Azure Access Application
  2. Provide the ID of an Microsoft Entra ID already registered with Conformity. If you do not have an existing Microsoft Entra ID on Conformity, this can be added via the application.
SecurityApiKeyAuth
Request
Request Body schema: application/vnd.api+json
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Create A GCP Account

post/accounts/gcp

This endpoint is used to create a new GCP account in Conformity.
Note:

  • Conformity Bot will not run immediately after creating a new GCP account. Once your GCP account is successfully onboarded, it may take up to 24 hours for Conformity Bot to run.
  • Real Time Monitoring is currently not available for GCP accounts..
  • The subscriptionType of GCP accounts defaults to essentials.
  • You can retrieve your serviceAccountUniqueId from your GCP group's settings under GCP Service Account Unique ID
  • Default Cloud GCP projects generated by Apps Scripts can't be added.
SecurityApiKeyAuth
Request
Request Body schema: application/vnd.api+json
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get Account Details

get/accounts/{id}

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

Note: If the account contains rule settings that are marked as deprecated and have not been disabled (enabled: false), the following meta warning will be included in the response:

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this account is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": [
          {
            "riskLevel": "LOW",
            "id": "RuleID-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true,
            "exceptions": {
              "resources": null,
              "tags": null,
              "filterTags": null
            }
          }
        ]
      }
    }
  }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Response samples
application/json
{
  • "data": {
    }
}

Delete Account

delete/accounts/{id}

A DELETE request to this endpoint allows an ADMIN to delete the specified account.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Response samples
application/json
{
  • "meta": {
    }
}

Update Account

patch/accounts/{id}

A PATCH request to this endpoint allows changes to the account name and environment.

We recommend you first Get account details to verify that the subscription needs to be updated.

IMPORTANT:    Only ADMINs and users with FULL access to the specified account can use this endpoint.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Request Body schema: application/vnd.api+json
required
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Update Account Subscription

patch/accounts/{id}/subscription

A PATCH request to this endpoint allows you to change the add-on package subscription of the specified account.

We recommend you first Get account details to verify that the subscription needs to be updated.

IMPORTANT:    Only ADMIN users can use this endpoint.

Please note the server will not accept both hasRealTimeMonitoring and subscriptionType in the request body. Please provide either hasRealTimeMonitoring or subscriptionType or neither

Example Request with the old field hasRealTimeMonitoring:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
  "data": {
    "attributes": {
      "hasRealTimeMonitoring": true
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/accounts/AgA12vIwb/subscription

Example Request with new field subscriptionType:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
  "data": {
    "attributes": {
      "subscriptionType": "advanced"
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/accounts/AgA12vIwb/subscription

Example Response:

{
  "data": {
    "type": "accounts",
    "id": "AgA12vIwb",
    "attributes": {
      "name": "myCCaccount",
      "environment": "myAWSenv",
      "awsaccount-id": "123456789101",
      "status": "ACTIVE",
      "has-real-time-monitoring": false, // **Note:** This field is planned to be replaced with subscription-type in the future.
      "last-notified-date": 1504113512701,
      "last-checked-date": 1504113511956,
      "available-runs": 5,
      "subscription-type": "advanced",
      "created-date": 1504113511956,
      "last-monitoring-event-date": 1504113511956,
      "cloud-id": "123456789101",
      "meta": {
        "is-deprecated-rules-free": true
      },
      "settings": {
        "rules": [
          {
            "riskLevel": "VERY_HIGH",
            "id": "CT-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true
          },
          {
            "ruleExists": false,
            "riskLevel": "MEDIUM",
            "id": "RTM-008",
            "extraSettings": [
              {
                "name": "authorisedRegions",
                "regions": true,
                "type": "regions",
                "value": null,
                "values": ["eu-west-1", "eu-west-2"]
              }
            ],
            "provider": "aws",
            "enabled": false
          }
        ]
      }
    },
    "relationships": {
      "organisation": {
        "data": {
          "type": "organisations",
          "id": "B1nHYYpwx"
        }
      }
    }
  }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Request Body schema: application/vnd.api+json
required
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": [
    ]
}

Get Account Access Setting

get/accounts/{id}/access

This endpoint allows ADMIN users to get the current setting Cloud Conformity uses to access the specified account.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Response samples
application/json
{
  • "id": "BJ0Ox16Hb:access",
  • "type": "settings",
  • "attributes": {
    },
  • "relationships": {
    }
}

Get Rule Setting

get/accounts/{id}/settings/rules/{ruleId}

A GET request to this endpoint allows you to get configured rule setting for the specified rule Id of the specified account.

If a specific rule has never been configured, the request will result in a 404 error.

For example, even if our bots run rule RDS-018 for your account hourly, if you have never configured it, trying to get rule settings for RDS-018 will result in a 404 error.

Note: If the rule setting being retrieved from the account is marked as deprecated and has not been disabled (enabled: false), the following meta warning will be included in the response:

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this account is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": [
          {
            "riskLevel": "LOW",
            "id": "RuleID-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true,
            "exceptions": {
              "resources": null,
              "tags": null,
              "filterTags": null
            }
          }
        ]
      }
    }
  }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

ruleId
required
string

The ID of the rule.

query Parameters
notes
boolean

Optional parameter to get notes for the specified rule setting.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

404

Not found.

Response samples
application/json
{
  • "data": {
    }
}

Update Rule Setting

patch/accounts/{id}/settings/rules/{ruleId}

A PATCH request to this endpoint allows you to customize rule setting for the specified rule Id of the specified account. This feature is used in conjunction with the GET request to the same endpoint for copying rule setting from one account to another. An example of this function is provided in the examples folder.

IMPORTANT:    To copy rule setting from one account to another, you first need to:

  1. Obtain rule setting from the desired account. Get rule setting
  2. Paste rule setting as is into the body of the PATCH request following the format below.

Example Request:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
  "data": {
    "attributes": {
      "ruleSetting": {
        "ruleExists": false,
        "riskLevel": "MEDIUM",
        "id": "RDS-018",
        "exceptions": {
          "resources": ["i-erw82heiu8"],
          "tags": ["mysql-backups"],
          "filterTags": ["dev"]
        },
        "extraSettings": [
          {
            "name": "threshold",
            "value": 90
          }
        ],
        "enabled": false
      },
      "note": "copied from account H19NxMi5- via the api"
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/accounts/AgA12vIwb/settings/rules/RDS-018

Example Response:

{
  "data": {
    "type": "accounts",
    "id": "AgA12vIwb",
    "attributes": {
      "settings": {
        "rules": [
          {
            "riskLevel": "VERY_HIGH",
            "id": "CT-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true
          },
          {
            "riskLevel": "MEDIUM",
            "id": "RTM-005",
            "extraSettings": [
              {
                "name": "authorisedCountries",
                "countries": true,
                "type": "countries",
                "value": null,
                "values": [
                  {
                    "value": "CA",
                    "label": "Canada"
                  },
                  {
                    "value": "US",
                    "label": "United States"
                  }
                ]
              }
            ],
            "provider": "aws",
            "enabled": false
          },
          {
            "ruleExists": false,
            "riskLevel": "MEDIUM",
            "id": "RTM-008",
            "extraSettings": [
              {
                "name": "authorisedRegions",
                "regions": true,
                "type": "regions",
                "value": null,
                "values": ["eu-west-1", "eu-west-2"]
              }
            ],
            "provider": "aws",
            "enabled": false
          },
          {
            "ruleExists": false,
            "riskLevel": "MEDIUM",
            "id": "RDS-018",
            "exceptions": {
              "resources": ["i-erw82heiu8"],
              "tags": ["mysql-backups"],
              "filterTags": ["dev"]
            },
            "extraSettings": [
              {
                "name": "threshold",
                "value": 90,
                "values": [],
                "type": []
              }
            ],
            "provider": "aws",
            "enabled": false
          }
        ],
        "access": {}
      },
      "available-runs": 5,
      "access": null
    },
    "relationships": {
      "organisation": {
        "data": {
          "type": "organisations",
          "id": "B1nHYYpwx"
        }
      }
    }
  }
}

Note: If the account contains rule settings that are marked as deprecated and have not been disabled (enabled: false), the following meta warning will be included in the response:

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this account is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": [
          {
            "riskLevel": "LOW",
            "id": "RuleID-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true,
            "exceptions": {
              "resources": null,
              "tags": null,
              "filterTags": null
            }
          }
        ]
      }
    }
  }
}

Errors:

Some errors thrown from rule setting validation may need further clarification. Below is a list. For more information about specific rule configurations, consult Cloud Conformity Services Endpoint

Error Details Resolution
This Real-Time Threat Monitoring package rule ruleId is not part of the account subscription You cannot configure rule settings for this rule. Try another rule.
ruleId is not configurable from this endpoint. This is an organisation-setting which you cannot configure via this account rule settings endpoint.
Rule risk level missing for ruleId ruleSetting.riskLevel is a required parameter
Rule risk level provided for ruleId is incorrect only "LOW", "MEDIUM", "HIGH", "VERY_HIGH", and "EXTREME" are accepted risk levels
Rule enable status is not valid for ruleId ruleSetting.enabled is a required boolean parameter
One or more rule setting property is invalid for ruleId remove the ruleSetting property if it is not id, enabled, riskLevel, extraSettings, or ruleExists
Provider XXX is invalid for ruleId provider must match the cloud provider for the rule

Extra settings Rule ruleId is not configurable | remove ruleSetting.extraSettings, you may only change risk level or enable/disable this rule. If you are directly copying this rule from another account and getting this message, this rule may have been previously configurable and is no longer.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

ruleId
required
string

The ID of the rule.

Request Body schema: application/vnd.api+json
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get Rule Settings

get/accounts/{id}/settings/rules

A GET request to this endpoint allows you to get rule settings for all configured rules of the specified account.

If a rule has never been configured, it will not show up in the resulting data. For example, even if our bots run rule RDS-018 for your account hourly, if you have never configured it, it will not be part of the data body we send back.

This endpoint only returns configured rules. If you want to include default rule settings, set includeDefaults=true in query parameters.

Note: If the account contains rule settings that are marked as deprecated and have not been disabled (enabled: false), the following meta warning will be included in the response:

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this account is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": [
          {
            "riskLevel": "LOW",
            "id": "RuleID-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true,
            "exceptions": {
              "resources": null,
              "tags": null,
              "filterTags": null
            }
          }
        ]
      }
    }
  }
}

Rule settings

Every rule in Cloud Conformity can be configured via API. These rule settings can disable or enable rules, change default risk level, setup exceptions and configure rule-specific settings.

Rule settings returned from GET /v1/accounts/{accountId}/settings/rules?includeDefaults=true endpoint are formatted as the following example:

{
  "id": "EC2-012",
  "enabled": true,
  "riskLevel": "MEDIUM",
  "exceptions": {
    "tags": ["Role::Temporary", "TagKey::TagValue", "TagKeyOrValue"],
    "filterTags": ["role::temporary", "tagkey::tagvalue", "tagKeyOrvalue"],
    "resources": ["i-98f25d31", "another EC2 instance ID"]
  },
  "extraSettings": [
    {
      "name": "threshold",
      "type": "single-number-value",
      "value": 100
    }
  ],
  "configured": false
}

Extra setting types

These formats are are found in type field of rule extra settings:

multiple-string-values

  • Usage: Used when one or more strings are required.
  • UI: List of text fields

Example:

{
  "id": "EC2-017",
  //...
  "extraSettings": [
    {
      "name": "desiredInstanceTypes",
      "type": "multiple-string-values",
      "values": [
        {
          "value": "t2.micro"
        },
        {
          "value": "m3.medium"
        },
        {
          "value": "m3.large"
        }
      ]
    }
  ]
  //...
}

multiple-object-values

  • Usage: Used when one or more sets of values are required.
  • UI: Table of text fields

Example:

{
  "id": "RTM-01a",
  //...
  "extraSettings": [
    {
      "name": "desiredInstanceTypes",
      "type": "multiple-object-values",
      "valueKeys": ["eventName", "eventSource", "userIdentityType"],
      "values": [
        {
          "value": {
            "eventName": "^(iam.amazonaws.com)",
            "eventSource": "^(IAM).*",
            "userIdentityType": "^(Delete).*"
          }
        }
      ]
    }
  ]
  //...
}

choice-multiple-value

  • Usage: Used when one or more selections from a predefined set of values are required.
  • UI: List of checkboxes

Note that all allowed values are returned from GET /v1/accounts/{accountId}/settings/rules?includeDefaults=true endpoint

Example:

{
  "id": "RTM-009",
  //...
  "extraSettings": [
    {
      "name": "ConfigurationChanges",
      "values": [
        {
          "value": "internetGateway",
          "enabled": true
        },
        {
          "value": "securityGroup",
          "enabled": false
        },
        {
          "value": "elasticNetworkInterface",
          "enabled": true
        },
        {
          "value": "virtualPrivateCloud",
          "enabled": false
        }
      ]
    }
  ]
  //...
}

choice-single-value

  • Usage: Used when a single value should be selected from multiple choices.
  • UI: List of radio buttons

Note that the allowed values differ for each rule:

  • Support-001 (Support Plan)
    • "Basic"
    • "Developer"
    • "Business"
    • "Enterprise"
  • EC2-025 (EC2 Instance Tenancy)
    • "default"
    • "dedicated"
    • "host"
  • ELB-008 (ELB Listener Security)
    • "1" (Yes)
    • "0" (No)
  • ELB-010, ELBv2-004 (ELB/ELBv2 Minimum Number Of EC2 Instances)
    • Minimum Number Of EC2 Instances
      • 1 (One instance)
      • 2 (Two instances)
  • ELBv2-005 (ELBv2 ALB Listener Security)
    • Include Internal Load Balancers
      • "1" (Yes)
      • "0" (No)

Example:

{
  "id": "Support-001",
  //...
  "extraSettings": [
    {
      "name": "level",
      "type": "choice-single-value",
      "value": "Developer"
    }
  ]
  //...
}

countries

  • Usage: Used when one or more countries should be selected.
  • UI: Multi-select list of countries

For certain rule settings, extra settings require configuration for a "countries" value. Value of each item is a country code.

Example:

{
  "id": "RTM-005",
  //...
  "extraSettings": [
    {
      "name": "authorisedCountries",
      "type": "countries",
      "values": [
        {
          "value": "CA"
        },
        {
          "value": "AU"
        },
        {
          "value": "US"
        },
        {
          "value": "UM"
        }
      ],
      "countries": true
    }
    //..
  ]
  //...
}

Below is the list of supported countries and their respective codes:

Country Name Code
Other Country O1
Andorra AD
United Arab Emirates AE
Afghanistan AF
Antigua and Barbuda AG
Anguilla AI
Albania AL
Armenia AM
Angola AO
Asia/Pacific Region AP
Antarctica AQ
Argentina AR
American Samoa AS
Austria AT
Australia AU
Aruba AW
Aland Islands AX
Azerbaijan AZ
Bosnia and Herzegovina BA
Barbados BB
Bangladesh BD
Belgium BE
Burkina Faso BF
Bulgaria BG
Bahrain BH
Burundi BI
Benin BJ
Saint Bartelemey BL
Bermuda BM
Brunei Darussalam BN
Bolivia BO
Bonaire, Saint Eustatius and Saba BQ
Brazil BR
Bahamas BS
Bhutan BT
Bouvet Island BV
Botswana BW
Belarus BY
Belize BZ
Canada CA
Cocos (Keeling) Islands CC
Congo, The Democratic Republic of the CD
Central African Republic CF
Congo CG
Switzerland CH
Cote d'Ivoire CI
Cook Islands CK
Chile CL
Cameroon CM
China CN
Colombia CO
Costa Rica CR
Cuba CU
Cape Verde CV
Curacao CW
Christmas Island CX
Cyprus CY
Czech Republic CZ
Germany DE
Djibouti DJ
Denmark DK
Dominica DM
Dominican Republic DO
Algeria DZ
Ecuador EC
Estonia EE
Egypt EG
Western Sahara EH
Eritrea ER
Spain ES
Ethiopia ET
Europe EU
Finland FI
Fiji FJ
Falkland Islands (Malvinas) FK
Micronesia, Federated States of FM
Faroe Islands FO
France FR
Gabon GA
United Kingdom GB
Grenada GD
Georgia GE
French Guiana GF
Guernsey GG
Ghana GH
Gibraltar GI
Greenland GL
Gambia GM
Guinea GN
Guadeloupe GP
Equatorial Guinea GQ
Greece GR
South Georgia and the South Sandwich Islands GS
Guatemala GT
Guam GU
Guinea-Bissau GW
Guyana GY
Hong Kong HK
Heard Island and McDonald Islands HM
Honduras HN
Croatia HR
Haiti HT
Hungary HU
Indonesia ID
Ireland IE
Israel IL
Isle of Man IM
India IN
British Indian Ocean Territory IO
Iraq IQ
Iran, Islamic Republic of IR
Iceland IS
Italy IT
Jersey JE
Jamaica JM
Jordan JO
Japan JP
Kenya KE
Kyrgyzstan KG
Cambodia KH
Kiribati KI
Comoros KM
Saint Kitts and Nevis KN
Korea, Democratic People's Republic of KP
Korea, Republic of KR
Kuwait KW
Cayman Islands KY
Kazakhstan KZ
Lao People's Democratic Republic LA
Lebanon LB
Saint Lucia LC
Liechtenstein LI
Sri Lanka LK
Liberia LR
Lesotho LS
Lithuania LT
Luxembourg LU
Latvia LV
Libyan Arab Jamahiriya LY
Morocco MA
Monaco MC
Moldova, Republic of MD
Montenegro ME
Saint Martin MF
Madagascar MG
Marshall Islands MH
Macedonia MK
Mali ML
Myanmar MM
Mongolia MN
Macao MO
Northern Mariana Islands MP
Martinique MQ
Mauritania MR
Montserrat MS
Malta MT
Mauritius MU
Maldives MV
Malawi MW
Mexico MX
Malaysia MY
Mozambique MZ
Namibia NA
New Caledonia NC
Niger NE
Norfolk Island NF
Nigeria NG
Nicaragua NI
Netherlands NL
Norway NO
Nepal NP
Nauru NR
Niue NU
New Zealand NZ
Oman OM
Panama PA
Peru PE
French Polynesia PF
Papua New Guinea PG
Philippines PH
Pakistan PK
Poland PL
Saint Pierre and Miquelon PM
Pitcairn PN
Puerto Rico PR
Palestinian Territory PS
Portugal PT
Palau PW
Paraguay PY
Qatar QA
Reunion RE
Romania RO
Serbia RS
Russian Federation RU
Rwanda RW
Saudi Arabia SA
Solomon Islands SB
Seychelles SC
Sudan SD
Sweden SE
Singapore SG
Saint Helena SH
Slovenia SI
Svalbard and Jan Mayen SJ
Slovakia SK
Sierra Leone SL
San Marino SM
Senegal SN
Somalia SO
Suriname SR
South Sudan SS
Sao Tome and Principe ST
El Salvador SV
Sint Maarten SX
Syrian Arab Republic SY
Swaziland SZ
Turks and Caicos Islands TC
Chad TD
French Southern Territories TF
Togo TG
Thailand TH
Tajikistan TJ
Tokelau TK
Timor-Leste TL
Turkmenistan TM
Tunisia TN
Tonga TO
Turkey TR
Trinidad and Tobago TT
Tuvalu TV
Taiwan TW
Tanzania, United Republic of TZ
Ukraine UA
Uganda UG
United States Minor Outlying Islands UM
United States US
Uruguay UY
Uzbekistan UZ
Holy See (Vatican City State) VA
Saint Vincent and the Grenadines VC
Venezuela VE
Virgin Islands, British VG
Virgin Islands, U.S. VI
Vietnam VN
Vanuatu VU
Wallis and Futuna WF
Samoa WS
Yemen YE
Mayotte YT
South Africa ZA
Zambia ZM
Zimbabwe ZW

multiple-aws-account-values

  • Usage: Used when one or more AWS Account IDs are required.
  • UI: List of text fields accepting AWS Account IDs (12 digits)

Example:

{
  "id": "S3-015",
  //...
  "extraSettings": [
    {
      "type": "multiple-aws-account-values",
      "name": "friendlyAccounts",
      "values": [
        {
          "value": "123456789012"
        },
        {
          "value": "111111111111"
        }
      ]
    }
  ]
  //...
}

multiple-ip-values

  • Usage: Used when one or more IP addresses or CIDRs are required.
  • UI: List of text fields accepting IP address or CIDRs.

Example:

{
  "id": "RTM-007",
  //...
  "extraSettings": [
    {
      "type": "multiple-ip-values",
      "name": "authorisedIps",
      "values": [
        {
          "value": "1.2.3.4"
        },
        {
          "value": "195.200.0.0/24"
        }
      ]
    }
    //...
  ]
  //...
}

multiple-number-values

  • Usage: Used when a one or more numbers are required.
  • UI: List of text fields accepting numbers

Example:

{
  "id": "EC2-034",
  //...
  "extraSettings": [
    {
      "name": "commonlyUsedPorts",
      "type": "multiple-number-values",
      "values": [
        {
          "value": 80
        },
        {
          "value": 443
        }
        //...
      ]
    }
  ]
  //...
}

regions

  • Usage: Used when one or more AWS region should be selected.
  • UI: List of on/off sliders for every supported AWS region

Note that setting values only include selected region identifiers.

Example:

{
  "id": "RTM-008",
  //...
  "extraSettings": [
    {
      "type": "regions",
      "name": "authorisedRegions",
      "values": ["us-east-1", "us-west-2", "ap-southeast-2", "eu-west-1"],
      "regions": true
    }
    //...
  ]
  //...
}

ignored-regions

  • Usage: Used when one or more AWS region should be ignored.
  • UI: List of on/off sliders for every supported AWS region

Note that setting values only include disabled region identifiers.

Example:

{
  "id": "Config-001",
  //...
  "extraSettings": [
    {
      "type": "ignored-regions",
      "name": "ignoredRegions",
      "values": ["us-east-1", "us-west-2", "ap-southeast-2"],
      "ignoredRegions": true
    }
    //...
  ]
  //...
}

single-number-value

  • Usage: Used when a single numeric value is required.
  • UI: Text field accepting numbers

Example:

{
  "id": "SQS-003",
  //...
  "extraSettings": [
    {
      "name": "threshold",
      "type": "single-number-value",
      "value": 100
    }
  ]
  //...
}

single-string-value

  • Usage: Used when a single string value is required.
  • UI: Text field

Example:

{
  "id": "IAM-047",
  //...
  "extraSettings": [
    {
      "name": "iam_master_role_name",
      "type": "single-string-value",
      "value": "MasterIAMRole"
    }
    //...
  ]
  //...
}

single-value-regex

  • Usage: Used when a regular expression is required.
  • UI: Text field accepting regular expressions

Example:

{
  "id": "VPC-004",
  //...
  "extraSettings": [
    {
      "name": "pattern",
      "type": "single-value-regex",
      "value": "^vpc-(ue1|uw1|uw2|ew1|ec1|an1|an2|as1|as2|se1)-(d|t|s|p)-([a-z0-9\\-]+)$"
    }
  ]
  //...
}

ttl

  • Usage: Real-time monitoring (RTM) rules have Time To Live. This is the number of hours that an RTM check remains valid after which time it is expired and may get triggered again.
  • UI: Text field accepting numbers

Example:

{
  "id": "RTM-001",
  //...
  "extraSettings": [
    {
      "name": "ttl",
      "type": "ttl",
      "value": 2
    }
  ]
  //...
}

multiple-vpc-gateway-mappings

  • Usage: Used when one or more VPC gateway mappings are required.
  • UI: List of VPC Id and Gateway Id mapping

Example:

{
  "id": "VPC-013",
  //...
  "extraSettings": [
    {
      "type": "multiple-vpc-gateway-mappings",
      "name": "SpecificVPCToSpecificGatewayMapping",
      "mappings": [
        {
          "values": [
            {
              "type": "single-string-value",
              "name": "vpcId",
              "value": "vpc-001"
            },
            {
              "type": "multiple-string-values",
              "name": "gatewayIds",
              "values": [
                {
                  "value": "nat-001"
                },
                {
                  "value": "nat-002"
                }
              ]
            }
          ]
        }
        //...
      ]
    }
  ]
  //...
}

tags

  • Usage: Identify friendly accounts with AWS Account Tags
  • UI: Text field accepting Tags

Example:

{
  "id": "S3-015",
  //...
  "extraSettings": [
    {
      "label": "Tags",
      "name": "accountTags",
      "type": "tags",
      "values": ["Sandbox"]
    }
  ]
  //...
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

query Parameters
includeDefaults
boolean
Default: false

(Optional) Whether or not to include default rule settings.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

404

Not found.

Response samples
application/json
{
  • "id": "EC2-012",
  • "enabled": true,
  • "riskLevel": "MEDIUM",
  • "exceptions": {
    },
  • "extraSettings": [
    ],
  • "configured": false
}

Update Rule Settings

patch/accounts/{id}/settings/rules

A PATCH request to this endpoint allows you to customize rule settings for the specified account.

This feature is used in conjunction with the GET request to the same endpoint for copying rule settings from one account to another. An example of this function is provided in the examples folder.

IMPORTANT:    To copy rule settings from one account to another, you first need to:

  1. Obtain rule settings from the desired account. Get rule settings
  2. Paste rule settings as is into the body of the PATCH request following the format below.

Example Request:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
-d '
{
  "data": {
    "attributes": {
      "note": "copied from account H19NxMi5- via the api",
      "ruleSettings": [
        {
          "ruleExists": false,
          "riskLevel": "MEDIUM",
          "id": "RDS-018",
          "exceptions": {
            "resources": ["i-erw82heiu8"],
            "tags": ["mysql-backups"],
            "filterTags" : ["dev"]
           },
          "extraSettings": [
            {
              "name": "threshold",
              "value": 90
            }
          ],
          "enabled": false
        },
        {
          "riskLevel": "LOW",
          "id": "Config-001",
          "extraSettings": null,
          "provider": "aws",
          "enabled": true
        },
        {
          "riskLevel": "MEDIUM",
          "id": "RTM-005",
          "extraSettings": [
            {
              "name": "authorisedCountries",
              "countries": true,
              "type": "countries",
              "value": null,
              "values": [
                {
                  "value": "CA",
                  "label": "Canada"
                },
                {
                  "value": "US",
                  "label": "United States"
                }
              ]
            }
          ],
          "provider": "aws",
          "enabled": false
        }
      ]
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/accounts/AgA12vIwb/settings/rules

Example Response:

{
  "data": {
    "type": "accounts",
    "id": "AgA12vIwb",
    "attributes": {
      "settings": {
        "rules": [
          {
            "ruleExists": false,
            "riskLevel": "MEDIUM",
            "id": "RDS-018",
            "exceptions": {
              "resources": ["i-erw82heiu8"],
              "tags": ["mysql-backups"],
              "filterTags": ["dev"]
            },
            "extraSettings": [
              {
                "name": "threshold",
                "value": 90
              }
            ],
            "provider": "aws",
            "enabled": false
          },
          {
            "riskLevel": "LOW",
            "id": "Config-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true
          },
          {
            "riskLevel": "MEDIUM",
            "id": "RTM-005",
            "extraSettings": [
              {
                "name": "authorisedCountries",
                "countries": true,
                "type": "countries",
                "value": null,
                "values": [
                  {
                    "value": "CA",
                    "label": "Canada"
                  },
                  {
                    "value": "US",
                    "label": "United States"
                  }
                ]
              }
            ],
            "provider": "aws",
            "enabled": false
          }
        ],
        "access": {}
      },
      "available-runs": 5,
      "access": null
    },
    "relationships": {
      "organisation": {
        "data": {
          "type": "organisations",
          "id": "B1nHYYpwx"
        }
      }
    }
  }
}

Note: If the account contains rule settings that are marked as deprecated and have not been disabled (enabled: false), the following meta warning will be included in the response:

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this account is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": [
          {
            "riskLevel": "LOW",
            "id": "RuleID-001",
            "extraSettings": null,
            "provider": "aws",
            "enabled": true,
            "exceptions": {
              "resources": null,
              "tags": null,
              "filterTags": null
            }
          }
        ]
      }
    }
  }
}

Errors:

Some errors thrown from rule settings validation may need further clarification. Below is a list. For more information about specific rule configurations, consult Cloud Conformity Services Endpoint

Error Details Resolution
This Real-Time Threat Monitoring package rule rule.id is not part of the account subscription Remove that rule setting from the array
ruleId is not configurable from this endpoint. This is an organisation-setting which you cannot configure via this account rule settings endpoint.
Rule risk level missing for ruleId ruleSetting.riskLevel is a required parameter
Rule risk level provided for ruleId is incorrect only "LOW", "MEDIUM", "HIGH", "VERY_HIGH", and "EXTREME" are accepted risk levels
Rule enable status is not valid for ruleId ruleSetting.enabled is a required boolean parameter
One or more rule setting property is invalid for ruleId remove the ruleSetting property if it is not id, enabled, riskLevel, extraSettings, or ruleExists
Provider XXX is invalid for ruleId provider must match the cloud provider for the rule

Extra Settings Rule ruleId is not configurable | remove ruleSetting.extraSettings, you may only change risk level or enable/disable this rule. If you are directly copying this rule from another account and getting this message, this rule may have been previously configurable and is no longer.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Request Body schema: application/vnd.api+json
object
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Request samples
application/vnd.api+json
{
  • "data": {
    }
}
Response samples
application/json
{
  • "data": {
    }
}

Get Account Bot Settings

get/accounts/{id}/settings/bot

This endpoint allows you to get the current settings of the Conformity Bot for an account.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Response samples
application/json
{
  • "data": [
    ]
}

Update Account Bot Setting

patch/accounts/{id}/settings/bot

This endpoint allows ADMIN, POWER USERS, and users with CUSTOM access to accounts to get the current setting that Cloud Conformity uses to determine when Conformity Bot is run and on which regions the Conformity Bot is disabled. This endpoint also supports updating single attributes under the settings field (see below) in which case, only attributes passed in the request body will be updated.

Example Request to update all attributes:
This request disables the Conformity Bot for two accounts. Conformity Bot is disabled in all regions until the specified date-time, after which it will run every 10 hours for all regions besides us-west-2.

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey eab0b7914c3ebv45bcK02cW33ff9564cec8" \
-d '
{
  "data": {
    "type": "accounts",
    "attributes": {
      "settings": {
        "bot": {
          "delay": 10,
          "disabledRegions": {
             "us-west-2": true
           },
           "disabled": true,
           "disabledUntil": 1591751339519,
        }
      }
    }
  },
  "meta": {
       "otherAccounts": ["cfe80897"]
  }
};' \
https://us-west-2-api.cloudconformity.com/v1/accounts/2fwmithMj/settings/bot

Example Response:

{
  "data": [
    {
      "type": "accounts",
      "id": "2fwmithMj",
      "attributes": {
        "name": "Test AWS Account",
        // ...
        "settings": {
          "rules": [
            // ...
          ],
          "bot": {
            "lastModifiedFrom": "12.345.67.890",
            "delay": 10,
            "disabledRegions": {
              "us-west-2": true
            },
            "disabled": true,
            "disabledUntil": 1591751339519,
            "lastModifiedBy": "3456d0"
          }
        },
        // ...
        "cloud-type": "aws",
        "managed-group-id": "23784h"
      },
      "relationships": {
        "organisation": {
          "data": {
            "type": "organisations",
            "id": "moid324"
          }
        }
      }
    },
    {
      "type": "accounts",
      "id": "cfe80897",
      "attributes": {
        "name": "Test Azure Account",
        // ...
        "settings": {
          "rules": [
            // ...
          ],
          "bot": {
            "lastModifiedFrom": "12.345.67.890",
            "delay": 10,
            "disabled": true,
            "disabledUntil": 1591751339519,
            "lastModifiedBy": "3456d0"
          }
        },
        // ...
        "cloud-type": "azure",
        "managed-group-id": "23784h"
      },
      "relationships": {
        "organisation": {
          "data": {
            "type": "organisations",
            "id": "moid324"
          }
        }
      }
    }
  ]
}

Other requests for example use cases:
Temporarily disable Conformity Bot until the specified date-time:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey eab0b7914c3ebv45bcK02cW33ff9564cec8" \
-d '
{
  "data": {
    "type": "accounts",
    "attributes": {
      "settings": {
        "bot": {
          "disabled": true,
          "disabledUntil": 1591751339519,
        }
      }
    }
  }
};' \
https://us-west-2-api.cloudconformity.com/v1/accounts/2fwmithMj/settings/bot

Disable Conformity Bot indefinitely:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey eab0b7914c3ebv45bcK02cW33ff9564cec8" \
-d '
{
  "data": {
    "type": "accounts",
    "attributes": {
      "settings": {
        "bot": {
          "disabled": true
        }
      }
    }
  }
};' \
https://us-west-2-api.cloudconformity.com/v1/accounts/2fwmithMj/settings/bot

Disable Conformity Bot runs for a few regions and increase delay between enabled regions:

curl -X PATCH \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey eab0b7914c3ebv45bcK02cW33ff9564cec8" \
-d '
{
  "data": {
    "type": "accounts",
    "attributes": {
      "settings": {
        "bot": {
          "delay": 10,
          "disabledRegions": {
            "us-east-1": true,
            "us-east-2": true,
            "us-west-2": true,
            "ap-southeast-2": true
          }
        }
      }
    }
  }
};' \
https://us-west-2-api.cloudconformity.com/v1/accounts/2fwmithMj/settings/bot
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Request Body schema: application/vnd.api+json
required
object
id
required
string

The Cloud Conformity ID of the account.

object

a JSON object containing JSONAPI compliant data object.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Request samples
application/vnd.api+json
{
  • "id": "u_9NRVPBC",
  • "data": {
    },
  • "meta": {
    }
}
Response samples
application/json
{
  • "data": [
    ]
}

Scan Account

post/accounts/{id}/scan

This endpoint allows you to run Conformity Bot for the specified account.

IMPORTANT:

This operation makes API calls to AWS on your behalf.
Amazon throttles API requests for each AWS account on a per-region basis to help the performance of the service.
To avoid API throttling, it's important to ensure that your application doesn't use this API at a high rate.
Refer to AWS Service Limits to find out more about AWS throttle rate.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the account.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

Response samples
application/json
{
  • "data": [
    ]
}