+

Creating Custom Governance Rulesets

MuleSoft provides several rulesets in Exchange, such as Anypoint API Best Practices, OpenAPI Best Practices, OWASP API Security Top 10, and Authentication Security Best Practices governance rulesets. You can discover rulesets published in Exchange by filtering the search in Exchange by the Rulesets type. See Search for Assets.

If you need a ruleset other than what is provided, you can submit your ideas for rulesets you would like MuleSoft to provide in future releases on the MuleSoft Ideas Portal. If you want to create a custom ruleset, use one of the following approaches:

Create Custom Rulesets by Modifying Provided Rulesets

If you want to create custom governance rulesets based on rulesets that are already in Exchange, download and modify the rulesets and then upload them as new assets. This is the best approach if a provided ruleset meets most of your needs and you need to make only a few changes.

To create a custom ruleset based on one already in Exchange, use one of the following approaches:

Change Rule Severity or Enable or Disable Rules Using the CLI

To create a custom ruleset using the CLI, use the governance ruleset clone command.

governance ruleset clone

> governance ruleset clone [options] <ruleset> <new_title> <new_description>

This command clones a governance ruleset to create a new custom ruleset and applies specified updates to rules based on the options. The new ruleset is written to standard output.

The new-title parameter gives the title for the new ruleset.

The new description parameter gives the description for the new ruleset.

Run the governance ruleset info command before running this command to get the rule ID information to use in this command.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--remote

Indicates that the ruleset to clone is published in Exchange and that the ruleset parameter is the asset identifier (GAV) for the ruleset.

--error=<list_rules_to_move_to_error>

The error option is followed by the rule IDs for the rules to move to the error severity level section of the ruleset YAML.

--warning=<list_rules_to_move_to_warning>

The warning option is followed by the rule IDs for the rules to move to the warning severity level section of the ruleset YAML.

--info=<list_rules_to_move_to_info>

The info option is followed by the rule IDs for the rules to move to the info severity level section of the ruleset YAML.

--remove=<list_rules_to_disable>

The remove option is followed by the rule IDs for the rules to comment out, and therefore effectively disable, in the ruleset YAML.

Example commands:

anypoint-cli governance ruleset clone ~/Downloads/ruleset.yaml 'New Ruleset from Clone' 'Cloned from ruleset.yaml' --warning=operation-default-response,operation-operationId > mynewruleset.yaml

anypoint-cli governance ruleset clone 668ef6520-13e9-5cf2-c2f6-720225690914/anypoint-best-practices/1.0.2 'Custom Anypoint Best Practices' 'Cloned from MuleSoft Anypoint Best Practices' --remote --remove=openapi-tags,operation-tags > my-anypoint-best-practices.yaml

To list the rules in a ruleset, use the governance ruleset info command.

governance ruleset info

> governance ruleset info [options] <governance-ruleset>

This command lists the ruleset rules in the ruleset definition passed in the governance-ruleset parameter.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--remote

Indicates that the ruleset to clone is published in Exchange and that the ruleset parameter is the asset identifier (GAV) for the ruleset.

Example commands:

anypoint-cli governance ruleset info ~/temp/myruleset.yaml

anypoint-cli governance ruleset info 668ef6520-13e9-5cf2-c2f6-720225690914/anypoint-best-practices/1.0.2 --remote

Example output:

Ruleset /Users/myuser/temp/myruleset.yaml
Violation	operation-default-response
Violation	operation-operationId
Warning  	operation-singular-tag
Warning  	tag-description
Warning  	info-contact
Warning  	info-description
Warning  	info-license
Warning  	license-url
Warning  	openapi-tags
Warning  	operation-description
Warning  	operation-tags
Warning  	operation-tag-defined

Manually Modify Rulesets

To create a custom ruleset manually:

  1. Download the ruleset from Exchange.

  2. Modify the ruleset YAML file. For example, update severity values or delete rules you do not want to use.

  3. Validate the changes using the governance ruleset validate command. See Validate Governance Ruleset Format Using the API Governance CLI.

  4. Generate the ruleset file as an asset document. See Generate Documentation for a Ruleset File to Upload to Exchange.

  5. Publish your custom ruleset as a new asset using the Exchange UI or the anypoint-cli exchange asset uploadv2 command. See Publish a Custom Governance Ruleset Asset in Exchange.

Create Completely New Custom Rulesets

If you want a custom ruleset that cannot be created by modifying one of the provided rulesets:

  1. First search the MuleSoft Ideas Portal for ideas for new rulesets that have already been submitted.

  2. If you do not find your idea there, consider submitting your idea in the MuleSoft Ideas Portal.

If you are interested in learning more about how rulesets are written, see the AMF Custom Validation section in the AML Open Source project. See the AMF Rulesets tutorial to learn how to author and test new rules.

Similarly to custom code and configurations, rulesets are not considered supported MuleSoft products. For assistance with issues with these custom rulesets, post an issue in the AMF Custom Validator Github repository.

Publish a Custom Governance Ruleset Asset in Exchange

You can publish a ruleset to Exchange as you do any other asset:

  • To upload your custom ruleset using the Exchange UI, see Create a Ruleset Asset.

  • To upload your custom ruleset using the CLI, use the exchange asset uploadv2 command. In the following example, the zipped YAML ruleset file is specified in --files.ruleset.zip ~/temp/ruleset.yaml.zip.

If you want to generate and include the documentation for the ruleset as part of the published asset, see Generate Documentation for a Ruleset File to Upload to Exchange before you run the upload command. In the following example, the zipped ruleset documentation file is specified in the second file option, --files.docs.zip ~/temp/ruleset.doc.zip.

To validate your ruleset locally before you upload it, see Validate Governance Ruleset Format Using the API Governance CLI.

Example command:

anypoint-cli exchange asset uploadv2 --name "cli ruleset asset" --description "cli ruleset asset description" --properties.mainFile ruleset.yaml --files.ruleset.zip ~/temp/ruleset.yaml cli-ruleset-asset/1.0.0 --files.docs.zip ~/temp/ruleset.doc.zip

Generate Documentation for a Ruleset File to Upload to Exchange

Use the following command to generate a documentation ZIP file for a ruleset YAML file. The resulting documentation ZIP file can then be used in an Exchange asset upload using the --files.docs.zip option.

governance document

> governance document [options] <ruleset> <doc-file>

This command creates the documentation for the API Governance ruleset definition ZIP file specified in ruleset. It puts the documentation in the doc-file ZIP file for you to upload and publish to Exchange.

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance document ~/temp/ruleset.yaml ~/temp/ruleset.doc.zip

Example output:

 validation name [ 'scalar-parameters' ]
 Saving to /Users/janedoe/temp/prof-1.doc.zip

Validate Governance Ruleset Format Using the API Governance CLI

To validate the format of your governance ruleset as you develop it, use the following command:

governance ruleset validate

> governance ruleset validate [options] <governance-ruleset>

This command validates the ruleset definitions passed using the governance-ruleset parameter. You can pass one of the following as the governance-ruleset parameter:

  • A ruleset definition YAML file

  • A ZIP file that contains an API project with an exchange.json file that specifies the ruleset as the main file

  • A folder that contains an API project with an exchange.json file that specifies the ruleset as the main file

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example commands:

anypoint-cli governance ruleset validate ~/temp/myruleset.yaml

anypoint-cli governance ruleset validate ~/temp/myruleset.zip

anypoint-cli governance ruleset validate ~/temp/myrulesetfolder

Example output for a valid ruleset:

 Ruleset conforms with Dialect

Example output for a nonvalid ruleset:

Ruleset does not conform with Dialect
ModelId: file:///Users/janedoe/temp/prof-1-bad.yaml
Profile: Validation Profile 1.0
Conforms: false
Number of results: 1

Level: Violation

- Constraint: http://a.ml/amf/default_document#/declarations/profileNode_profile_required_validation
  Message: Property 'profile' is mandatory
  Severity: Violation
  Target: file:///Users/janedoe/temp/prof-1-bad.yaml#/encodes
  Property: http://schema.org/name
  Range: [(3,0)-(11,19)]
  Location: file:///Users/janedoe/temp/prof-1-bad.yaml

Scaffold Rulesets from Data Schemas

To scaffold rulesets from data schemas, use the following command sequence:

Inspect API Definitions for API Type

Use the following command to inspect API Definitions for API type. This helps you determine which data schema to use.

governance api inspect

> governance api inspect [options] <api-definition>

This command inspects the API definition passed in api-definition and lists all its schemas, such as headers, requests, and response payloads. You can use this schema information in the governance ruleset init command. See governance ruleset init.

This command accepts only the default options: --help, -f/--fields and -o/--output.

Example command:

anypoint-cli governance api inspect my-healthcare-api.yaml

Example schema

types:
  patientmultipleBirthBoolean:
    properties:
      multipleBirthBoolean:
        description: Whether patient is part of a multiple birth
        type: boolean
  patientmultipleBirthInteger:
    properties:
      multipleBirthInteger:
        description: Whether patient is part of a multiple birth
        type: integer

        .
        .
        .

  PatientEntry:
    type: FHIR_commons.Entry
    properties:
      resource: Patient

  PatientBundle:
    type: FHIR_commons.Bundle
    properties:
      entry?: PatientEntry[]

Example output:

  'patientmultipleBirthBoolean',
  'PatientBundle',
  'patientmultipleBirthInteger',
  'PatientEntry'

Initialize Rulesets from Data Schemas

Use the following command to initialize rulesets from data schemas.

governance ruleset init

> governance ruleset init [options] <schema>

This command initializes a ruleset based on the data schema passed in the schema parameter.

Besides the default options --help, -f/--fields and -o/--output options, this command also takes:

Option Description

--types <types>

The types option gives the target types to export as rules. You can use the governance api inspect command to identify the types to specify in this option. See governance api inspect.

--name <name>

The name option is the name of the ruleset. Defaults to GeneratedRuleset.

Example command:

anypoint-cli governance ruleset init --types patientmultipleBirthBoolean,patientBundle,patientmultipleBirthInteger --name=my-ruleset mydataschema

Was this article helpful?

💙 Thanks for your feedback!