Customizable HTML Formatter

This is a customizable HTML Markup Formatter used to sanitize the HTML content.

This project is based upon OWASP Java HTML Sanitizer.

1. Navigate to Configure Global Security page

   (Jenkins Home page -> Manage Jenkins -> Configure Global Security)

2. Navigate to Markup Formatter parameter and select Customizable HTML Formatter from the dropdown menu

• Change the Policy parameter under Customizable HTML Formatter Plugin in the Configure System page

  (Jenkins Home page -> Manage Jenkins -> Configure System)

• The format of the policy is simple and you can get started by directly seeing the default definition shown in Default policies section.

• The resultant policy is defined as a combination of different policies represented as JSON array. Thus, each element in the JSON array represents one policy.

  [
    {
      "policy 1": "definition"
    },
    {
      "policy 2": "definition"
    }
  ]

  Note: The policy defined does not depend on indentation as long as it is a valid JSON. However, the parameters and values are case-sensitive unless explicitly mentioned.

• There are different types of policy you can define as shown below.

  1. Default Policy

     {
       "type": "default",
       "name": "<DEFAULT_NUMBER>"
     }

     Define the value of DEFAULT_NUMBER from the available default policies packaged with the plugin as defined here.

  2. Inbuilt Policy

     Inbuilt policy is defined in the Sanitizers class available at [GitHub, DOCS].

     {
      "type": "inbuilt",
      "name": "<INBUILT_POLICY_NAME>"
     }

     INBUILT_POLICY_NAME can be a comma seperated list such as "blocks, links" or as individual "links"

     Supported values are: BLOCKS, LINKS, FORMATTING, IMAGES, STYLES, TABLES

     Note: Value of INBUILT_POLICY_NAME is not case-sensitive and does not depend on extra spaces.(" blOCks, Links" is same as "blocks, links")

  3. New Policy

     {
      "type": "new",
      "name": "<TAG_NAME> <OPTIONAL: Only required if using methods allowAttributes and disallowAttributes>",
      "allow": {
        "<TAG_LIST1 Comma-seperated>": "<ATTRIBUTE_LIST Comma-seperated>",
        "<TAG_LIST2 Comma-seperated>": "<ATTRIBUTE_LIST Comma-seperated>"
      },
      "methods": {
        "<METHOD1>": "<Comma-seperated parameters>",
        "<METHOD2>": "<Comma-seperated parameters>"
      }
     }

     In most cases, only using allow will do the job. methods can be used for more advanced configuration. The list of methods are part of HtmlPolicyBuilder available at [GitHub, DOCS]

     Note: Supports method with String parameters or no parametes and return type as being HtmlPolicyBuilder and AttributeBuilder as defined in the docs.

The value or name of default policies are numbers. Currently, there are two default policies with this plugin.

1. Policy 1

   [
       {
           "type": "inbuilt",
           "name": "blocks, formatting, blocks, tables, images"
       },
       {
       	"type": "new",
       	"allow": {
               "dl, dt, dd, hr, pre": "",
               "font": "size, color",
               "a": "href, target"
       	},
           "methods": {
               "allowStandardUrlProtocols": ""
           }
       }
   ]

   This is same as

   [
     {
       "type": "default",
       "name": "1"
     }
   ]

2. Policy 2

   [
      {
    	"type": "inbuilt",
    	"name": "blocks, formatting, blocks, links, tables, images"
      },
      {
    	"type": "new",
    	"allow": {
       	    "dl, dt, dd, hr, pre": ""
       }
      }     
   ]