

Policy

Policy

Policies are structured YAML files that provide the human readable context for an audit. Drutiny scans for these files and looks for files ending in .policy.yml. The convention is to store these files in a directory called Policy.

View list of policies managed under the Drutiny project.

Policy structure

title (required)

The human readable name and title of a given policy. The title should accurately indicate what the audit is for in as few words as possible. An expanded context can be given in the description field.

title: Shield module is enabled

name (required)

The machine readable name of the policy. This is used to call the policy in policy:audit and to list in profiles. The naming convention is to use camel case and to delineate namespaces with colons.

name: Drupal:ShieldEnabled

class (required)

The audit class used to assess the policy. The entire namespace should be given including a leading forward slash. If this class does not exist, Drutiny will fail when attempting to use this policy.

class: \Drutiny\Audit\Drupal\ModuleEnabled

type (default: audit)

Policies can be of two types: audit (the default) or data.

Audit types evaluate the target for a pass/fail result. Data types simply collect and display the data.

This property helps define how to best display the policy in an HTML report.

type: data

description (required)

A human readable description of the policy. The description should be informative enough for a human to read the description and be able to interpret the audit findings.

This field is interpreted as Markdown

description: |
  Using the pipe (|) symbol in yaml,
  I'm able to provide my description
  across multiple lines.

success (required)

The success message to provide if the audit returns successfully. This field supports mustache templates to display parameters given at runtime or tokens generated by the audit.

This field is interpreted as Markdown

success: The module {{module_name}} is enabled.

failure (required)

If the audit fails or is unable to complete due to an error, this message will be displayed. This field supports mustache templates to display parameters given at runtime or generated by the audit.

This field is interpreted as Markdown

failure: {{module_name}} is not enabled.

remediation (required)

This text is displayed to advise the reader how to go about remediating the policy. This field supports mustache templates to display parameters given at runtime or tokens generated by the audit.

This field is interpreted as Markdown

remediation: |
  Please enable the {{module_name}} module using drush
  `drush en {{module_name}} -y`

parameters

Parameters allow a policy to define values for variables used by the Audit. They are also used in policy:info to inform on the parameters available to customize. A parameter consists of three key value pairs:

• default (required): The actual value to pass through to the audit.
• type: The data type of the parameter. Used to advise profile builders on how to use the parameter.
• description: A description of what the parameter is used for. Used to advise profile builders.

parameters:
  module_name:
    default: shield
    type: string
    description: The name of the module to check is enabled.

tags

The tags key is simply a mechanism to allow policies to be grouped together. For example "Drupal 7" or "Performance".

tags:
  - Drupal 7
  - Performance

depends

The depends directive allows policies to only apply if one or more conditions are meet such as an enabled module or the value of a target environmental variable (like OS).

Drutiny uses Symfony Expression Language to evaluate the outcome of each dependency. Drutiny extends this language to provide additional functions available in the evaluation process. See more docs Expression Language.

depends:
  - expression: Policy('fs:largeFiles') == 'success'
    on_fail: 'error'
  - expression: drupal_module_enabled('syslog') && semver_gt(target('php_version'), '5.5')

Each depends item must have an associated expression key with the expression to evaluate. Optionally, an on_fail property can be added to indicate the failure behaviour:

On fail

Value	Behaviour
omit	Omit policy from report
fail	Fail policy in report
error	Report policy as error
report_only	Report as not applicable

severity

Not all policies are of equal importance. Severity allows you to specify how critical a failure or warning is. Possible values in order of importance:

• none (only option for data type policies)
• low
• medium (default)
• high
• critical

severity: 'high'

chart

Chart declarations allow you to provide metadata about how to build a chart for display in the html format. This then produces a chart token that can be used in the success, failure, warning or remediation fields to render a chart in place.

chart:
  requests:
    type: doughnut
    labels: tr td:first-child
    hide-table: false
    title: Request Distribution by Domain
    series:
      - tr td:nth-child(4)

See charts documentation for more information.

Using Tokens in message renders.

Tokens are variables you can use in the render of policy messaging. This includes success, failure, warning and description fields defined in a policy.

Available Tokens

Use the policy:info command to identify which tokens are available in a policy for use in the render.

bash $ drutiny policy:info fs:largeFiles

You can see in the above example output, that fs:largeFiles contains three tokens: _max_size, issues and plural. These tokens are available to use as template variables when writting messaging for a policy:

yaml failure: | Large public file{{plural}} found over {{max_size}} {{#issues}} - `{{ . }}` {{/issues}}

These variables are rendered using mustache templates. The messages are also parsed by a markdown parser when rendering out to HTML.