The crs-toolchain is the utility belt of CRS developers. It provides a single point of entry and a consistent interface for a range of different tools. Its core functionality (owed to the great rassemble-go, which is itself based on the brain-melting Regexp::Assemble Perl module) is to assemble individual parts of a regular expression into a single expression (with some optimizations).
With Existing Go Environment
If a current Go environment is present, simply run
go install github.com/coreruleset/crs-toolchain@latest
Provided that the Go binaries are on the
PATH, the toolchain can now be run from anywhere with
With the Binary
Alternatively, one of the pre-built binaries can be downloaded from GitHub. Navigate to the latest release and download the package of choice along with the
crs-toolchain-checksums.txt file. To verify the integrity of the binary/archive, navigate to the directory where the two files are stored and verify that the checksum matches:
shasum -a 256 -c crs-toolchain-checksums.txt 2>&1 | grep OK
The output should look like the following (depending on the binary/archive downloaded):
Test the Toolchain
It should now be possible to use the crs-toolchain. Test this by running the following in a shell:
printf "(?:homer)? simpson\n(?:lisa)? simpson" | crs-toolchain regex generate -
The output should be:
Adjusting the Logging Level
The level of logging can be adjusted with the
--log-level option. Accepted values are
disabled. The default level is
Read the built-in help text for the full documentation:
regex command provides sub-commands for everything surrounding regular expressions, especially the “assembly” of regular expressions from a specification of its components (see Assembling Regular Expressions for more details).
To generate a reduced expression from a list of expressions, simply pass the corresponding CRS rule ID to the script or pipe the contents to it:
crs-toolchain regex generate 942170
cat regex-assembly/942170.ra | crs-toolchain regex generate -
It is also possible to compare generated expressions to the current expressions in the rule files, like so:
crs-toolchain regex compare 942170
Even better, rule files can be updated directly:
crs-toolchain regex update 942170
# or update all
crs-toolchain regex update --all
format sub-command reports formatting violations and actively formats assembly files:
crs-toolchain regex format --all
util command includes sub-commands that are used from time to time and do not fit nicely into any of the other groups. Currently, the only sub-command is
renumber-tests is used to simplify maintenance of the regression tests. Since every test has a consecutive number within its file, adding or removing tests can disrupt numbering.
renumber-tests will renumber all tests within each test file consecutively.
completion command can be used to generate a shell script for shell completion. For example:
mkdir -p ~/.oh-my-zsh/completions && crs-toolchain completion zsh > ~/.oh-my-zsh/completions/_crs-toolchain
How completion is enabled and where completion scripts are sourced from depends on the environment. Please consult the documentation of the shell in use.