User-Supplied Check-Level Post-Processing Overrides

By default, Xylok ships with post-processing (PP) scripts embedded in each benchmark. These scripts run automatically when scan data is imported and produce recommendations, simplified output, and system metadata.

Xylok also supports user-supplied check-level PP overrides. Override files placed in a configured directory on the server will replace the built-in PP script for a given check, allowing you to customize post-processing logic without modifying the benchmark itself.

For more details about the actual PP execution context (available globals, return values, and how scripts are invoked), see the PP Concepts documentation.

Default Location

Override files are loaded from the directory configured by the PP_OVERRIDES_DIR setting. The default value is:

/etc/xylok/pp-overrides

This can be changed via the server configuration file or the PP_OVERRIDES_DIR environment variable. Tildes (~) in the path are resolved to the current user’s home directory.

File Path Convention

Override files must follow a specific directory structure. Within the overrides directory, each benchmark gets its own subdirectory named after the benchmark ID (with unsafe filesystem characters replaced by _). Inside that subdirectory, each check gets a Python file named after the check’s Human ID (also with unsafe filesystem characters replaced by _).

The expected path pattern is:

<PP_OVERRIDES_DIR>/<benchmark_id>/<check_human_id>.py

For example, if the benchmark ID is RHEL_9_STIG and the check Human ID is RHEL-09-232010, the override file would be:

/etc/xylok/pp-overrides/RHEL_9_STIG/RHEL-09-232010.py

Characters that are not alphanumeric, underscores, periods, or hyphens are replaced with underscores in both the directory and file names. Double periods (..) are collapsed to a single period.

When viewing a scan item, in the left-hand box (in the check details, where it talks about the check content), the bottom section displays the path on the server where you can create the override file for that particular check. Look for the “User PP Override” text.

Re-Running Post-Processing

After adding or modifying override files, you must re-run post-processing for the changes to take effect on existing scans. This can be done from the scan view:

Navigate to the scan you want to update.
Open Scan Options.
Click the Post-Process button.

This queues a new post-processing job that will pick up any override files on disk. New scans will automatically use the overrides at import time.

When a user-supplied override file exists, it completely replaces the built-in PP script for that check. The original script is not run at all. Make sure your override script includes all the logic you need, including any recommendations or data saving from the original.

Verification via Site

When user post-processing runs, Xylok marks the result as coming from a user PP script. If the scan item is marked, it displays “(PP override in place)” next to the “Post-Processing Recommendations” section of the scan item analysis page, just above the “Use Recommendation” button.

Verification via Logs

When post-processing runs, Xylok logs information about check-level PP override loading. Look for the following log lines to verify that your overrides are being found:

Attempting to load: When Xylok looks for an override file, it logs (at DEBUG level):
```
"Attempting to load check-level PP" benchmark_id=<id> check_id=<human_id> path=<full_path>
```
This line appears for every check that has a Human ID, regardless of whether an override file exists.
Successfully loaded: If the override file is found and read, Xylok logs (at INFO level):
```
"Loaded check-level PP override"
```
No override found: If no override file exists for a given check, Xylok logs (at DEBUG level):
```
"NO check-level PP override" error=<error>
```
The error field will typically contain a “file does not exist” message, which is expected for any check that does not have a user-supplied override.