+
+

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.

Submit your ideas for rulesets you would like MuleSoft to provide in future releases on the MuleSoft Ideas Portal.

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:

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

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 Github repository for the AMF Custom Validator.

If you are interested in learning more about how rulesets are written, see the AMF Custom Validation section in the AML Open Source project.

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> <file>

This command creates the documentation for an API Governance ruleset definition .zip file that you want to upload and publish to Exchange.

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

This command accepts the following options:

  • Default options: --help, -f/--fields and -o/--output

  • Other options: --files.docs.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 <governance-ruleset>

This command validates the governance ruleset definition’s format.

<governance-ruleset>

Specify the file location and file name of the ruleset definition .zip file that you want to validate.

Example command:

anypoint-cli governance ruleset validate ~/temp/prof-1-bad.yaml

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

Was this article helpful?

💙 Thanks for your feedback!

Submit your feedback!
Share your thoughts to help us build the best documentation experience for you!
Take our latest survey!