Updated documentation to reflect changes

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.

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,17 +29,18 @@ 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
 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",

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).

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).

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