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.

An example of such an integration for GitHub is available in the suricata-check-action repository.

Passing CLI options using an INI file

When integrating suricata-check into a project, it is recommended to configure suricata-check using a .ini file as documented on the documentation page dedicated to configuration using the INI file. By doing so, all collaborators to the project will adhere to the same quality standards and CI/CD linting outcomes will be in-line with local linting outcomes.

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.

For GitHub, you can copy this workflow and modify it to your needs.

name: Suricata Check

on:
  pull_request:
    branches: ["main", "master"]
  push:
    branches: ["main", "master"]
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

jobs:
  suricata-check:
    name: Suricata Check
    runs-on: ubuntu-latest

    strategy:
      fail-fast: true

    steps:
      - uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v6

      - name: Install dependencies
        run: |
          python -m pip install --upgrade --upgrade-strategy eager pip
          python -m pip install suricata-check[performance]

      - name: Test with suricata-check
        run: |
          suricata-check --github

Below you can find an example of how the issued detected by suricata-check would be highlighted in GitHub.

Example GitHub workflow where issues with Suricata rules are highlighted.

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.json file which follows the required CodeClimate report / GitLab Code Quality Report format.

To have GitLab process this output, you need to declare the code quality report using the syntax prescribed by GitLab.