Rule Sets

Overview

A rule set is a named set of rules, represented as a JSON object within a Policy. A rule set is made up of rules that define a specific check to perform and a resulting action.

A Rule Set is made up of:

  • ID: a unique id for the rule set within the policy
  • Name: a human readable name to give the policy (may contain spaces etc)
  • A list of rules to define what to evaluate and the action to recommend on any matches for the rule

A simple example of a rule_set JSON object (found within a larger policy object):

{
  "name": "DefaultPolicy",
  "version": "2",
  "comment": "Policy for basic checks",
  "id": "policy1",
  "rules": [
      {
        "action": "STOP",
        "gate": "vulnerabilities",
        "id": "rule1",
        "params": [
          { "name": "package_type", "value": "all" },
          { "name": "severity_comparison", "value": ">=" },
          { "name": "severity", "value": "medium" }
        ],
        "trigger": "package",
        "recommendation": "Upgrade the package",
      }
  ]
}

The above example defines a stop action to be produced for all package vulnerabilities found in an image that are severity medium or higher.

Policy evaluation is the execution of all defined triggers in the rule set against the image analysis result and feed data and results in a set of output trigger matches, each of which contains the defined action from the rule definition. The final recommendation value for the policy evaluation is called the final action, and is computed from the set of output matches: stop, go, or warn.

alt text

Policy Rules

Rules define the behavior of the policy at evaluation time. Each rule defines:

  • Gate - example: dockerfile
  • Trigger - example: exposed_ports
  • Parameters - parameters specific to the gate/trigger to customize its match behavior
  • Action - the action to emit if a trigger evaluation finds a match. One of stop, go, warn. The only semantics of these values are in the aggregation behavior for the policy result.

Gates

A Gate is a logical grouping of trigger definitions and provides a broader context for the execution of triggers against image analysis data. You can think of gates as the “things to be checked”, while the triggers provide the “which check to run” context. Gates do not have parameters themselves, but namespace the set of triggers to ensure there are no name conflicts.

Examples of gates:

  • vulnerabilities
  • packages
  • npms
  • files
  • …

For a complete listing see: Anchore Policy Checks

Triggers

Triggers define a specific condition to check within the context of a gate, optionally with one or more input parameters. A trigger is logically a piece of code that executes with the image analysis content and feed data as inputs and performs a specific check. A trigger emits matches for each instance of the condition for which it checks in the image. Thus, a single gate/trigger policy rule may result in many matches in final policy result, often with different match specifics (e.g. package names, cves, or filenames…).

Trigger parameters are passed as name, value pairs in the rule JSON:

{
  "action": "WARN",
  "parameters": [
    {  "name": "param1", "value": "value1" },
    {  "name": "param2", "value": "value2" },
    {  "name": "paramN", "value": "valueN" }
  ],
  "gate": "vulnerabilities",
  "trigger": "packages",
}

For a complete listing of gates, triggers, and the parameters, see: Anchore Policy Gates

Policy Evaluation

  • All rules in a selected rule_set are evaluated, no short-circuits
  • Rules who’s triggers and parameters find a match in the image analysis data, will “fire” resulting in a record of the match and parameters. A trigger may fire many times during an evaluation (e.g. many cves found).
  • Each firing of a trigger generates a trigger_id for that match
  • Rules may be executed in any order, and are executed in isolation (e.g. conflicting rules are allowed, it’s up to the user to ensure that policies make sense)

A policy evaluation will always contain information about the policy and image that was evaluated as well as the Final Action. The evaluation can optionally include additional detail about the specific findings from each rule in the evaluated rule_set as well as suggested remediation steps.

Policy Evaluation Findings

When extra detail is requested as part of the policy evaluation, the following data is provided for each finding produced by the rules in the evaluated rule_set.

  • trigger_id - An ID for the specific rule match that can be used to allowlist a finding
  • gate - The name of the gate that generated this finding
  • trigger - The name of the trigger within the Gate that generated this finding
  • message - A human readable description of the finding
  • action - One of go, warn, stop based on the action defined in the rule that generated this finding
  • policy_id - The ID for the rule_set that this rule is a part of
  • recommendation - An optional recommendation provided as part of the rule that generated this finding
  • rule_id - The ID of the rule that generated this finding
  • allowlisted - Indicates if this match was present in the applied allowlist
  • allowlist_match - Only provided if allowlisted is true, contains a JSON object with details about a allowlist match (allowlist id, name and allowlist rule id)
  • inherited_from_base - An optional field that indicates if this policy finding was present in a provided comparison image

Excerpt from a policy evaluation, showing just the policy evaluation output:

...json
"findings": [
  {
    "trigger_id": "CVE-2008-3134+imagemagick-6.q16",
    "gate": "package",
    "trigger": "vulnerabilities",
    "message": "MEDIUM Vulnerability found in os package type (dpkg) - imagemagick-6.q16 (CVE-2008-3134 - https://security-tracker.debian.org/tracker/CVE-2008-3134)",
    "action": "go",
    "policy_id": "48e6f7d6-1765-11e8-b5f9-8b6f228548b6",
    "recommendation": "Upgrade the package",
    "rule_id": "rule1",
    "allowlisted": false,
    "allowlist_match": null,
    "inherited_from_base": false
  },
  {
    "trigger_id": "CVE-2008-3134+libmagickwand-6.q16-2",
    "gate": "package",
    "trigger": "vulnerabilities",
    "message": "MEDIUM Vulnerability found in os package type (dpkg) - libmagickwand-6.q16-2 (CVE-2008-3134 - https://security-tracker.debian.org/tracker/CVE-2008-3134)",
    "action": "go",
    "policy_id": "48e6f7d6-1765-11e8-b5f9-8b6f228548b6",
    "recommendation": "Upgrade the package",
    "rule_id": "rule1",
    "allowlisted": false,
    "allowlist_match": null,
    "inherited_from_base": false
  }
]

Final Action

The final action of a policy evaluation is the policy’s recommendation based on the aggregation of all trigger evaluations defined in the policy and the resulting matches emitted.

The final action of a policy evaluation will be:

  • stop - if there are any triggers that match with this action, the policy evaluation will result in an overall stop.
  • warn - if there are any triggers that match with this action, and no triggers that match with stop, then the policy evaluation will result in warn.
  • go - if there are no triggers that match with either stop or warn, then the policy evaluation is result is a go. go actions have no impact on the evaluation result, but are useful for recording the results of specific checks on an image in the audit trail of policy evaluations over time

The policy findings are one part of the broader policy evaluation which includes things like image allowlists and denylists and makes a final policy evaluation status determination based on the combination of several component executions. See policies for more information on that process.

Next Steps

Read more about the Mappings component of a policy.

Last modified September 16, 2024