diff --git a/README.md b/README.md index dab9439..0101b77 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,14 @@ `suricata-check` is a command line utility to provide feedback on [Suricata](https://github.com/OISF/suricata) rules. The tool can detect various issues including those covering syntax validity, interpretability, rule specificity, rule coverage, and efficiency. +## Features + +- [Static analysis without Suricata installation for any operating system](https://suricata-check.teuwen.net/readme.html) +- [Simple CLI with options to work with any ruleset](https://suricata-check.teuwen.net/cli_usage.html) +- [Clearly documented and typed API](https://suricata-check.teuwen.net/api_usage.html) +- [CI/CD integration with GitHub and GitLab](https://suricata-check.teuwen.net/ci_cd.html) +- [Easily extendable with custom checkers](https://suricata-check.teuwen.net/checker.html) + ## Installation ### From PyPI @@ -23,6 +31,8 @@ To install `suricata-check` from [PyPI](https://pypi.org/project/suricata-check/ pip install suricata-check[performance] ``` +Installation should work out-of-the-box on any Operating System (OS) and has been tested on Windows and Linux (Fedora and Ubuntu). + ### From source To install `suricata-check` from source (potentially with local modifications), simply run the following commands: @@ -52,42 +62,34 @@ More details regarding the command line interface can be found below: ``` Usage: suricata-check [OPTIONS] - Processes all rules inside a rules file and outputs a list of issues found. - - Args: - - ---- - - out: A path to a directory where the output will be written. - - rules: A path to a Suricata rules file or a directory in which a single rule file can be discovered - - single_rule: A single Suricata rule to be checked. If set, the rules file will be ignored. - - log_level: The verbosity level for logging. - - evaluate_disabled: A flag indicating whether disabled rules should be evaluated. - - Raises: - ------ + The `suricata-check` command processes all rules inside a rules file and + outputs a list of detected issues. - BadParameter: If provided arguments are invalid. + Raises: BadParameter: If provided arguments are invalid. RuntimeError: If no checkers could be automatically discovered. Options: - -o, --out TEXT Path to suricata-check output folder. - [default: .] - -r, --rules TEXT Path to Suricata rules to provide check on. - [default: .] - -s, --single-rule TEXT A single Suricata rule to be checked - --log-level TEXT Verbosity level for logging. Can be one of - ('DEBUG', 'INFO', 'WARNING', 'ERROR') - [default: INFO] - --evaluate-disabled BOOLEAN Flag to evaluate disabled rules. [default: - False] - --help Show this message and exit + -r, --rules TEXT Path to Suricata rules to provide check on. + [default: .] + -s, --single-rule TEXT A single Suricata rule to be checked + -o, --out TEXT Path to suricata-check output folder. [default: .] + --log-level TEXT Verbosity level for logging. Can be one of ('DEBUG', + 'INFO', 'WARNING', 'ERROR') [default: INFO] + --gitlab Flag to create CodeClimate output report for GitLab + CI/CD. + --github Flag to write workflow commands to stdout for GitHub + CI/CD. + --evaluate-disabled Flag to evaluate disabled rules. + --issue-severity TEXT Verbosity level for detected issues. Can be one of + ('DEBUG', 'INFO', 'WARNING', 'ERROR') [default: + INFO] + -a, --include-all Flag to indicate all checker codes should be + enabled. + -i, --include TEXT List of all checker codes to enable. + -e, --exclude TEXT List of all checker codes to disable. + --help Show this message and exit. ``` Usage of suricata-check as a module is currently not documented in detail, but the type hints and docstrings in the code should provide a decent start. diff --git a/docs/checker.md b/docs/checker.md index 2db0b55..e29d863 100644 --- a/docs/checker.md +++ b/docs/checker.md @@ -11,7 +11,7 @@ from suricata_check.utils.typing import ISSUES_TYPE class ExampleChecker(CheckerInterface): - codes = tuple() + codes = dict() def _check_rule( self: "ExampleChecker", @@ -29,6 +29,7 @@ To detect issues, you can use utility functions provided in `suricata_check.util All you have to do to add new issue types is, to add the desired issue code (e.g. `E000`) to the `codes` field of the class, and append a new `Issue` to the list of `issues` that is returned at the end of `_check_rule` depending on the output of the utlity function called from `suricata_check.utils.checker`. For example, we can add two new issue types as follows: ```python +import logging import idstools.rule from suricata_check.checkers.interface import CheckerInterface from suricata_check.utils import checker @@ -36,10 +37,10 @@ from suricata_check.utils.typing import ISSUES_TYPE, Issue class ExampleChecker(CheckerInterface): - codes = ( - "E000", - "E001", - ) + codes = { + "E000": {"severity": logging.INFO}, + "E001": {"severity": logging.INFO}, + } def _check_rule( self: "ExampleChecker", diff --git a/docs/ci_cd.md b/docs/ci_cd.md new file mode 100644 index 0000000..5243f74 --- /dev/null +++ b/docs/ci_cd.md @@ -0,0 +1,21 @@ +# CI/CD Integration + +If you maintain a large rulebase in through version-control managed platform, you may be interested in integrating `suricata-check` with your Continuous Integration and Continuous Deployment workflows. + +This is possible using the `--github` and `--gitlab` CLI options. The integration can be further adjusted to the specific deployment environment needs using [the other available CLI options](./cli_usage.rst). + +An example of such an integration for GitHub can be found [here](https://github.com/Koen1999/suricata-check-action). + +## GitHub + +Integration with GitHub is easy. All you need to do is checkout the repository containing the rules that require checking, setup a Python environment and install `suricata-check`, and run it with the `--github` option to automatically issue the required GitHub workflow commands for integration. + +For example, when integrated with GitHub, issues can be highlighted in a pull requests (PRs) similar to [this example PR](https://github.com/Koen1999/suricata-check-action/pull/1/files). + +For GitHub, you can copy [this workflow](https://github.com/Koen1999/suricata-check-action/blob/main/.github/workflows/suricata-check.yml) and modify it to your needs. + +## GitLab + +To integrate `suricata-check` with GitLab, you need to run it in a workflow with the `--gitlab` option to produce the `suricata-check-gitlab.log` file which follows the required [CodeClimate report / GitLab Code Quality Report format](https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format). + +To have GitLab process this output, you need to declare the code quality report using the syntax prescribed by [GitLab](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscodequality). diff --git a/docs/cli_usage.md b/docs/cli_usage.md index 515e73e..d2ca51c 100644 --- a/docs/cli_usage.md +++ b/docs/cli_usage.md @@ -141,7 +141,8 @@ suricata-check -o /path/to/my/output/dir "WhitespaceChecker": 0 } }, - "line": 1 + "line_begin": 1, + "line_end": 1 } ``` @@ -227,3 +228,15 @@ You can inspect the `suricata-check.log` output to verify if the intended checke 2024-12-14 15:26:43,456 - suricata_check.suricata_check - INFO - Checker WhitespaceChecker is disabled. 2024-12-14 15:26:43,456 - suricata_check.suricata_check - INFO - Discovered and enabled checkers: [MandatoryChecker, MetadataChecker] ``` + +It is also possible to enable issues based on their severity using the `--issue-severity` option. + +For example, if one would like to only see issues with severity `WARNING` or greater, one could use the following option: + +```bash +suricata-check --issue-severity=WARNING +``` + +## CI/CD Integration + +You can use `suricata-check` to generate output to be processed by platforms such as GitHub and GitLab to integrate it with your Continuous Integration and Continuous Deployment workflows using the `--gitlab` and `--github` options. Read more about those options [here](./ci_cd.rst). diff --git a/docs/index.rst b/docs/index.rst index 4311f35..6af5ba0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Welcome to suricata-check's documentation! readme.md cli_usage.md + ci_cd.md api_usage.md checker.md contributing.md