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
  ]
}

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:

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."
    }
  }
}

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"
          }
        ]
      }
    }
  }
}

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

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"
          }
        ]
      }
    }
  }
}

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

Modes

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.

{
  "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.