falco rules mitre checker module

Signed-off-by: Louis Cailliot <[email protected]>

.gitignore

@@ -0,0 +1,196 @@
+# Specific project files
+build/mitre_checker/build
+build/mitre_checker/reports
+**/falco_rules_mitre_errors.json
+**/application_rules_errors.json
+
+# IntelliJ project files
+.idea
+*.iml
+out
+gen
+### Go template
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+.run/
+

build/mitre_checker/.python-version

@@ -0,0 +1 @@
+3.10.12

build/mitre_checker/README.md

@@ -0,0 +1,141 @@
+# Mitre Checker Module
+
+The Mitre Checker module aims to check the compliance of the Falco rules against the Mitre ATT&CK
+Framework. This module provides to Falco experts and Falco users a way to check default and custom
+rules for Mitre ATT&CK extra tags.
+This module uses STIX from the OASIS standards. Structured Threat Information Expression (STIX™) is a
+language and serialization format used to exchange cyber threat intelligence (CTI) :
+
+- [STIX CTI documentation](https://oasis-open.github.io/cti-documentation/stix/intro)
+
+Leveraging STIX, Mitre Checker fetches the ATT&CK® STIX Data from MITRE ATT&CK repositories using the
+`python-stix2` library implemented by OASIS:
+
+- [ATT&CK STIX Data repository](https://github.com/mitre-attack/attack-stix-data)
+- [Python STIX2 repository](https://github.com/oasis-open/cti-python-stix2)
+
+The choice of a module is motivated by the packaging of a python code to integrate it into wider Falco
+implementations. More precisely, the module can be used :
+
+- by the rules_overview_generator.py script
+- by Falco users and experts to check their Falco rules files
+- by other Falco components that need to check the validity of rules files
+
+## Build
+
+Requirements :
+
+- Python >= `3.10`
+- Poetry >= `1.5.1`
+
+```sh
+./build.sh
+```
+
+## Install
+
+Requirements :
+
+- Python >= `3.10`
+
+```sh
+./install.sh
+```
+
+Or manualy using `pip` :
+
+```sh
+pip install dist/mitre_checker-0.1.0-py3-none-any.whl
+```
+
+## Usage
+
+```sh
+python -m falco_mitre_checker --help
+```
+
+Using the stable falco rules :
+
+```sh
+python -m falco_mitre_checker -f ../../rules/falco_rules.yaml -o /tmp/
+```
+
+## Development
+
+Requirements :
+
+- Python >= `3.10`
+- Poetry >= `1.5.1`
+
+```sh
+poetry check
+poetry update
+poetry install --sync
+```
+
+### Testing
+
+With coverage :
+
+```sh
+poetry update
+poetry run python -m pytest falco_mitre_checker/tests --cov=falco_mitre_checker
+```
+
+```
+---------- coverage: platform linux, python 3.10.12-final-0 ----------                                   
+Name                                                     Stmts   Miss  Cover                             
+----------------------------------------------------------------------------                             
+falco_mitre_checker/__init__.py                              0      0   100%                             
+falco_mitre_checker/__main__.py                              7      7     0%                             
+falco_mitre_checker/api/__init__.py                          0      0   100%                             
+falco_mitre_checker/api/core.py                             19     19     0%                             
+falco_mitre_checker/cli/__init__.py                          0      0   100%                             
+falco_mitre_checker/cli/core.py                             18     18     0%                             
+falco_mitre_checker/engine/__init__.py                       0      0   100%                             
+falco_mitre_checker/engine/mitre_checker.py                 46      1    98%                             
+falco_mitre_checker/exceptions/__init__.py                   0      0   100%          
+falco_mitre_checker/exceptions/rules_exceptions.py           8      0   100%                             
+falco_mitre_checker/models/__init__.py                       0      0   100%                             
+falco_mitre_checker/models/falco_mitre_errors.py            16      0   100%                             
+falco_mitre_checker/models/falco_mitre_relations.py         14      2    86%
+falco_mitre_checker/parsers/__init__.py                      0      0   100%
+falco_mitre_checker/parsers/falco_rules.py                  30      1    97%                             
+falco_mitre_checker/parsers/mitre_stix.py                   31      4    87%                            
+falco_mitre_checker/tests/__init__.py                        0      0   100%                             
+falco_mitre_checker/tests/engine/__init__.py                 0      0   100%                            
+falco_mitre_checker/tests/engine/test_mitre_checker.py      41      0   100%                            
+falco_mitre_checker/tests/parsers/__init__.py                0      0   100%                            
+falco_mitre_checker/tests/parsers/test_falco_rules.py       18      0   100%                             
+falco_mitre_checker/tests/parsers/test_mitre_stix.py        34      0   100%
+falco_mitre_checker/tests/test_common.py                    13      2    85%
+falco_mitre_checker/utils/__init__.py                        0      0   100%
+falco_mitre_checker/utils/file.py                           10      0   100%
+falco_mitre_checker/utils/logger.py                         36      7    81%
+----------------------------------------------------------------------------
+TOTAL                                                      341     61    82%
+```
+
+### Security
+
+You should run a vulnerability scanner every time you add a new dependency in projects :
+
+```sh
+poetry update
+poetry run python -m safety check
+```
+
+```
+  Using non-commercial database
+  Found and scanned 33 packages
+  Timestamp 2023-10-02 13:43:51
+  0 vulnerabilities found
+  0 vulnerabilities ignored
++=======================================================================================================+
+
+ No known security vulnerabilities found. 
+
++=======================================================================================================+
+```
+
+

build/mitre_checker/build.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+SCRIPT_PATH="$(realpath "$0")"
+MODULE_DIR="$(dirname "${SCRIPT_PATH:?}")"
+
+#
+# FUNCTIONS
+#
+
+function check_requirement(){
+    if ! eval "$@" >> /dev/null 2>&1 ; then
+        echo "! Fatal : missing requirement"
+        if [ -n "${*: -1}" ]; then echo "${@: -1}"; fi
+        exit 1
+    fi
+}
+
+#
+# MAIN
+#
+
+check_requirement poetry --version "Install poetry first"
+
+cd "${MODULE_DIR}" || exit
+echo "Build environment :"
+poetry env info
+
+echo ""
+echo "Update dependencies"
+poetry check
+poetry update --without dev
+poetry install --without dev --sync
+
+echo "Build Falco Mitre Checker module"
+rm -rf "${MODULE_DIR}/dist"
+poetry build --format wheel --no-cache
+
+echo "Built in dist/:"
+ls "${MODULE_DIR}/dist/"

build/mitre_checker/falco_mitre_checker/__main__.py

@@ -0,0 +1,16 @@
+from falco_mitre_checker.cli.core import cli
+from falco_mitre_checker.utils.logger import MitreCheckerLogger
+
+
+def main():
+    # init logger
+    MitreCheckerLogger()
+    # init cli
+    cli()
+
+
+if __name__ == '__main__':
+    """
+    for debug purpose
+    """
+    main()