From 62aa1df4a63023a6fefde78a478a0e2979e2bfb3 Mon Sep 17 00:00:00 2001 From: Juliana Fajardini Date: Wed, 6 Jul 2022 16:35:12 -0300 Subject: [PATCH] readme: update createst explanation, add examples There were optional arguments missing in the usage shown, as well as in the list with explanations about possible arguments. --- README.md | 48 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cc4f390c4..25933051b 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ requires: # Require that the Suricata version be less than a version. lt-version: 6 - # Test is only for this version. For example, 4.0 would match any 4.0 + # Test is only for this version. For example, 4.0 would match any 4.0 # release, but 4.0.3 would only match 4.0.3. version: 4.0 @@ -147,17 +147,18 @@ checks: # A check that compares two files filename: datasets.csv expected: expected/datasets.csv -``` +``` ## Adding a new test the automated way: createst -Script to create a test directory with test.yaml for a given PCAP. This -needs to be run from a valid Suricata source directory. +Createst is a script to create a test directory with test.yaml for a given PCAP. +This needs to be run from a valid Suricata source directory. ### Usage ``` usage: createst.py [-h] [--output-path ] [--eventtype-only] - [--allow-events [ALLOW_EVENTS]] + [--allow-events [ALLOW_EVENTS]] [--rules ] + [--strictcsums] [--min-version ] Create tests with a given PCAP. Execute the script from a valid Suricata source @@ -169,10 +170,47 @@ positional arguments: optional arguments: -h, --help show this help message and exit + --rules + Path to rules file (optional) --output-path Path to the folder where generated test.yaml should be put --eventtype-only Create filter blocks based on event types only + This means the subfields of the event in the eve log + will not be added to the test.yaml file --allow-events [ALLOW_EVENTS] Create filter blocks for the specified events + Events must be comma-separated only + This means that just the events listed will be checked + against in the test + --strictcsums Strictly validate checksum + --min-version + Adds a global minimum required version +``` + +### Examples + +The only mandatory arguments for ``createst.py`` are the test name and the pcap +file. These examples show how some of the optional arguments can be used. + +#### Example 1 + +Create a Suricata-verify test named ``test-01`` that runs over a pcap file called +``input.pcap`` and that requires strict checksums, filters only on the event-types +and uses no Suricata rules: ``` +../suricata-verify/createst.py --strictcsums --eventtype-only test-01 input.pcap +``` + +#### Example 2 + +Create a Suricata-verify test named ``test-02`` that runs over a pcap file called +``input.pcap``, only checks for ``http``, ``alert`` and ``flow`` events, and +uses a rules file located in another test in the same suricata-verify folder. +It also doesn't require strict checksums and will run only for versions 6 and +newer: +``` +../suricata-verify/createst.py --min-version 6 --allow-events http,alert,flow \ +--rules ../suricata-verify/tests/no-payload-output/test.rules test-02 input.pcap +``` + -- 2.47.2