Below is a list of the available API calls:
- Create An Account
- List All Accounts
- Get Account Details
- Scan Account
- Get Rule Setting
- Update Rule Setting
- Get Rule Settings
- Update Rule Settings
This endpoint is used to register a new AWS account with Cloud Conformity.
IMPORTANT: In order to register a new AWS account, you need to:
- Obtain an External Id from Create an External Id (Note: External Ids expire after 1 hour.)
- Configure your account using CloudFormation automation (Note: You need to specify
ExternalIdparameter for both options)-
Option 1 Launch stack via the console:
-
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
-
- Verify stack creation is completed, and then create a new account (see below) with Cloud Conformity using your roleArn and externalId.
POST /accounts
data: an JSON object containing JSONAPI compliant data object with following propertiestype: The type of the object (account)attributes: An attribute object containingname: The Name of the accountenvironment: The Name of the environmentaccess: An object containingkeys: An object containingroleArn: The Role ARN of the role you have already created to grant access to Cloud ConformityexternalId: The External ID that you have requested on the previous step
costPackage: Boolean, true for enabling the cost package add-on for the account (AWS spend analysis, forecasting, monitoring)securityPackage: Boolean, true for enabling the security package add-on for the account (real-time monitoring, additional security rules)
Example Request:
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"
}
},
"costPackage": true,
"securityPackage": true
}
}
}' \
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",
"security-package": true,
"cost-package": 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"
}
}
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B1nHYYpwx"
}
}
}
}
}
This endpoint allows you to query all accounts that you have access to.
GET /accounts
This end point takes no parameters.
Example Request:
curl -H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" https://us-west-2-api.cloudconformity.com/v1/accounts
Example Response:
{
"data": [
{
"type": "accounts",
"id": "AgA12vIwb",
"attributes": {
"name": "Test",
"environment": "Test",
"awsaccount-id": "123456789013",
"security-package": true,
"created-date": 1502472854056,
"last-notified-date": 1503580590169,
"last-checked-date": 1503584192576,
"last-monitoring-event-date": 1502570799000,
"billing-account-id": "r1gyR4cqg"
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B2UhJY3W1"
}
}
}
},
{
"type": "accounts",
"id": "55Yfrq_IT",
"attributes": {
"name": "Route53",
"environment": "Route53",
"awsaccount-id": "123456789012",
"security-package": true,
"cost-package": true,
"created-date": 1489703037251,
"last-notified-date": 1503503192127,
"last-checked-date": 1503503191166,
"last-monitoring-event-date": 1502570252000,
"billing-account-id": "r1gyR4cqg"
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B2UhJY3W1"
}
}
}
}
]
}
This endpoint allows you to get the details of the specified account.
GET /accounts/id
id: The Cloud Conformity ID of the account
Example Request:
curl -H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" https://us-west-2-api.cloudconformity.com/v1/accounts/BJ0Ox16Hb
Example Response:
{
"data": [
{
"type": "accounts",
"id": "ABA95vIw8",
"attributes": {
"name": "Test Account",
"environment": "Test",
"awsaccount-id": "123456789012",
"status": "ACTIVE",
"security-package": true,
"created-date": 1502472854056,
"settings": {
"communication": {
"channels": [
{
"name": "email",
"users": [
"H22rMyTu5"
],
"enabled": true,
"levels": [
"HIGH",
"LOW",
"MEDIUM",
"VERY_HIGH"
]
}
]
}
},
"last-notified-date": 1503285393239,
"last-checked-date": 1503285392447,
"last-monitoring-event-date": 1502570799000,
"billing-account-id": "r1gyR4cqg",
"cost": {
"billing-account-map": {
"payerAccount": {
"awsId": "123456789012",
"id": "r1gyR4cqg"
},
"linkedAccounts": [
{
"awsId": "123456789011",
"id": "BJ0Ox16Hb"
},
{
"awsId": "123456789012",
"id": "BJA95viwb"
},
{
"awsId": "123456789013",
"id": "SyZZUc_il"
},
{
"awsId": "123456789014",
"id": "S1SFeq_ig"
},
{
"awsId": "123456789015",
"id": "SJQINcOol"
},
{
"awsId": "123456789016",
"id": "ryi6NPivW"
}
]
},
"last-updated-date": 1503283806380,
"bills": [
{
"current": true,
"accountCost": 319.55255299999976,
"id": "2017-08",
"status": "succeeded"
}
],
"version": 1.07
},
"bot-status": null
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "A1iUY1pz3"
}
}
}
}
]
}
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.
POST /accounts/id/scan
id: The Cloud Conformity ID of the account
Example Request:
curl -X POST -H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" https://us-west-2-api.cloudconformity.com/v1/accounts/BJ0Ox16Hb/scan
Example Response:
{
"data": [
{
"status": "STARTED"
}
]
}
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.
GET /accounts/accountId/settings/rules/ruleId
accountId: The Cloud Conformity ID of the accountruleId: The ID of the rulenotes: Optional parameter (boolean) to get notes for the specified rule setting
Example Request:
curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/accounts/H19NxMi5-/settings/rules/RDS-018?notes=true
Example Response:
{
"data": {
"type": "accounts",
"id": "H19NxMi5-",
"attributes": {
"settings": {
"rules": [
{
"ruleExists": false,
"riskLevel": "MEDIUM",
"id": "RDS-018",
"extraSettings": [
{
"name": "threshold",
"value": 90
}
],
"enabled": false
}
],
"access": {}
},
"available-runs": 5,
"access": null
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B1nHYYpwx"
}
}
}
},
"meta": {
"notes": [
{
"createdBy": "SYmS0YcL-",
"createdDate": 1511456432526,
"note": "hello world"
}
]
}
}
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:
- Obtain rule setting from the desired account. Get rule setting
- Paste rule setting as is into the body of the PATCH request following the format below.
PATCH /accounts/accountId/settings/rules/ruleId
data: an JSON object containing JSONAPI compliant data object with following propertiesattributes: An attribute object containingruleSetting: An object containingid: Rule Id, same as the one provided in the endpointenabled: Boolean, true for inclusion in bot detection, false for exclusionriskLevel: riskLevel you desire for this rule. Must be one of the following: LOW, MEDIUM, HIGH, VERY_HIGH, EXTREMEextraSettings: An array of object(s) for customisable rules only, containingname: Keywordtype: Rule specific propertycountries/regions/multiple/etc....: Rule specific property (boolean)value: Customisable value for rules that take on single name/value pairsvalues: An array (sometimes of objects) rules that take on a set of of values
note: A detailed message regarding the reason for this rule configuration
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",
"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,
"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"
}
]
}
],
"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"]
}
],
"enabled": false
},
{
"ruleExists": false,
"riskLevel": "MEDIUM",
"id": "RDS-018",
"extraSettings": [
{
"name": "threshold",
"value": 90,
"values": [],
"type": []
}
],
"enabled": false
}
],
"access": {}
},
"available-runs": 5,
"access": null
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B1nHYYpwx"
}
}
}
}
}
Some errors thrown from rule setting validation may need further clarification. Below is a list. For more information about rule specifivities, consult Cloud Conformity Services Endpoint
| Error Details | Resolution |
|---|---|
This security (or cost) 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 either a cost-setting or 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 |
| 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. |
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.
GET /accounts/accountId/settings/rules
accountId: The Cloud Conformity ID of the account
Example Request:
curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey S1YnrbQuWagQS0MvbSchNHDO73XHqdAqH52RxEPGAggOYiXTxrwPfmiTNqQkTq3p" \
https://us-west-2-api.cloudconformity.com/v1/accounts/H19NxMi5-/settings/rules
Example Response:
{
"data": {
"type": "accounts",
"id": "H19NxMi5-",
"attributes": {
"settings": {
"rules": [
{
"ruleExists": false,
"riskLevel": "MEDIUM",
"id": "RDS-018",
"extraSettings": [
{
"name": "threshold",
"value": 90
}
],
"enabled": false
}, {
"riskLevel": "LOW",
"id": "Config-001",
"extraSettings": null,
"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"
}
]
}
],
"enabled": false
}
],
"access": {}
},
"available-runs": 5,
"access": null
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B1nHYYpwx"
}
}
}
}
}
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:
- Obtain rule settings from the desired account. Get rule settings
- Paste rule settings as is into the body of the PATCH request following the format below.
PATCH /accounts/accountId/settings/rules
data: an JSON object containing JSONAPI compliant data object with following propertiesattributes: An attribute object containingnote: A detailed message regarding the reason for this batch of rule configurationsruleSettings: An array of objects, each object containsid: Rule Id, same as the one provided in the endpointenabled: Boolean, true for inclusion in bot detection, false for exclusionriskLevel: riskLevel you desire for this rule. Must be one of the following: LOW, MEDIUM, HIGH, VERY_HIGH, EXTREMEextraSettings: An array of object(s) for customisable rules only, containingname: Keywordtype: Rule specific propertycountries/regions/multiple/etc....: Rule specific property (boolean)value: Customisable value for rules that take on single name/value pairsvalues: An array (sometimes of objects) rules that take on a set of of values
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",
"extraSettings": [
{
"name": "threshold",
"value": 90
}
],
"enabled": false
}, {
"riskLevel": "LOW",
"id": "Config-001",
"extraSettings": null,
"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"
}
]
}
],
"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",
"extraSettings": [
{
"name": "threshold",
"value": 90
}
],
"enabled": false
}, {
"riskLevel": "LOW",
"id": "Config-001",
"extraSettings": null,
"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"
}
]
}
],
"enabled": false
}
],
"access": {}
},
"available-runs": 5,
"access": null
},
"relationships": {
"organisation": {
"data": {
"type": "organisations",
"id": "B1nHYYpwx"
}
}
}
}
}
Some errors thrown from rule settings validation may need further clarification. Below is a list. For more information about rule specifivities, consult Cloud Conformity Services Endpoint
| Error Details | Resolution |
|---|---|
This security (or cost) 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 either a cost-setting or 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 |
| 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. |