Conformity’s core engine is the Conformity Bot, which ingests read-only API meta data from your cloud accounts and assesses the information through best practice logic called ‘rules'.

Popular use-cases and compliance standards are covered by Conformity out-of-the-box. However, your organization may have a variety of use-cases that require customization.

By providing a flexible framework, you can create your own niche rules.

Conformity Custom Rules aims to:

Empower you to create customizable and specific rules that form checks based on the cloud configuration data stored by Conformity.
Provides you freedom from dependency on the existing ‘rule settings’ framework allowing you to embed all the configuration options in the custom rule configuration.
Optimize the generic set of languages and tools for you as a developer.
Leverage existing Conformity features such as rule filtering, suppressing checks, communication channels, and reports, so that the core experience is the same as out of the box rules.

Key Feature Summary

Conformity Custom Rules allows for an organization API user to create, update, delete, get, and execute custom rules via API.
Creating and updating of custom rules via API supports configuration settings as a part of the request body payload and are saved to the organization.
- The Custom Rules documentation includes an example library of custom rule templates to help you structure the API request body.
- The API documentation also includes example templates of cloud resource data which a user can use to reference the JSON structure.
- In addition to sample templates, users can query the existing cloud resource data inside their account to further reference the JSON structure of the resource data.
Designed for creating highly specific checks for one type of resource or set of conditions, Conformity Custom Rules use a combination of JSON and jsonpath , a well-documented JSON syntax for querying resource data, which is used as part of the rule logic/evaluation process.
Conformity Custom Rules support multiple rules and conditions against a single resource to be configured as part of one custom rule.
Custom rules checks can be filtered based on the same wide range of parameters as out-of-the-box rules, including resource types, resource ID, tags etc. Custom rules can also assess any data contained within the resource data of the chosen resource.
As a flexible and open framework, it is possible to create highly complex and specific logic including nesting and relating multiple conditions.
You can ‘dry run’ your custom rules using dummy data before saving one.
You can also use the ‘dry run’ endpoint to query your own organization resource data to use as a reference for creating custom rule logic.
You can include remediation steps in the custom rule, which are displayed alongside custom rule check data in the application and PDF reports.
Conformity Custom Rules support some basic data validation and error handling.
When executed by Conformity Bot or RTM, the custom rule checks appear in the Conformity console.
Custom rules are currently supported by the following existing checks:
- Browsing and filerting checks
- Reports
- Communication channels
- Suppression

Using Custom Rules

To activate Custom Rules for your organization, request access by sending an email to alloftrendproduct-conformity@trendmicro.com.
Please provide the following details with your request:
- Name of the Organization account in Conformity
- Whether access is via Cloud One or Conformity Standalone (i.e. cloudconformity.com)
- List key contacts
Ensure you are an Administrator user, and have an API key set up.
To get comfortable with the Custom Rules API, we highly recommend using an API management tool (e.g., Postman) to more easily save, reuse, and manage API payloads during testing and implementation.
For more complete usage examples and details of API endpoints available, refer to the Custom Rules API documentation.
For an introductory guide with example workflows, refer to Getting Started with Conformity Custom Rules.

Custom Rule Configuration

Anatomy of a custom rule configuration

Definitions

attributes: collection of user defined attribute names and the associated resource value that will be used as part of the rule logic/evaluation
rules*: a set of rules for the custom rule
conditions*: the conditions object for a rule set
facts*: the related attribute name in which the value can be found
events: the name or description of the rule set.

General parameters

name: Name or title of custom rule
description: Optional description value
severity: Risk/severity level of the custom rule, can be one of the following: LOW, MEDIUM, HIGH, VERY HIGH.
categories: An array of category best practice pillar strings, can be any of the following: security, reliability, performance-efficiency, cost-optimisation, operation-excellence.
remediationNotes: Optional text description of notes or steps relevant to remediation.
enabled: Boolean indicating status of a rule, disabled rules (i.e., enabled set to false) will not be run by Conformity Bot or Real-Time Threat Monitoring (RTM).
provider: Cloud provider (e.g., aws, azure, gcp). For a complete list, please refer to Conformity Providers Endpoint

Resource parameters

service: The cloud provider service name (e.g., S3). For a complete list of supported services, please refer to Conformity Services Endpoint.
resourceType: The type of resource this custom rule applies to (e.g., s3-bucket). For a complete list, please refer to Conformity Resource Types Endpoint.
attributes: (array of objects)
name: user defined to the value of the result of the path query, this value is used as the fact input to the rule condition
path: jsonpath syntax to resource value
required: Boolean that determines if this data value is required for the rule to run. If required is set to true and the result of the attribute path is undefined, the rule will not run as it does not have the necessary data to provide an accurate result. In cases where data being undefined can be expected, setting required: false, will allow the rule to run regardless.

Rule parameters

rules: (array) a custom rule can have multiple rule sets
conditions (object): Each condition must begin with all or any at its root.
any/all (array): these conditions can be nested (see example below)
fact: attribute value, must have a matching attribute name
operator:
parameters:
- String (equal, notEqual, pattern) * Note: pattern is a custom operator which can match a regular expression (regex)
- Number (equal, notEqual, lessThan, lessThanInclusive, greaterThan, greaterThanInclusive)
- Array (in, notIn, contains, doesNotContain)
- value: expected value of attribute, If the result is truthy, the condition passes.
path: jsonpath syntax for nested values
event:
parameter:
- type: this is the value that is returned for the rule set required

Operators

The operator in each rule condition compares the value of the fact to what is set in the value property. If the result is truthy, the condition passes.

Regex:

pattern: fact must pass regex pattern set in value

String and Numbers:

equal: fact must equal value
notEqual: fact must not equal value

these operators use strict equality (===) and inequality (!==)

Numeric:

lessThan: fact must be less than value
lessThanInclusive: fact must be less than or equal to value
greaterThan: fact must be greater than value
greaterThanInclusive: fact must be greater than or equal to value

Array:

in: fact must be included in value (an array)
notIn: fact must not be included in value (an array)
contains: fact (an array) must include value
doesNotContain: fact (an array) must not include value

Null or Undefined:

isNullOrUndefined: fact must be null or undefined if value is true

Date:

dateComparison: a operator to compare a date fact
- The value should be an object includes days and operator properties
  - days: the number of days to compare the fact date to
  - operator: the operator to use for the comparison. Can be one of the following: within, olderThan
- Example:
```
{
  "fact": "CreationDate",
  "operator": "dateComparison",
  "value": 
    {
      "days": 30,
      "operator": "within"
    }
}
```

Example Configurations

To see custom rule sample configurations, please refer to example library here.

Check Results

A rule must pass all conditions for it to be considered a successful check and return a SUCCESS result. If any rule conditions fail, the rule will return a FAILURE result including any failing rule events as part of the check metadata.

The check result message does not require any configuration. The message is automatically formatted based on the settings and whether the rule conditions pass or fail.

Format: {resourceType} {resourceName} passed/failed {ruleEvent} and {Number(ruleConditions - 1)} more rule conditions.

Example Success Result

Example: S3 Bucket bobs-website-bucket passed 'Bucket has encryption enabled' and 1 more rule condition.

{
  "region": "ap-southeast-2",
  "resource": "bobs-website-bucket",
  "ccrn": "ccrn:aws:abc123ABC-:S3:ap-southeast-2:bobs-website-bucket",
  "status": "SUCCESS",
  "message": "S3 Bucket bobs-website-bucket passed 'Bucket has encryption enabled' and 1 more rule condition.",
  "extradata": [
    {
      "name": "successEvent",
      "label": "Passed Condition Event",
      "value": "Bucket has encryption enabled",
      "type": "META"
    },
    {
      "name": "successEvent",
      "label": "Passed Condition Event",
      "value": "Bucket has versioning enabled",
      "type": "META"
    }
  ]
}

Example Failure Result

Example: S3 Bucket bobs-website-bucket failed failed 'Bucket has encryption enabled'.

{
  "region": "ap-southeast-2",
  "resource": "bobs-website-bucket",
  "ccrn": "ccrn:aws:abc123ABC-:S3:ap-southeast-2:bobs-website-bucket",
  "status": "FAILURE",
  "message": "S3 Bucket bobs-website-bucket failed 'Bucket has encryption enabled' and 1 more rule condition.",
  "extradata": [
    {
      "name": "failedEvent",
      "label": "Failed Condition Event",
      "value": "Bucket has encryption enabled",
      "type": "META"
    },
    {
      "name": "failedEvent",
      "label": "Failed Condition Event",
      "value": "Bucket has versioning enabled",
      "type": "META"
    }
  ]
}

API Endpoints

Endpoint
POST /custom-rules/ - Create a new custom rule
PUT /custom-rules/{id} - Update custom rule configuration
GET /custom-rules/ - List custom rules
GET /custom-rules/{id} - Get specified rule
DELETE /custom-rules/{id} - Permanently delete custom rule. Note: This is an immediate action. It is recommended to disable any custom rules for one Conformity Bot cycle across accounts prior to deleting.
POST /custom-rules/run - Executes custom rule

Executing custom rule ‘run’ endpoint with parameters
POST /custom-rules/run?accountId={accountId}&id={ruleId} - Posting to this route with the rule ID will execute this rule against the account provided and return the result(s) as part of the response.
POST /custom-rules/run?accountId={accountId} - Posting to this route with a rule config as part of the request body will execute this rule configuration and return the results(s) as part of the response.
POST /custom-rules/run - Posting to this route with a rule configuration and resource data as part of the request body will execute this rule configuration against provided resource data and return the results(s) as part of the response.
POST /custom-rules/run?accountId={accountId}&resourceData=true - Posting to this route with specific resource id in the rule configuration request body will return the resource data along with the check result.

Frequently Asked Questions

How do get access to Conformity Custom Rules?

To activate Custom Rules for your organization, request access by sending an email to alloftrendproduct-conformity@trendmicro.com.
Please provide the following details with your request:
- Name of the Organization account in Conformity
- Whether access is via Cloud One or Conformity Standalone (i.e. cloudconformity.com)
- List key contacts
- A list of users with email addresses who will be added to our shared product slack channel
- this will be forum to ask questions and provide feedback on custom rules.

Can I create custom rules for services Conformity does not yet support?

Not all services are automatically supported, however it is possible to create custom rules for any service that has data available. In order to access specific data, the Conformity Bot must ingest that data from your account using something called an inventory process that makes the relevant API calls. If there is a service that you would like to see supported in addition to the services we currently support, please raise a feature request.

How do I implement exceptions in my custom rule?

Conformity Custom Rules do not have conventional settings configurations like out-of-the box Conformity rules (e.g., exceptions). Instead, you can define a unique attribute which identifies a specific resource name, andname and create specific condition statement which reference the condition as a fact to exclude or include the check based on matching the condition with the appropriate operator.

There are ways to implement equivalents to exceptions by building conditions that automatically pass SUCCESS for a resource that matches certain parameters.

Here is an example of a configuration which checks both S3 encryption and public access block, but automatically succeeds for any bucket whose name contains ‘test':

{
  "configuration": {
    "name": "S3 encrypted and public access block - with safelist for 'test'",
    "description": "Check S3 has encryption AND public access block, but safelist 'test' buckets",
    "service": "S3",
    "resourceType": "s3-bucket",
    "severity": "HIGH",
    "enabled": true,
    "provider": "aws",
    "categories": [
      "security"
    ],
    "remediationNotes": "To remediate, follow these steps:\n1. Do as you wish \n2. Step two\n",
    "attributes": [
      {
        "name": "bucketEncryption",
        "path": "data.Encryption",
        "required": true
      },
      {
        "name": "publicAccessBlockConfiguration",
        "path": "data.PublicAccessBlockConfiguration",
        "required": true
      },
      {
        "name": "safeList",
        "path": "data.resourceId",
        "required": true
      }
    ],
    "rules": [
      {
        "conditions": {
          "any": [
            {
              "fact": "safeList",
              "operator": "pattern",
              "value": ".*test.*"
            },
            {
              "all": [
                {
                  "fact": "bucketEncryption",
                  "operator": "notEqual",
                  "value": null
                },
                {
                  "fact": "publicAccessBlockConfiguration",
                  "operator": "notEqual",
                  "value": null
                }
              ]
            }
          ]
        },
        "event": {
          "type": "Bucket has encryption enabled"
        }
      }
    ]
  }
}

How can I make a custom rule only apply to certain accounts in different ways (e.g. like profiles)?

Custom rules are saved to the organization level, which means they are run globally. While there is no concept of defining a ‘no check’ scenario, it is possible to define the rule configuration to contain specific conditions so that a rule might automatically return SUCCESS when applied to specific accounts. For example, you could assign conditions that specify the AWS account id path value from the resource data and apply relevant logic.

How do I determine the resource data options available to query, and is there a data schema or dictionary?

Conformity Custom Rules does not provide a full published resource schema for all cloud resource data, however, we do provide the ability to retrieve your own resource data using the run endpoint. This is because cloud resource data is highly varied depending on the service and which settings are enabled, meaning generating an exhaustive dictionary for all possible options for all services is prohibitively complex and expensive. By providing both sample data for common services, plus the ability to query your own data using the ‘run’ endpoint, you have access to the data you need to be able to create and fine-tuned custom rules.

If you require assistance accessing your resource data, you can also raise a support request for Conformity’s production engineers to assist you in generating sample data.

Can I create complex workflows that combine the result of multiple checks from multiple services?

Advanced users may want to create advanced custom rules that consider conditions from more than one cloud service.

Custom Rules does not currently provide the ability to connect multiple checks in this way, but provides the first layer of the custom rules framework that later versions will build upon. The ability to add more complex workflows that can combine services will be considered in future iterations. This may include the ability to create 'chained' rules that can join existing Conformity rules, custom rules, or custom data and will be driven by your feedback.

How do I test a rule is working as expected?

Users can complete a ‘dry run’ of a rule to test the output using example resource data in the body of the request. When creating rules, this gives the user the chance to validate the syntax and the desired result against a known quantity.

For more details on using the dry run feature, please refer to the custom rules API documentation.

When I test the rule against an account using the API, why is my custom rule data not reflecting correctly based on my latest information in my cloud account?

Latest data reflected is based on data stored by the most recent Conformity Run. When testing a rule, be mindful that the state of the underlying resource may change before Conformity data is updated.

Does the Conformity Custom Rules engine support Real-Time Threat Monitoring (RTM)?

Yes, RTM has the same access to custom rules as any other rule, based on Conformity’s support for the relevant events and services.

For example, if you have a custom rule for an S3 bucket, and RTM detects the S3 configuration change event, RTM will generate checks for the S3 buckets related rules including your custom rule.

You can check the supported services by checking the services endpoint and see which equivalent Conformity rules are supported by RTM.

I am using JSON path to create my rule. Is there anything unique to Conformity’s implementation I need to be mindful of?

By default, if the result of json.path query returns no results, we will return the value 'undefined' as opposed to an empty array, to help with error handling.

By default, certain responses are wrapped in an array even if there is only one result, depending on the query, and a single array will be unwrapped to its primitive value - this can be addressed on a case-by-case basis depending on your rule configuration.

For specific assistance, please feel free to raise a support request.

How do I see a schema for the resource data?

A general schema has not been built for the first iteration of custom rules. This is because the resource data can vary widely depending on the platform and service, and can change frequently based on updates to the Conformity Bot.

Instead, you can use the ‘dry run’ feature to query a specific resource and use this as a reference for the structure of the resource data relevant to the rule you are creating. This way, your reference source is always up-to-date based on real data.

An example workflow of how to query resource data using the run endpoint is included in the Custom Rules - Getting Started Guide .

References

https://goessner.net/articles/JsonPath/
jsonpath-plus
JsonPath Evaluator

Topics on this page

An Overview of Conformity Custom Rules

Introduction