Skip to content

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

Policies can depend on other policies meaning that all policies specified in this field must pass successfully for this policy to pass.

depends:
  - fs:largeFiles
  - Drupal:SyslogEnabled

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

Check Large public files

Description Large static assets should ideally be housed in other services, e.g. Amazon S3 (for files) or Youtube (for videos).

Remediable No

Parameters max_size:integer Report files larger than this value measured in megabytes.

Tokens max_size:integer Report files larger than this value measured in megabytes. issues:array A list of files that reach the max file size. plural:string This variable will contain an 's' if there is more than one issue found.

Location /mnt/drutiny/Policy/fsLargeFiles.policy.yml

```

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.