Control: an automated or manual process designed to help safeguard an organisation and minimise risks to its objectives through preventative or detective measures.
Rule: an AWS, GCP, Azure or Conformity Rule.
Compliance Standard: an organised mapping of Controls to Rules.
Original Compliance Standard: the ready-made compliance standard available without customization.
Level: Custom Compliance Standards organise their Controls under Headings. A Custom Compliance Standard can have any number of headings, but controls can only be organized up to 3 Levels.
Custom Compliance Standard Editing Types

A Custom Compliance Standard can be in one of two editing types:

DRAFT: you can edit and update a standard when it's a work in progress i.e. before it is published.
PUBLISHED: you cannot edit or update a standard once it's published.

We recommend that you do not 'PUBLISH' a standard and keep it in the `DRAFT' state until it's finalised.

If you do need to update a PUBLISHED standard, create a new standard with a different name or version and then start editing it.

If an Original Compliance Standard is updated, you must update your Custom Compliance Standard as well to ensure that it keeps on working as intended. We recommend creating a new standard with the same name but a different version instead of continuing to use the outdated standard.

How to Create/Read/Update/Delete (CRUD) a Custom Compliance Standard using the API?

Refer to our API reference for Creating, Updating, Deleting and Getting Custom Compliance Standards.

Custom Compliance Standards API Features

Visibility Toggling: allows you to hide Custom Compliance Standards on the UI by setting the parameter isEnabled to false using the POST and PUT requests.
Editing Modes: allows you to set the type field to DRAFT until a standard is finalised. Once you are ready you can use the PUT request to set the type to PUBLISHED to lock it from further edits.
Versioning: version allows you to set versions for your Custom Compliance Standards.
Level 3 Headings: allows you to handle controls up to 3 levels of headings as compared to previously supported 2 headings.
External URL: you can use the externalUrl with each control as a link to get additional information about a specific control.
Validation: validates user standards and provides error messages to assist with debugging.

Disabling or deleting an in-use Custom Compliance Standard

If an active Custom Compliance Standard is used in any existing report configurations, the user will receive an error when trying to disable or delete the Custom Compliance Standard.

Only after the Custom Compliance Standard is no longer in use (report configurations updated or deleted) can it be disabled or deleted. See API reference for more details.

Features you can access in the Conformity UI

Once created via the API, Custom Compliance Standards have the same set of features as a normal standard. You can:

View: the Custom Compliance Standards from the Standards & Frameworks section under 'Browse All Checks'.
Filter: the Custom Compliance Standards in Simple Filters or CQL.
Create reports: using the Custom Compliance Standards and download as a PDF or CSV.
Schedule a report: automate generation of a Custom Compliance Standard report.

Example - Creating Custom Compliance Standard for CIS Amazon Web Services Foundations Benchmark v2.0.0

Following the annotations in the below image, convert the Headings, Control ID's, Control Titles and map the necessary Rules to Controls into the POST /compliance-standards/custom endpoint.
After sending the request, run Conformity Bot from the UI.
You can now view checks on your Custom Compliance Standard.

Maintaining a Custom Compliance Standard

You will have to maintain and update your Custom Compliance Standards in the following scenarios:

New Rule Releases by Conformity.
Updates to the original Compliance Standard definition used to create a Custom Compliance Standard.

Recommended Resolution

Fetch your standard from GET /compliance-standards/custom/{id}, if you have forgotten the ID you can use GET /compliance-standards/custom to fetch a list of all custom compliance standards and search for the one you want to edit.
Paste the result of GET /compliance-standards/custom/{id} into either:
PUT /compliance-standards/custom/{id} if the standard is in the DRAFT state.
POST /compliance-standards/custom if the standard is in PUBLISHED state (because you cannot edit a PUBLISHED standard in the PUT endpoint, you have to create a new one.)
Edit the standard, update the version, and select if you wish the mapping to be DRAFTor PUBLISHED.
(optional): If you've used the POST endpoint in Step 2, you can also deprecate the previous standard by updating the parameter isEnabled to false or hard deleting the standard with DELETE /compliance-standards/custom/{id}.

Debugging Validation Errors in the Custom Compliance Standard

Conformity sends a response containing a JSON Pointer and details of the issue in case of a validation error. Please see the tips below on debugging the error messages:

Use of Array Indexes: the error messages use array indexes as the values to specify the exact location of the error. For example, in "pointer": "/data/attributes/controls/1/awsRules" the number 1 indicates the second item in the array.
Use of Consistent Properties: since the Control array can be large, you can search for a consistent property like "aid": and go to the search result indicated by the count, plus one to account for array indexes. As an example, in the image below, you can view that we have gone to the 2nd search result, and we can clearly see the issue is a missing level1 heading and a duplicate rule.

Example Template

{
  "data": {
    "name": "My Custom Compliance Standard",
    "isEnabled": true,
    "version": "v1.0.0",
    "type": "DRAFT",
    "description": "This is a template custom compliance standard",
    "controls": [
      {
        "aid": "0.0.1",
        "title": "This is the title of my first control",
        "headings": {
          "level1": "Heading 1",
          "level2": "Heading 2",
          "level3": "Heading 3"
        },
        "externalUrl": "Insert a URL here to link to more information about this control",
        "awsRules": ["S3-001"],
        "azureRules": ["StorageAccounts-012"],
        "gcpRules": ["ResourceManager-001"]
      }
    ]
  }
}

Topics on this page

Custom Compliance Standards

About Custom Compliance Standards

Concepts and Terminology