Profiles

Managing Conformity profiles.

Organisation Profile

Organisation profiles work with the existing Profiles API.

The Organisation profile Id is in this format:

organisation-${organisationId}

If the organisationId was 123-456-789, the Organisation Profile Id would be: organisation-123-456-789

To get the organisation profile, as an example, you would do:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
https://us-west-2-api.cloudconformity.com/v1/profiles/organisation-123-456-789

User Privileges

There are 4 possible Cloud Conformity roles. Each role grants different levels of access via the api. The roles are:

  • organisation admin
  • organisation user with full access to account
  • organisation user with read-only access to account
  • organisation user with no access to account

User access to each endpoint is listed below:

Endpoint admin full access user read-only user no access user
GET /profiles (get a list of profiles) Y Y Y N
GET /profiles/id (get details about a profile and rule settings) Y N N N
POST /profiles (save a profile and rule settings) Y N N N
PATCH /profiles/id (update a profile and rule settings) Y N N N
DELETE /profiles/id (delete a profile and rule settings) Y N N N
POST /profiles/id/apply (apply a profile to a set of accounts) Y N N N

Response will depend on the ProfileId's, Include Settings flag and Types condition added to the query parameter. For example, if a user has no access to a profile and they modify profile details, an error will be thrown. Alternatively, if a user has no access to a profile and they modify rule settings for that profile, an error will be thrown.

Parameters Details Value
includes This parameter provides the option to include additional information to the profile. Currently, only Rule Settings is supported. ruleSettings

List All Profiles

get/profiles

This endpoint displays a list of profiles associated to an organisation.

Example Request:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
https://us-west-2-api.cloudconformity.com/v1/profiles/

Example Response:


{
  "data": [
    {
      "type": "profiles",
      "id": {profile-id},
      "attributes": {
        "name": "Test-Profile-1",
        "description": "A test profile with rule settings"
      }
    },
    {
      "type": "profiles",
      "id": {profile-id},
      "attributes": {
          "name": "Test-Profile-2",
          "description": "A second test profile with rule settings"
      }
    }, ...more profiles
  ]
}
SecurityApiKeyAuth
Responses
200

OK

403

Forbidden. This happens when a valid api key is not provided or the user does not have access to the profile.

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

Save New Profile and Rule Settings

post/profiles

This endpoint allows you to create a new profile and subsequently add rule settings to the new profile. Saving rule settings via this endpoint will overwrite existing settings with those passed in the request. This allows for the following requests to be made:

Request Details Parameters
Saving a new profile Save a new profile with name and description Profile name and description
Save new profile with rule settings included Save a new profile and a batch of configured rule settings upon profile creation Profile name and description, and rule settings
Save rule settings to an existing Profile Add a batch of configured rule settings to an empty profile or overwrite existing rule settings and profile details Profile details and Rule settings
Delete all settings Retain the profile but clear all rule settings Profile ID

Saving a new Profile

The expected behavior of this request is to create a new profile.

Example request for saving a new profile:

curl -X POST -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
  "data": {
    "type": "profiles",
    "attributes": {
      "name": "New-Test-Profile",
      "description": "A test description for a new profile."
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/profiles/

Example Response:

{
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "New-Test-Profile",
      "description": "A test description for a new profile."
    }
  }
}

Save new profile with rule settings included

The expected behavior of this request is to save a new profile and configure new rule settings associated with that profile.

Note: A deprecation warning will be included in the response for rules that are deprecated.

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this profile is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": ["EC2-XXX"]
      }
    }
  }
}

Example request for new profile creation including rule settings:

curl -X POST -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
  "included": [
    {
      "type": "rules",
      "id": "EC2-001",
      "attributes": {
        "enabled": false,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "RTM-002",
      "attributes": {
        "enabled": true,
        "extraSettings": [
          {
            "name": "ttl",
            "type": "ttl",
            "value": 72,
            "ttl": true
          }
        ],
        "riskLevel": "MEDIUM",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "attributes": {
      "name": "New-Test-Profile",
      "description": "A test description for a new profile with rule settings."
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-001"
          },
          {
            "type": "rules",
            "id": "RTM-002"
          }
        ]
      }
    }
  }
}
'\
https://us-west-2-api.cloudconformity.com/v1/profiles/

Example Response:

{
  "included": [
    {
      "type": "rules",
      "id": "EC2-001",
      "attributes": {
        "enabled": false,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "RTM-002",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": [],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [
          {
            "name": "ttl",
            "type": "ttl",
            "value": 72,
            "ttl": true
          }
        ],
        "riskLevel": "MEDIUM",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Test-Profile-1",
      "description": "A test description for a new profile with rule settings."
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-001"
          },
          {
            "type": "rules",
            "id": "RTM-002"
          }
        ]
      }
    }
  }
}

Save rule settings to an existing Profile

The expected behavior of this is request to overwrite all existing rule settings to a configured profile or write new rule settings to an existing empty profile.

You must indicate the Profile ID in the request body otherwise a new profile will be created with the indicated rule settings configured.

Example request for saving rule settings:

curl -X POST -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
  "included": [
    {
      "type": "rules",
      "id": "EC2-001",
      "attributes": {
        "enabled": false,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "RTM-002",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": [],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [
          {
            "name": "ttl",
            "type": "ttl",
            "value": 72,
            "ttl": true
          }
        ],
        "riskLevel": "MEDIUM",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Test-Profile-1",
      "description": "A test description for an existing profile."
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-001"
          },
          {
            "type": "rules",
            "id": "RTM-002"
          }
        ]
      }
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/profiles/

Example Response:

{
  "included": [
    {
      "type": "rules",
      "id": "EC2-001",
      "attributes": {
        "enabled": false,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "RTM-002",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": [],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [
          {
            "name": "ttl",
            "type": "ttl",
            "value": 72,
            "ttl": true
          }
        ],
        "riskLevel": "MEDIUM",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Test-Profile-1",
      "description": "A test description for an existing profile."
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-001"
          },
          {
            "type": "rules",
            "id": "RTM-002"
          }
        ]
      }
    }
  }
}

Delete all settings

The expected behaviour of this request to preserve an existing profile's attributes while deleting all existing rule settings. To do so, exclude the "includes" and "relationships" field from the request.

Example request for modifying an existing profile and deleting its settings:

curl -X POST -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
    "data": {
      "type": "profiles",
      "id": {profile-id},
      "attributes": {
        "name": "New-Test-Profile",
        "description": "A test description for a new profile."
      }
    }
  }' \
https://us-west-2-api.cloudconformity.com/v1/profiles/

Example Response:

{
  "meta": {},
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "New-Test-Profile",
      "description": "A test description for a new profile."
    }
  }
}
SecurityApiKeyAuth
Request
Request Body schema: application/json
object
id
string

Profile ID.

Array of objects (profile-rule-setting)
Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

Request samples
application/json
{
  • "id": "d9yHTrzP0",
  • "data": {
    },
  • "included": [
    ]
}
Response samples
application/json
{
  • "data": {
    },
  • "included": [
    ]
}

Get Profile and Rule Settings

get/profiles/{id}

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

Getting Profile Details

Example request for getting details of a profile:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
https://us-west-2-api.cloudconformity.com/v1/profiles/{profile-id}

Example Response:

{
  "meta": {},
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Test-Profile-1",
      "description": "A test profile."
    }
  }
}
Getting Profile Details with Included Rule Settings

Example request to get a profile and its rule settings.

Note: A deprecation warning will be included in the response for rules that are deprecated.

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
https://us-west-2-api.cloudconformity.com/v1/profiles/{profile-id}?includes=ruleSettings

Example Response:

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this profile is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": [
            "EC2-XXX"
        ]
      }
    }
  },
  "included": [
    {
      "type": "rules",
      "id": "EC2-001",
      "attributes": {
        "enabled": false,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "RTM-002",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": [],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [
          {
            "name": "ttl",
            "type": "ttl",
            "value": 72,
            "ttl": true
          }
        ],
        "riskLevel": "MEDIUM",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Test-Profile-1",
      "description": "A test profile."
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-001"
          },
          {
            "type": "rules",
            "id": "RTM-002"
          }
        ]
      }
    }
  }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the profile.

query Parameters
includes
string
Default: "ruleSettings"

The extra information .

Responses
200

OK

403

Forbidden. The requesting user does not have enough privilege.

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

Delete Profile and Rule Settings

delete/profiles/{id}

This endpoint allows ADMINs to delete a specified profile and all affiliated rule settings.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the profile.

Responses
200

OK

403

Forbidden. The requesting user does not have enough privilege.

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

Update Profile and Rule Settings

patch/profiles/{id}

This endpoint allows you to update profile details and its associated rule settings. Only the settings passed in the request will be added/updated and no other existing rule settings will be affected.

Note: A deprecation warning will be included in the response for rules that are deprecated.

{
  "meta": {
    "deprecation": {
      "warning": {
        "message": "1 manually configured rule in this profile is deprecated. Refer to our Help Pages for instructions.",
        "link": "https://www.cloudconformity.com/help/rules.html",
        "rules": ["EC2-XXX"]
      }
    }
  }
}

Example request to only update profile details - name and description:

curl -X PATCH -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "New-Name-Test-Profile",
      "description": "Updated test description for a new profile."
    }
  }
}' \
https://us-west-2-api.cloudconformity.com/v1/profiles/{profile-id}

Example Response:

{
  "meta": {},
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "New-Name-Test-Profile",
      "description": "Updated test description for a new profile."
    }
  }
}

To update rule settings along with your profile, only the settings passed in the request will be added/updated and no other existing rule settings will be affected.

Example request to update profile details and add one rule setting to existing settings:

curl -X PATCH -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
  "included": [
    {
      "type": "rules",
      "id": "EC2-006",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Update-Test-Profile",
      "description": "Update test description"
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-006"
          }
        ]
      }
    }
  }
}'\
https://us-west-2-api.cloudconformity.com/v1/profiles/{profile-id}

Example Response:

{
  "meta": {},
  "included": [
    {
      "type": "rules",
      "id": "EC2-001",
      "attributes": {
        "enabled": false,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "EC2-006",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": ["TestUpdateTags"],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [],
        "riskLevel": "LOW",
        "provider": "aws"
      }
    },
    {
      "type": "rules",
      "id": "RTM-002",
      "attributes": {
        "enabled": true,
        "exceptions": {
          "tags": [],
          "filterTags": [],
          "resources": []
        },
        "extraSettings": [
          {
            "name": "ttl",
            "type": "ttl",
            "value": 72,
            "ttl": true
          }
        ],
        "riskLevel": "MEDIUM",
        "provider": "aws"
      }
    }
  ],
  "data": {
    "type": "profiles",
    "id": {profile-id},
    "attributes": {
      "name": "Update-Test-Profile",
      "description": "Update test description"
    },
    "relationships": {
      "ruleSettings": {
        "data": [
          {
            "type": "rules",
            "id": "EC2-001"
          },
          {
            "type": "rules",
            "id": "EC2-006"
          },
          {
            "type": "rules",
            "id": "RTM-002"
          }
        ]
      }
    }
  }
}
SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the profile.

Request Body schema: application/json
object
Array of objects (profile-rule-setting)

List of rule settings.

Responses
200

OK

401

Unauthorized. The requesting user does not have enough privilege.

403

Forbidden. The requesting user does not have enough privilege.

422

Unprocessed Entity. Validation error.

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

Apply Profile to Accounts

post/profiles/{id}/apply

This endpoint allows you to apply profile and rule settings to a set of accounts under your organisation.

Modes

Mode Details
fill-gaps Merge existing settings with this Profile. If there is a conflict, the account's existing setting will be used.
overwrite Merge existing settings with this Profile. If there is a conflict, the Profile's setting will be used.
replace Clear all existing settings and apply settings from this Profile.

Example requests for applying a profile to accounts

Using overwrite mode:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
    "meta": {
        "accountIds": [{account-id-1}, {account-id-2}],
        "types": ["rule"],
        "mode": "overwrite",
        "notes": "Applying profile to accounts",
                "include" : {
                    "exceptions": false
                }
    }
}' https://us-west-2-api.cloudconformity.com/v1/profiles/{profile-id}/apply

Using fill-gaps mode:

curl -H "Content-Type: application/vnd.api+json" \
-H "Authorization: ApiKey YOUR-API-KEY" \
-d '
{
    "meta": {
        "accountIds": [{account-id-1}, {account-id-2}],
        "types": ["rule"],
        "mode": "fill-gaps",
        "notes": "Applying profile to accounts"
    }
}' https://us-west-2-api.cloudconformity.com/v1/profiles/{profile-id}/apply

Example Response:

{
  "meta": {
    "status": "sent",
    "message": "Profile will be applied to the accounts in background"
  }
}

Using the include parameter

When using the overwrite mode when applying a profile to account/s, there might be data on an account's rule settings that you want to retain, e.g. You want to replace the enabled, extraSettings and riskLevel but wish to keep the exceptions.

When using the:

{
  "include": {
    "exceptions": true
  }
}

parameter in the meta part of the request, setting the exceptions to true or false alters how the profile rule setting is applied to the account rule setting.

For example, given a rule setting in a profile:

{
  "id": "EC2-001",
  "enabled": "true",
  "riskLevel": "LOW"
}

And the same rule setting in an account:

{
  "id": "EC2-001",
  "enabled": "false",
  "riskLevel": "EXTREME",
  "exceptions": {
    "resources": ["i-098765432"],
    "tags": ["development"],
    "filterTags": ["stage"]
  }
}

When the applying the profile to the account using the overwrite mode, the resulting rule setting will appear as per the table below:
Note: Currently, only exceptions configuration is supported.

Without "include" in the request Using "include" with "exceptions" set to true in the request Using "include" with "exceptions" set to false in the request
{
  "id": "EC2-001",
  "enabled": "true",
  "riskLevel": "LOW"
}
            
{
  "id": "EC2-001",
  "enabled": "true",
  "riskLevel": "LOW"
}
            
{
  "id": "EC2-001",
  "enabled": "true",
  "riskLevel": "LOW",
  "exceptions": {
    "resources": ["i-098765432"],
    "tags": ["development"],
    "filterTags": ["stage"]
  }
}
            

By default, omitting the include field defaults to all configurations in the account rule setting being overwritten by the profile's. For more information, refer to the Profiles Help Pages.

SecurityApiKeyAuth
Request
path Parameters
id
required
string

The Cloud Conformity ID of the profile.

Request Body schema: application/json
object
Responses
200

OK

403

Forbidden. The requesting user does not have enough privilege.

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