Examples and Recipes

The following examples are drawn from real benchmark post-processing code in the Xylok Security Suite. Each example is labeled with the benchmark and check ID it was sourced from so you can look up the full context if needed. (Examples may vary from the current scripts over time, but are still relevant.)

Windows Registry Check

A very common pattern on Windows benchmarks is to query a registry value with reg query and then use a regular expression to verify the expected value exists and is set correctly. Early return guard clauses keep each branch independent and flat, handling the “key not found,” “key found and correct,” and “key found but wrong” cases without nested if / elif / else.

Source: microsoft_windows_11_stig / WN11-CC-000110 — “Printing over HTTP must be prevented.”

import re

valuenotfound = "The system was unable to find the specified registry key or value."
goodvalue = r"DisableHTTPPrinting\s+REG_DWORD\s+0x1"

if re.search(valuenotfound, ctx.raw, re.IGNORECASE):
    print("The registry value does not exist.")
    ctx.recommend_noncompliant("The system is not configured to prevent printing over HTTP.")
    return

if re.search(goodvalue, ctx.raw, re.IGNORECASE):
    print(ctx.raw)
    ctx.recommend_compliant("The system is configured to prevent printing over HTTP.")
    return

print(ctx.raw)
ctx.recommend_noncompliant("The system is not configured to prevent printing over HTTP.")

IIS MIME Type Check with Utility Function

This example demonstrates several features in one short script: using a utility module (utils.windows.powershell.ps_list_cleanup()) to parse PowerShell list output, an early return guard clause for a not-applicable condition, and iterating over cleaned results to build a human-readable list of non-compliant items.

Source: iis_10-0_server_stig / IIST-SV-000124 — “The IIS 10.0 web server must have MIME types that invoke OS shell programs disabled.”

from utils.windows.powershell import ps_list_cleanup

if "WSUS installed" in ctx.raw:
    ctx.recommend_na("WSUS installed, which makes this check Not Applicable.")
    return

# Split the results with a little cleanup
extension_list = ps_list_cleanup(ctx.raw, "\n\n")

print(ctx.raw)

if not extension_list:
    ctx.recommend_compliant("All MIME Types that invoke OS shell programs have been disabled.")
    return

nc_extensions = []
for extension_result in extension_list:
    extension_name = extension_result.split(" : ", 1)[1].strip()
    nc_extensions.append(extension_name)

ctx.recommend_noncompliant(
    f"The following MIME Types that invoke OS shell programs have not been disabled: {', '.join(nc_extensions)}"
)

Cisco IOS Configuration Parsing with NetworkParse

The networkparse module makes it easy to parse structured network device configurations. In this case, it’s used to filter the running configuration for AAA-related lines and local user definitions, then prints them in a tree display for the reviewer. This examples doesn’t provide any particular recommendation and will appear as unreviewed to the user, but with just the filtered lines displayed.

Source: cisco_ios-xr_router_ndm_stig / CISC-ND-000490 — “The Cisco router must be configured with only one local account to be used as the account of last resort.”

 # Here we directly import networkparse, but it's also available at `utils.networkparse`
from networkparse import parse

config = parse.ConfigIOS(ctx.raw)

print("🔎 Finding all AAA related configuration lines:")
print(config.filter(".*aaa.*", depth=None).tree_display())
print()

print("🔎 Finding all local users:")
for user in config.filter("username.*"):
    print(user.tree_display())

Complex Example and Cleanup

This example demonstrates defining a function within the script for local complex logic that isn’t shared with other scripts, as recommended in the PP Core Concepts Best Practices. The active_lines(raw) helper normalizes grep output (stripping file-path prefixes, skipping comments and blank lines) and is called in multiple places.

However, the original script also has some deep nesting, which makes the logic harder to follow. After the original code, we show a refined version which uses early returns to simplify some of the logic.

Source: can_ubuntu_22-04_lts_stig / UBTU-22-653020 — “Ubuntu 22.04 LTS audit event multiplexor must be configured to offload audit logs onto a different system from the system being audited.”

Original: Linux Audit Offload Check

compliance = True
complianceComment = ""

### STIG VALUES ###
PKG_SENTINEL = "Not installed"
REQUIRED_ACTIVE = "yes"
### STIG VALUES ###

cmdOutput = ctx.ics_split()[1:]  # [0]=dpkg, [1]=grep active, [2]=grep remote_server

print("Checking that audit offloading via audispd is configured:")

# Helper: normalize grep output lines, strip file prefixes and comments
def active_lines(raw):
    if raw is None:
        return []
    lines = []
    for ln in raw.splitlines():
        ln = ln.rstrip()
        if not ln.strip():
            continue
        # strip "/path:content" prefix from grep -R style
        if ":" in ln and ln.split(":",1)[0].startswith("/"):
            ln = ln.split(":",1)[1].lstrip()
        if ln.lstrip().startswith("#"):
            continue
        lines.append(ln)
    return lines

# 1) Package installed?
if not cmdOutput or len(cmdOutput) < 3:
    compliance = False
    print("\N{cross mark} Missing outputs for package/active/remote_server checks.")
    complianceComment = ("Did not receive all three outputs. Ensure 'audispd-plugins' is installed, "
                         "'active = yes' in /etc/audit/plugins.d/au-remote.conf, and "
                         "'remote_server = <IP>' in /etc/audit/audisp-remote.conf.")
else:
    pkg_raw = (cmdOutput[0] or "")
    if PKG_SENTINEL in pkg_raw:
        compliance = False
        print("\N{cross mark} 'audispd-plugins' package is not installed.")
        complianceComment = ("'audispd-plugins' missing. Install it with "
                             "'apt-get install audispd-plugins'.")
    else:
        # look for 'ii  audispd-plugins'
        import re
        pkg_ok = False
        for ln in pkg_raw.splitlines():
            if not ln.strip(): continue
            # strip possible "file:" prefix
            if ":" in ln and ln.split(":",1)[0].startswith("/"):
                ln = ln.split(":",1)[1].lstrip()
            m = re.match(r'^\s*([a-z]{2})\s+(\S+)', ln.lower())
            if m and m.group(1) == "ii" and (m.group(2) == "audispd-plugins" or m.group(2).startswith("audispd-plugins:")):
                pkg_ok = True
                break
        if pkg_ok:
            print("\N{left-pointing magnifying glass} audispd-plugins package is installed.")
        else:
            compliance = False
            print("\N{cross mark} audispd-plugins not in installed state.")
            complianceComment = ("'audispd-plugins' is not fully installed (dpkg state not 'ii'). "
                                 "Install with 'apt-get install audispd-plugins'.")

    # 2) au-remote active?
    if compliance:
        active_raw = cmdOutput[1] or ""
        act_lines = active_lines(active_raw)
        if not act_lines:
            compliance = False
            print("\N{cross mark} No active 'active =' line found in au-remote.conf.")
            complianceComment = ("Missing or commented 'active = yes' in "
                                 "/etc/audit/plugins.d/au-remote.conf.")
        else:
            # evaluate last effective assignment
            eff = None
            for ln in act_lines:
                if ln.lower().startswith("active"):
                    parts = [p.strip() for p in ln.split("=",1)]
                    if len(parts) == 2:
                        eff = parts[1].lower()
            if eff == REQUIRED_ACTIVE:
                print("\N{left-pointing magnifying glass} au-remote plugin is active (active = yes).")
            else:
                compliance = False
                print("\N{cross mark} 'active' not set to 'yes' in au-remote.conf.")
                complianceComment = ("'/etc/audit/plugins.d/au-remote.conf' must contain "
                                     "'active = yes' (uncommented).")

    # 3) remote_server valid and not loopback/invalid
    if compliance:
        rs_raw = cmdOutput[2] or ""
        rs_lines = active_lines(rs_raw)
        if not rs_lines:
            compliance = False
            print("\N{cross mark} No active 'remote_server =' line found.")
            complianceComment = ("Missing or commented 'remote_server = <ip>' in "
                                 "/etc/audit/audisp-remote.conf.")
        else:
            remote_val = None
            for ln in rs_lines:
                if ln.lower().startswith("remote_server"):
                    parts = [p.strip() for p in ln.split("=",1)]
                    if len(parts) == 2:
                        remote_val = parts[1]
            if not remote_val:
                compliance = False
                print("\N{cross mark} Unable to parse remote_server value.")
                complianceComment = ("Invalid 'remote_server' assignment in "
                                     "/etc/audit/audisp-remote.conf.")
            else:
                # Validate IPv4 dotted-quad; reject loopback/0.0.0.0; (private ranges OK if a separate host)
                ipv4_ok = re.match(r'^\d{1,3}(\.\d{1,3}){3}$', remote_val) is not None
                if not ipv4_ok:
                    compliance = False
                    print("\N{cross mark} remote_server is not an IPv4 address.")
                    complianceComment = ("'remote_server' must be a valid IPv4 address "
                                         "(e.g., 192.0.2.10), not: '{}'.".format(remote_val))
                else:
                    octets = [int(x) for x in remote_val.split(".")]
                    valid_octets = all(0 <= o <= 255 for o in octets)
                    loopback = (octets[0] == 127)
                    unspecified = (remote_val == "0.0.0.0")
                    if not valid_octets or loopback or unspecified:
                        compliance = False
                        print("\N{cross mark} remote_server is invalid or loopback/unspecified.")
                        complianceComment = ("'remote_server' must be a valid non-loopback IPv4 address; "
                                             f"found '{remote_val}'.")
                    else:
                        print("\N{white heavy check mark} Remote offload configured (active=yes, remote_server set).")
                        complianceComment = (f"audisp remote offload enabled; remote_server = {remote_val}.")

# 6) Final Recommendation
if compliance:
    recommend_compliant(complianceComment.strip())
else:
    recommend_noncompliant(complianceComment.strip())

Refactored

The version above works, but violates several PP Core Concepts Best Practices. The refactored version below addresses those:

import re

### STIG VALUES ###
PKG_SENTINEL = "Not installed"
REQUIRED_ACTIVE = "yes"
### STIG VALUES ###

# Helper: normalize grep output lines, strip file prefixes and comments
def active_lines(raw):
    if raw is None:
        return []
    lines = []
    for ln in raw.splitlines():
        ln = ln.rstrip()
        if not ln.strip():
            continue
        # strip "/path:content" prefix from grep -R style
        if ":" in ln and ln.split(":", 1)[0].startswith("/"):
            ln = ln.split(":", 1)[1].lstrip()
        if ln.lstrip().startswith("#"):
            continue
        lines.append(ln)
    return lines


cmdOutput = ctx.ics_split()[1:]  # [0]=dpkg, [1]=grep active, [2]=grep remote_server

print("Checking that audit offloading via audispd is configured:")

# 1) All three command outputs present?
if not cmdOutput or len(cmdOutput) < 3:
    print("\N{cross mark} Missing outputs for package/active/remote_server checks.")
    ctx.recommend_noncompliant(
        "Did not receive all three outputs. Ensure 'audispd-plugins' is installed, "
        "'active = yes' in /etc/audit/plugins.d/au-remote.conf, and "
        "'remote_server = <IP>' in /etc/audit/audisp-remote.conf."
    )
    return

# 2) Package installed?
pkg_raw = cmdOutput[0] or ""

if PKG_SENTINEL in pkg_raw:
    print("\N{cross mark} 'audispd-plugins' package is not installed.")
    ctx.recommend_noncompliant(
        "'audispd-plugins' missing. Install it with 'apt-get install audispd-plugins'."
    )
    return

pkg_ok = False
for ln in pkg_raw.splitlines():
    if not ln.strip():
        continue
    if ":" in ln and ln.split(":", 1)[0].startswith("/"):
        ln = ln.split(":", 1)[1].lstrip()
    m = re.match(r'^\s*([a-z]{2})\s+(\S+)', ln.lower())
    if m and m.group(1) == "ii" and (
        m.group(2) == "audispd-plugins" or m.group(2).startswith("audispd-plugins:")
    ):
        pkg_ok = True
        break

if not pkg_ok:
    print("\N{cross mark} audispd-plugins not in installed state.")
    ctx.recommend_noncompliant(
        "'audispd-plugins' is not fully installed (dpkg state not 'ii'). "
        "Install with 'apt-get install audispd-plugins'."
    )
    return

print("\N{left-pointing magnifying glass} audispd-plugins package is installed.")

# 3) au-remote active?
active_raw = cmdOutput[1] or ""
act_lines = active_lines(active_raw)

if not act_lines:
    print("\N{cross mark} No active 'active =' line found in au-remote.conf.")
    ctx.recommend_noncompliant(
        "Missing or commented 'active = yes' in /etc/audit/plugins.d/au-remote.conf."
    )
    return

eff = None
for ln in act_lines:
    if ln.lower().startswith("active"):
        parts = [p.strip() for p in ln.split("=", 1)]
        if len(parts) == 2:
            eff = parts[1].lower()

if eff != REQUIRED_ACTIVE:
    print("\N{cross mark} 'active' not set to 'yes' in au-remote.conf.")
    ctx.recommend_noncompliant(
        "'/etc/audit/plugins.d/au-remote.conf' must contain "
        "'active = yes' (uncommented)."
    )
    return

print("\N{left-pointing magnifying glass} au-remote plugin is active (active = yes).")

# 4) remote_server valid and not loopback/invalid
rs_raw = cmdOutput[2] or ""
rs_lines = active_lines(rs_raw)

if not rs_lines:
    print("\N{cross mark} No active 'remote_server =' line found.")
    ctx.recommend_noncompliant(
        "Missing or commented 'remote_server = <ip>' in /etc/audit/audisp-remote.conf."
    )
    return

remote_val = None
for ln in rs_lines:
    if ln.lower().startswith("remote_server"):
        parts = [p.strip() for p in ln.split("=", 1)]
        if len(parts) == 2:
            remote_val = parts[1]

if not remote_val:
    print("\N{cross mark} Unable to parse remote_server value.")
    ctx.recommend_noncompliant(
        "Invalid 'remote_server' assignment in /etc/audit/audisp-remote.conf."
    )
    return

# Validate IPv4 dotted-quad; reject loopback/0.0.0.0
ipv4_ok = re.match(r'^\d{1,3}(\.\d{1,3}){3}$', remote_val) is not None

if not ipv4_ok:
    print("\N{cross mark} remote_server is not an IPv4 address.")
    ctx.recommend_noncompliant(
        f"'remote_server' must be a valid IPv4 address (e.g., 192.0.2.10), not: '{remote_val}'."
    )
    return

octets = [int(x) for x in remote_val.split(".")]
valid_octets = all(0 <= o <= 255 for o in octets)
loopback = octets[0] == 127
unspecified = remote_val == "0.0.0.0"

if not valid_octets or loopback or unspecified:
    print("\N{cross mark} remote_server is invalid or loopback/unspecified.")
    ctx.recommend_noncompliant(
        f"'remote_server' must be a valid non-loopback IPv4 address; found '{remote_val}'."
    )
    return

print("\N{white heavy check mark} Remote offload configured (active=yes, remote_server set).")
ctx.recommend_compliant(f"audisp remote offload enabled; remote_server = {remote_val}.")

Discussion of Changes

The following changes were made to bring the script in line with the PP Core Concepts Best Practices:

1. `ctx.` prefix on all recommendation calls.*

The original code called bare recommend_compliant() and recommend_noncompliant() — deprecated globals that exist for backward compatibility. Every recommendation now uses ctx.recommend_compliant() / ctx.recommend_noncompliant().

2. Early `return` instead of `compliance` flag tracking.

The original code carried a compliance boolean and a complianceComment string through every sub-check, then made a single recommendation at the very end. This required if compliance: guards before each sub-check, creating nesting. The refactored code calls ctx.recommend_noncompliant() and returns immediately on each failure branch. This eliminates both tracking variables entirely and flattens the control flow.

3. Imports moved to the top.

The original placed import re mid-function, inside the package check block. Python allows this, but we generally recommend imports at the top of the module for readability.

4. Helper function moved above the main logic.

The active_lines() helper was defined after the first print() in the original. It now appears right after the STIG-values block, before any main-line code runs. This follows the convention of defining helpers before they are called and keeps the top-to-bottom reading order clean: constants → helpers → main logic.

5. Eliminated deeply nested `if`/`else` blocks.

The original code had up to five levels of nesting (the else of the output-count check → the else of the sentinel check → the if compliance: guard → the else of the empty-lines check → the else of the IPv4 format check). Each sub-check now sits at the same top-level indentation. On failure, the script prints its message, makes its recommendation, and returns — no nesting required. The happy path falls through to the final ctx.recommend_compliant() call.

6. Consistent f-string usage.

The original mixed .format() and f-strings in the remote_server error messages. All string interpolation now uses f-strings.