Policies are built with checks, which provide a definition for a single CI attribute and its expected value.

Overview

Policies consist of a number of checks to confirm if a configuration item is passing or failing a particular condition. These checks have a unique type to test a CI attribute in different ways. Below is a list of the check types and how they work.

Checks

Exact Match

Verify that an attribute string exactly matches a given string. For example:

Example PASS
Collected Value C:\Program Files\UpGuard\UpGuard.exe
Check Value C:\Program Files\UpGuard\UpGuard.exe
Example FAIL
Collected Value C:\Program Files\UpGuard\UpGuard.exe
Check Value C:\Program Files (x86)\UpGuard\UpGuard.exe

You can also use this for exact matches of version numbers. For example:

Example PASS
Collected Value 10.1.0
Check Value 10.1.0
Example FAIL
Collected Value 10.1.0
Check Value 10.1.0-ubuntu

Includes

Verify that one string exists in an attribute. If you are checking against a list value, you may provide a comma-separated list of values.

Example PASS
Collected Value enable_secure_cookied=true; enable_httponly_cookied=true
Check Value enable_secure_cookied=true
Example FAIL
Collected Value enable_httponly_cookied=true
Check Value enable_secure_cookied=true

For example, assume a configuration item for the members of a local Windows group.

Example PASS
Collected Value ["Administrator","Guest","User1"]
Check Value Administrator, Guest
Example FAIL
Collected Value ["Administrator","Guest","User1"]
Check Value Administrator, User2

Excludes

Verify that one string does not exist in an attribute. If you are checking against a list value, you may provide a comma-separated list of values.

Example PASS
Collected Value secret_git_password=<dev to fill in>
Check Value secret_git_password=UpGu4rd
Example FAIL
Collected Value secret_git_password=UpGu4rd
Check Value secret_git_password=UpGu4rd

For example, assume a configuration item for the members of a local Windows group.

Example PASS
Collected Value ["Administrator","Guest","User1"]
Check Value User2

This will fail:

Example FAIL
Collected Value ["Administrator","Guest","User1"]
Check Value Administrator, User1

XPath

The XPath check allows you to find elements in an XML file (such as a web.config file). The check will verify that a path exists, but does not actually check the value of the element.

For the examples below, assume the following attribute value:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
  </appSettings>
  <system.web>
    <authentication mode="None" />
    <compilation targetFramework="4.5.1" />
    <httpRuntime targetFramework="4.5.1" />
  </system.web>
  <system.webServer>
    <modules>
      <remove name="FormsAuthenticationModule" />
    </modules>
  </system.webServer>
</configuration>

This will pass:

Example PASS
Check Value configuration/system.web/compilation/@targetFramework

This will fail:

Example FAIL
Check Value configuration/system.web/compilation/@debug

Greater than, Less than

When running a policy check against a number, you can specify if the attribute value should be greater than or less than the provided value.

Example PASS
Collected Value 100
Check Value < 1000
Example FAIL
Collected Value 1200
Check Value < 1000

Regular Expression

Search for text within an attribute value using a regular expression.

Example PASS
Collected Value C:\Program Files\UpGuard\.upguard\upguard.yml
Check Value ^.*yml$
Example FAIL
Collected Value C:\Program Files\UpGuard\.upguard\upguard.yml
Check Value ^.*txt$

Regular Expression (Excludes)

Passes if the given regular expression pattern does not match any content.

Example PASS
Collected Value C:\Program Files\UpGuard\.upguard\upguard.yml
Check Value ^.*txt$
Example FAIL
Collected Value C:\Program Files\UpGuard\.upguard\upguard.yml
Check Value ^.*yml$

Time Comparison

When running a policy check against a date or time, you can specify if the attribute value should be less than or greater than (before or after) the provided date or time.

For the following examples, assume the current date is 2017-12-05 (December 5th 2017) and we want to make sure the attribute value does not fall within the next 30 days (for certificate expiration).

Example PASS
Collected Value 2020-01-01
Check Value < in 30 days
Example FAIL
Collected Value 2018-01-01
Check Value < in 30 days

For more examples of the natural language dates you can use for this check, see the documentation for the Chronic Project.

Version Comparison

When running a policy check against a version (such as v1.2.3, 4.5.6 or 7.8), you can specify if the attribute value should be greater than or less than the provided version.

Example PASS
Collected Value 10.1.2
Check Value < 11.0
Example FAIL
Collected Value 10.1.2
Check Value > 11.0

Whitelist/Blacklist

Check that a given value either matches any entry in a specified whitelist and does not match an entry given in a specified blacklist. As part of this check you can specify either only whitelisted items, only blacklisted items, or a combination of both.

The following two examples show a pass and fail condition for purely whitelisted elements:

Example PASS
Collected Value alan
Check Values [+ alan] [+ mike]
Example FAIL
Collected Value greg
Check Values [+ alan] [+ mike]

The following two examples show a pass and fail condition for purely lacklsited elements:

Example PASS
Collected Value homer
Check Values [- alan] [- mike]
Example FAIL
Collected Value virus.exe
Check Values [- virus.exe] [- malware.exe

What if the value is missing completely?

Many of these checks apply a particular condition to a collected value. There are cases, however, where a particular value isn’t collected as part of a node scan. By default, if a value isn’t collected the engine will fail the check as it doesn’t have enough information to perform a proper pass/fail check.

If you are happy for a particular attribute check to pass if the value is absent, then you can check the Check should pass if attribute is absent box just under the Type of check selection box.

w400

What Next?

Many checks by default apply to a particular configuration item. For more information on using wildcard paths to match multiple items, please view our guide on Wildcard Policies.