maat-vuln 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. maat_vuln-0.1.0/.github/PULL_REQUEST_TEMPLATE.md +9 -0
  2. maat_vuln-0.1.0/.github/workflows/ci.yml +49 -0
  3. maat_vuln-0.1.0/.github/workflows/publish.yml +93 -0
  4. maat_vuln-0.1.0/.gitignore +220 -0
  5. maat_vuln-0.1.0/.pre-commit-config.yaml +36 -0
  6. maat_vuln-0.1.0/CHANGELOG.md +17 -0
  7. maat_vuln-0.1.0/CLAUDE.md +118 -0
  8. maat_vuln-0.1.0/CONTRIBUTING.md +98 -0
  9. maat_vuln-0.1.0/LICENSE +201 -0
  10. maat_vuln-0.1.0/PKG-INFO +143 -0
  11. maat_vuln-0.1.0/README.md +95 -0
  12. maat_vuln-0.1.0/docs/design.md +157 -0
  13. maat_vuln-0.1.0/maat_vuln/__init__.py +15 -0
  14. maat_vuln-0.1.0/maat_vuln/cli/__init__.py +5 -0
  15. maat_vuln-0.1.0/maat_vuln/cli/main.py +391 -0
  16. maat_vuln-0.1.0/maat_vuln/engine/__init__.py +15 -0
  17. maat_vuln-0.1.0/maat_vuln/engine/core.py +228 -0
  18. maat_vuln-0.1.0/maat_vuln/feeds/__init__.py +55 -0
  19. maat_vuln-0.1.0/maat_vuln/feeds/cvss.py +191 -0
  20. maat_vuln-0.1.0/maat_vuln/feeds/epss.py +106 -0
  21. maat_vuln-0.1.0/maat_vuln/feeds/http.py +149 -0
  22. maat_vuln-0.1.0/maat_vuln/feeds/kev.py +85 -0
  23. maat_vuln-0.1.0/maat_vuln/models/__init__.py +68 -0
  24. maat_vuln-0.1.0/maat_vuln/models/finding.py +127 -0
  25. maat_vuln-0.1.0/maat_vuln/models/input.py +26 -0
  26. maat_vuln-0.1.0/maat_vuln/models/report.py +84 -0
  27. maat_vuln-0.1.0/maat_vuln/models/signals.py +62 -0
  28. maat_vuln-0.1.0/maat_vuln/policy/__init__.py +29 -0
  29. maat_vuln-0.1.0/maat_vuln/policy/default.py +228 -0
  30. maat_vuln-0.1.0/maat_vuln/snapshot/__init__.py +39 -0
  31. maat_vuln-0.1.0/maat_vuln/snapshot/store.py +226 -0
  32. maat_vuln-0.1.0/notes.md +12 -0
  33. maat_vuln-0.1.0/pyproject.toml +215 -0
  34. maat_vuln-0.1.0/schemas/input.schema.json +221 -0
  35. maat_vuln-0.1.0/schemas/report.schema.json +409 -0
  36. maat_vuln-0.1.0/scripts/generate_schemas.py +64 -0
  37. maat_vuln-0.1.0/tests/cli/conftest.py +64 -0
  38. maat_vuln-0.1.0/tests/cli/test_main.py +342 -0
  39. maat_vuln-0.1.0/tests/engine/test_core.py +230 -0
  40. maat_vuln-0.1.0/tests/feeds/cvss_bulk.json +189 -0
  41. maat_vuln-0.1.0/tests/feeds/epss.csv +5 -0
  42. maat_vuln-0.1.0/tests/feeds/kev.json +40 -0
  43. maat_vuln-0.1.0/tests/feeds/test_cvss.py +122 -0
  44. maat_vuln-0.1.0/tests/feeds/test_epss.py +94 -0
  45. maat_vuln-0.1.0/tests/feeds/test_http.py +168 -0
  46. maat_vuln-0.1.0/tests/feeds/test_kev.py +88 -0
  47. maat_vuln-0.1.0/tests/models/test_finding.py +137 -0
  48. maat_vuln-0.1.0/tests/models/test_input.py +36 -0
  49. maat_vuln-0.1.0/tests/models/test_report.py +106 -0
  50. maat_vuln-0.1.0/tests/models/test_signals.py +75 -0
  51. maat_vuln-0.1.0/tests/policy/test_default.py +198 -0
  52. maat_vuln-0.1.0/tests/snapshot/test_store.py +202 -0
@@ -0,0 +1,9 @@
1
+ ## Changes
2
+
3
+ - **type(scope)** — what and why.
4
+
5
+ ## Tests
6
+
7
+ - Files/cases:
8
+ - `pytest`:
9
+ - Coverage:
@@ -0,0 +1,49 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, develop]
6
+ pull_request:
7
+ branches: [main, develop]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ lint:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v7
17
+ - uses: actions/setup-python@v7
18
+ with:
19
+ python-version: "3.12"
20
+ cache: pip
21
+ cache-dependency-path: pyproject.toml
22
+ - run: pip install -e ".[lint]"
23
+ - run: ruff check
24
+ - run: ruff format --check
25
+ - run: lint-imports
26
+ - run: python scripts/generate_schemas.py --check
27
+
28
+ test-matrix:
29
+ runs-on: ubuntu-latest
30
+ strategy:
31
+ fail-fast: false
32
+ matrix:
33
+ python-version: ["3.12", "3.13", "3.14"]
34
+ steps:
35
+ - uses: actions/checkout@v7
36
+ - uses: actions/setup-python@v7
37
+ with:
38
+ python-version: ${{ matrix.python-version }}
39
+ cache: pip
40
+ cache-dependency-path: pyproject.toml
41
+ - run: pip install -e ".[test]"
42
+ - run: pytest
43
+
44
+ test:
45
+ if: always()
46
+ needs: test-matrix
47
+ runs-on: ubuntu-latest
48
+ steps:
49
+ - run: test "${{ needs.test-matrix.result }}" = success
@@ -0,0 +1,93 @@
1
+ name: Publish
2
+
3
+ on:
4
+ push:
5
+ branches: ["release/**"]
6
+ tags: ["v*"]
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ # Building apart from publishing keeps the OIDC token away from build steps.
13
+ build:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v7
17
+ - uses: actions/setup-python@v7
18
+ with:
19
+ python-version: "3.12"
20
+ cache: pip
21
+ cache-dependency-path: pyproject.toml
22
+ - run: pip install ".[release]"
23
+ - name: Set the rehearsal version
24
+ if: github.ref_type == 'branch'
25
+ # TestPyPI never accepts the same version twice: one per run.
26
+ run: |
27
+ sed -i -E "s/^version = \"([^\"]+)\"$/version = \"\1.dev$GITHUB_RUN_NUMBER\"/" pyproject.toml
28
+ grep -qE '^version = ".+\.dev[0-9]+"$' pyproject.toml
29
+ - name: Check the tag and extract the release notes
30
+ if: github.ref_type == 'tag'
31
+ run: |
32
+ version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
33
+ test "${GITHUB_REF_NAME#v}" = "$version"
34
+ awk -v v="$version" '/^## /{p = ($2 == v); next} p' CHANGELOG.md > notes.md
35
+ grep -q '[^[:space:]]' notes.md
36
+ - run: python -m build
37
+ - uses: actions/upload-artifact@v7
38
+ with:
39
+ name: dist
40
+ path: dist/
41
+ - if: github.ref_type == 'tag'
42
+ uses: actions/upload-artifact@v7
43
+ with:
44
+ name: release-notes
45
+ path: notes.md
46
+
47
+ testpypi:
48
+ if: github.ref_type == 'branch'
49
+ needs: build
50
+ runs-on: ubuntu-latest
51
+ environment: testpypi
52
+ permissions:
53
+ id-token: write
54
+ steps:
55
+ - uses: actions/download-artifact@v8
56
+ with:
57
+ name: dist
58
+ path: dist/
59
+ - uses: pypa/gh-action-pypi-publish@release/v1
60
+ with:
61
+ repository-url: https://test.pypi.org/legacy/
62
+
63
+ pypi:
64
+ if: github.ref_type == 'tag'
65
+ needs: build
66
+ runs-on: ubuntu-latest
67
+ environment: pypi
68
+ permissions:
69
+ id-token: write
70
+ steps:
71
+ - uses: actions/download-artifact@v8
72
+ with:
73
+ name: dist
74
+ path: dist/
75
+ - uses: pypa/gh-action-pypi-publish@release/v1
76
+
77
+ github-release:
78
+ needs: pypi
79
+ runs-on: ubuntu-latest
80
+ permissions:
81
+ contents: write
82
+ steps:
83
+ - uses: actions/download-artifact@v8
84
+ with:
85
+ name: dist
86
+ path: dist/
87
+ - uses: actions/download-artifact@v8
88
+ with:
89
+ name: release-notes
90
+ - run: gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file notes.md dist/*
91
+ env:
92
+ GH_TOKEN: ${{ github.token }}
93
+ GH_REPO: ${{ github.repository }}
@@ -0,0 +1,220 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ *.lcov
51
+ .hypothesis/
52
+ .pytest_cache/
53
+ cover/
54
+
55
+ # Translations
56
+ *.mo
57
+ *.pot
58
+
59
+ # Django stuff:
60
+ *.log
61
+ local_settings.py
62
+ db.sqlite3
63
+ db.sqlite3-journal
64
+
65
+ # Flask stuff:
66
+ instance/
67
+ .webassets-cache
68
+
69
+ # Scrapy stuff:
70
+ .scrapy
71
+
72
+ # Sphinx documentation
73
+ docs/_build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ # Pipfile.lock
97
+
98
+ # uv
99
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ # uv.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ # poetry.lock
110
+ # poetry.toml
111
+
112
+ # pdm
113
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
114
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
115
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
116
+ # pdm.lock
117
+ # pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # pixi
122
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
123
+ # pixi.lock
124
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
125
+ # in the .venv directory. It is recommended not to include this directory in version control.
126
+ .pixi/*
127
+ !.pixi/config.toml
128
+
129
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
130
+ __pypackages__/
131
+
132
+ # Celery stuff
133
+ celerybeat-schedule*
134
+ celerybeat.pid
135
+
136
+ # Redis
137
+ *.rdb
138
+ *.aof
139
+ *.pid
140
+
141
+ # RabbitMQ
142
+ mnesia/
143
+ rabbitmq/
144
+ rabbitmq-data/
145
+
146
+ # ActiveMQ
147
+ activemq-data/
148
+
149
+ # SageMath parsed files
150
+ *.sage.py
151
+
152
+ # Environments
153
+ .env
154
+ .envrc
155
+ .venv
156
+ env/
157
+ venv/
158
+ ENV/
159
+ env.bak/
160
+ venv.bak/
161
+
162
+ # Spyder project settings
163
+ .spyderproject
164
+ .spyproject
165
+
166
+ # Rope project settings
167
+ .ropeproject
168
+
169
+ # mkdocs/Zensical documentation
170
+ /site
171
+
172
+ # mypy
173
+ .mypy_cache/
174
+ .dmypy.json
175
+ dmypy.json
176
+
177
+ # Pyre type checker
178
+ .pyre/
179
+
180
+ # pytype static type analyzer
181
+ .pytype/
182
+
183
+ # Cython debug symbols
184
+ cython_debug/
185
+
186
+ # PyCharm
187
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
188
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
189
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
190
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
191
+ # .idea/
192
+
193
+ # Abstra
194
+ # Abstra is an AI-powered process automation framework.
195
+ # Ignore directories containing user credentials, local state, and settings.
196
+ # Learn more at https://abstra.io/docs
197
+ .abstra/
198
+
199
+ # Visual Studio Code
200
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
201
+ # can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
202
+ # and can be added to the global gitignore or merged into this file. However, if you prefer, you
203
+ # could uncomment the following to ignore the entire vscode folder
204
+ # .vscode/
205
+ # Temporary file for partial code execution
206
+ tempCodeRunnerFile.py
207
+
208
+ # Ruff stuff:
209
+ .ruff_cache/
210
+
211
+ # PyPI configuration file
212
+ .pypirc
213
+
214
+ # Marimo
215
+ marimo/_static/
216
+ marimo/_lsp/
217
+ __marimo__/
218
+
219
+ # Streamlit
220
+ .streamlit/secrets.toml
@@ -0,0 +1,36 @@
1
+ # Mirrors the CI lint job. Hooks run the venv's tools so that versions come
2
+ # from pyproject.toml, as in CI: activate the venv before committing.
3
+ default_install_hook_types: [pre-commit, commit-msg]
4
+ default_stages: [pre-commit]
5
+
6
+ repos:
7
+ - repo: local
8
+ hooks:
9
+ - id: ruff-check
10
+ name: ruff check
11
+ entry: ruff check
12
+ language: system
13
+ types_or: [python, pyi]
14
+ - id: ruff-format
15
+ name: ruff format --check
16
+ entry: ruff format --check
17
+ language: system
18
+ types_or: [python, pyi]
19
+ - id: lint-imports
20
+ name: lint-imports
21
+ entry: lint-imports
22
+ language: system
23
+ files: (\.py|pyproject\.toml)$
24
+ pass_filenames: false
25
+ - id: schema-drift
26
+ name: JSON Schema drift
27
+ entry: python scripts/generate_schemas.py --check
28
+ language: system
29
+ files: ^(maat_vuln/models/|schemas/|scripts/generate_schemas\.py)
30
+ pass_filenames: false
31
+ - id: conventional-commit
32
+ name: Conventional Commits message
33
+ entry: '\A(Merge |(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?: [^\n]{1,100}$)'
34
+ language: pygrep
35
+ args: [--multiline, --negate]
36
+ stages: [commit-msg]
@@ -0,0 +1,17 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ ## 0.1.0 - 2026-10-31
6
+
7
+ First release: the reproducible core.
8
+
9
+ ### Features
10
+
11
+ - **models**: Pydantic data contract for findings, signals, decisions and reports, with uppercase IDs, a CVE pivot over aliases and merging of findings that share a vulnerability and a component
12
+ - **schemas**: JSON Schemas for the input document and the report, generated from the models
13
+ - **policy**: `maat-default` v1 policy, P1 for KEV, then P2–P4 from the EPSS probability with CVSS as a secondary signal; every decision names its rule, thresholds and flags for missing data
14
+ - **snapshot**: KEV and EPSS feeds stored in dated snapshots identified by the SHA-256 of their manifest, with CVSS lookups cached beside it
15
+ - **feeds**: CISA KEV catalog, FIRST EPSS scores and CIRCL Vulnerability-Lookup CVSS clients over one shared HTTP client with timeouts, retries and bounded concurrency
16
+ - **engine**: `prioritize` / `aprioritize` and `fetch_snapshot` / `afetch_snapshot` library entry points
17
+ - **cli**: `maat rank`, `maat explain`, `maat snapshot fetch` and `maat snapshot show`, with table and JSON output
@@ -0,0 +1,118 @@
1
+ # maat-vuln
2
+
3
+ Maat: exploitation-driven vulnerability prioritization, as a Python library first with a thin CLI on top. It ranks vulnerabilities with CISA KEV and FIRST EPSS (CVSS as a secondary signal); every verdict is explained and tied to a dated, hashed snapshot of the feeds.
4
+
5
+ The design (data contract, default policy, roadmap) is the reference for every decision:
6
+
7
+ @docs/design.md
8
+
9
+ ## Scope
10
+
11
+ - Work only on the current milestone: the first roadmap milestone in `docs/design.md` that has no release yet (compare with `version` in `pyproject.toml` and `CHANGELOG.md`). Do not start features of later milestones.
12
+ - When the design doc is silent or ambiguous, ask instead of guessing. Items marked **Provisional** may be implemented as written but must stay easy to change.
13
+ - Feed endpoints and formats change: check them against the official documentation before writing a client, and keep the URL used in the code.
14
+
15
+ ## Environment
16
+
17
+ - Package manager: pip + venv.
18
+ - No `requirements*.txt` — `pyproject.toml` is the single source of truth for dependencies. Never add a parallel requirements file.
19
+ - Setup: `python3 -m venv .venv && . .venv/bin/activate`
20
+ - Install: `pip install -e ".[dev]"` (aggregates `test` + `lint` + `release` groups; use `.[test]`, `.[lint]` or `.[release]` alone for a narrower install).
21
+ - Runtime stack: Pydantic v2 (single source of truth for the data contract), Typer (CLI), Rich (tables), httpx (HTTP), platformdirs (cache location). Test stack: pytest, pytest-cov, pytest-asyncio, respx.
22
+
23
+ ## Layout
24
+
25
+ - Flat layout, no `src/`: the package lives directly at the repo root as `maat_vuln/`.
26
+ - Expected subpackages: `models/` (contract), `feeds/` (KEV, EPSS, CVSS clients), `snapshot/`, `policy/`, `engine/` (entry points, re-exported by `maat_vuln`), `cli/`. Create them progressively, as each feature is implemented — do not pre-create empty subpackages or empty test directories/files.
27
+ - `tests/` mirrors the package structure. No `__init__.py` in `tests/` or its subdirectories. Each test directory has its own `conftest.py` when it needs fixtures.
28
+ - Each subpackage's `__init__.py` re-exports its public symbols via `__all__` (e.g. `models/__init__.py` re-exports `Finding`, `Decision`). Code outside that subpackage imports from the subpackage itself (`from maat_vuln.models import Finding`), never by reaching into the submodule directly (`from maat_vuln.models.finding import Finding`). Cross-imports within the same subpackage may use the direct submodule path.
29
+ - This convention is enforced by `import-linter` (`[tool.importlinter]` in pyproject.toml, run via `lint-imports`): one `forbidden` contract per subpackage bars every *other* subpackage (and `tests/`) from importing its submodules directly. Whenever a new submodule with public exports is created, add it to the relevant contract's `forbidden_modules` list in the same commit — otherwise the rule silently does not cover it.
30
+ - JSON Schemas generated from the Pydantic models live in `schemas/` and are committed; CI fails if they drift from the models. Regenerate them with `python scripts/generate_schemas.py`.
31
+
32
+ ## Code style
33
+
34
+ Config lives in `pyproject.toml`. Rules are never disabled to make code pass; the code changes instead.
35
+
36
+ - Line length: 79 (PEP 8, not Black's 88).
37
+ - Docstrings: Google convention, required on every module (including test files and `conftest.py`) and every function/class/method.
38
+ - Blank line after a module docstring, before the first import/statement.
39
+ - No blank line after a function/method docstring (`D202`, enforced, not disabled).
40
+ - `# pragma: no cover` is for genuinely non-testable infrastructure lines only (e.g. reading package version via `importlib.metadata`) — not a shortcut to dodge the coverage threshold.
41
+ - The library never prints; only `cli/` writes to the terminal.
42
+ - Thresholds, rule IDs and flag names are named constants, never inline literals.
43
+ - Determinism: stable sort orders, RFC 3339 UTC timestamps, uppercase vulnerability IDs.
44
+
45
+ ## Type hints
46
+
47
+ Enforced by ruff `ANN` rules — never disabled to make code pass.
48
+
49
+ - Every function, method, and `__init__` must have full annotations: every parameter and the return type, including `-> None` where nothing is returned.
50
+ - Use built-in generics (`list[str]`, `dict[str, int]`), not `List`/`Dict` from `typing` (PEP 585).
51
+ - Use `X | None`, not `Optional[X]` (PEP 604).
52
+ - Pydantic model fields are typed directly on the class body; do not re-annotate them in a custom `__init__`.
53
+ - `Any` is a last resort, not a convenience — prefer a precise type, a `TypeVar`, or a `Protocol`.
54
+ - Exception: `tests/**` is exempt from `ANN` (`per-file-ignores` in `pyproject.toml`). Docstrings are still required there.
55
+
56
+ ## Comments
57
+
58
+ - Comments explain why a choice was made, not what the code does.
59
+ - No commented-out code committed, ever — delete it, Git keeps the history.
60
+ - Skip comments that restate the obvious.
61
+
62
+ ## Tests
63
+
64
+ - `pytest`, with `--import-mode=importlib`.
65
+ - Coverage via `pytest-cov`, threshold `fail_under = 80` in `pyproject.toml`.
66
+ - Run: `pytest` (all config comes from `pyproject.toml`, no flags needed).
67
+ - Tests never hit the network: mock HTTP with respx and use small committed fixtures (trimmed real feed samples) next to the tests that use them.
68
+
69
+ ## Commits and branches
70
+
71
+ - Conventional Commits for commit messages and pull request titles: `^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?: .{1,100}`. Commit messages are checked locally by the pre-commit `commit-msg` hook; PR titles are not checked automatically, so get them right by hand.
72
+ - Branch names: `^(feature|fix|hotfix|release|docs|chore|refactor|test|ci|build|perf|style)/[a-z0-9]+(?:[-.][a-z0-9]+)*$`
73
+ - Group commits by unit of meaning, not by file — never one giant commit, never one commit per file.
74
+ - `develop` is the default branch; `main` holds the latest stable release only. Both are protected by repository rulesets: PR required, no direct or force push, no deletion, `lint` and `test` checks required.
75
+ - All other branches are ephemeral: force pushes are blocked everywhere (no `push --force` after a rebase or an amend), and head branches are deleted automatically once their PR is merged.
76
+ - Merge methods (rebase merging is disabled):
77
+ - ephemeral branch → `develop`: **squash**. The PR title becomes the commit subject and the PR description its body, so both are what git-cliff and the history keep.
78
+ - `release/X.Y.Z` or `hotfix/<name>` → `main`: **merge commit** (the only method the `main` ruleset allows).
79
+ - `main` → `develop` (merge back): **merge commit**. The `develop` ruleset allows both squash and merge, so choosing the right one here is a convention.
80
+ - Pull requests: the description follows `.github/PULL_REQUEST_TEMPLATE.md` (`## Changes`, one bullet per logical change as `**type(scope)**` — what and why; `## Tests`, files/cases, `pytest` result, coverage).
81
+ - `CONTRIBUTING.md` is the contributor-facing version of these rules: when a convention here changes, update it in the same commit.
82
+
83
+ ## Pre-commit
84
+
85
+ - `.pre-commit-config.yaml` mirrors the CI `lint` job: `ruff check`, `ruff format --check`, `lint-imports`, schema drift check, plus a `commit-msg` hook validating Conventional Commits. `pytest` stays out of it (CI runs it).
86
+ - `pre-commit` belongs to the `lint` dependency group. Install the hooks with `pre-commit install --hook-type pre-commit --hook-type commit-msg`.
87
+ - When a check is added to the CI `lint` job, add it to pre-commit in the same commit.
88
+
89
+ ## Documentation
90
+
91
+ - Markdown files: no hard-wrapped lines (one paragraph or list item per line), exactly one blank line between blocks, headings in sentence case, and text after a `**Label**:` continues in lowercase unless it starts with a proper noun.
92
+ - Links in `README.md` are absolute URLs to the `main` branch (`blob/main/` for files, `tree/main/` for directories): it is also the PyPI project page.
93
+ - Never document an unreleased feature as available. The roadmap section of the README may announce planned versions as planned.
94
+ - Do not mention other projects as consumers of Maat in public documentation.
95
+
96
+ ## CI
97
+
98
+ `.github/workflows/ci.yml` runs on `push`/`pull_request` to `main`/`develop` only: a `lint` job (`ruff check` + `ruff format --check` + `lint-imports` + schema drift check) on Python 3.12 and a `test-matrix` job (`pytest`) on Python 3.12, 3.13 and 3.14, summed up by a `test` job. Each installs only its own dependency group (`.[lint]` or `.[test]`), not `.[dev]`.
99
+
100
+ The rulesets require the `lint` and `test` checks by name: never rename these jobs.
101
+
102
+ `.github/workflows/publish.yml` publishes through PyPI trusted publishing (OIDC, no token): a push to `release/**` publishes a `X.Y.Z.devN` rehearsal to TestPyPI (environment `testpypi`); a `vX.Y.Z` tag checks it matches `pyproject.toml`, publishes to PyPI (environment `pypi`) and creates the GitHub release with the version's `CHANGELOG.md` section as notes.
103
+
104
+ ## Releases
105
+
106
+ Versions follow SemVer `X.Y.Z`, configured in `[tool.git-cliff.bump]` with `features_always_bump_minor = true` and `breaking_always_bump_major = false`: until 1.0, `fix` bumps the patch version, while `feat` and breaking changes bump the minor one. A roadmap milestone `v0.N` is the `0.N.x` release series, so the features of one milestone ship together in one release. The version is hardcoded in `pyproject.toml`; `CHANGELOG.md` is generated by git-cliff (`[tool.git-cliff]` in `pyproject.toml`), except the hand-written 0.1.0 entry.
107
+
108
+ 1. Create `release/X.Y.Z` from `develop` (hotfix: `hotfix/<name>` from `main`).
109
+ 2. Set `version` in `pyproject.toml` to `git cliff --bumped-version` (without the `v`), then run `git cliff --unreleased --tag vX.Y.Z --prepend CHANGELOG.md` and review the new section. Commit both together as `chore(release): prepare X.Y.Z`.
110
+ 3. Push the branch: the TestPyPI rehearsal runs. Install it in a clean venv (`pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ maat-vuln==X.Y.Z.devN`, with the version the workflow published; `--pre` would also pull pre-releases of the dependencies) and run `maat` on a few CVE IDs.
111
+ 4. Open the PR from `release/X.Y.Z` into `main` and merge it with a merge commit. Make sure the changelog date is the release day.
112
+ 5. Tag the merge commit on `main` (`git tag -a vX.Y.Z -m vX.Y.Z`) and push the tag: PyPI publishing and the GitHub release follow. Release tags `v*` cannot be moved or deleted.
113
+ 6. Open a PR from `main` into `develop` and merge it with a merge commit, never a squash: git-cliff only sees tags that are ancestors of the current branch. If it conflicts, resolve on a temporary branch created from `main` (`git merge develop`, fix, PR into `develop` with a merge commit), never by committing to `main`.
114
+
115
+ ## Working with Claude Code
116
+
117
+ - Plan first (plan mode), then implement in small steps; run `ruff check`, `ruff format --check`, `lint-imports` and `pytest` after each step.
118
+ - Use available skills when their description matches the task; do not ask before using one.
@@ -0,0 +1,98 @@
1
+ # Contributing to Maat
2
+
3
+ Thanks for your interest in Maat. This guide covers the conventions every change follows. The design document, [docs/design.md](docs/design.md), is the reference for every decision: read it before proposing a feature.
4
+
5
+ ## Scope
6
+
7
+ Work happens one roadmap milestone at a time: the current milestone is the first one in the design document that has no release yet. Features of later milestones are not accepted ahead of time. When the design document is silent or ambiguous, open an issue to discuss it before writing code.
8
+
9
+ ## Setup
10
+
11
+ Maat uses pip and a virtual environment. `pyproject.toml` is the single source of truth for dependencies: there is no `requirements*.txt`, and none should be added.
12
+
13
+ ```sh
14
+ python3 -m venv .venv && . .venv/bin/activate
15
+ pip install -e ".[dev]"
16
+ pre-commit install --hook-type pre-commit --hook-type commit-msg
17
+ ```
18
+
19
+ The `dev` extra aggregates `test`, `lint` and `release`; install one of them alone (`.[test]`, `.[lint]` or `.[release]`) for a narrower environment. The pre-commit hooks run the tools from the virtual environment, so activate it before committing.
20
+
21
+ ## Checks
22
+
23
+ Run these before pushing; CI runs the same ones:
24
+
25
+ ```sh
26
+ ruff check
27
+ ruff format --check
28
+ lint-imports
29
+ python scripts/generate_schemas.py --check
30
+ pytest
31
+ ```
32
+
33
+ The pre-commit hooks mirror the CI `lint` job (`ruff check`, `ruff format --check`, `lint-imports`, schema drift check) and validate commit messages. `pytest` is left to CI. When a check is added to the CI `lint` job, it is added to pre-commit in the same commit.
34
+
35
+ The JSON Schemas in `schemas/` are generated from the Pydantic models and committed: after changing a model, regenerate them with `python scripts/generate_schemas.py` and commit them with the change.
36
+
37
+ ## Branches
38
+
39
+ `develop` is the default branch; `main` holds the latest stable release only. Both are protected: changes go through a pull request with the `lint` and `test` checks passing.
40
+
41
+ Branch names follow `^(feature|fix|hotfix|release|docs|chore|refactor|test|ci|build|perf|style)/[a-z0-9]+(?:[-.][a-z0-9]+)*$`, for example `feature/kev-client` or `fix/epss-date-parsing`. Branches are deleted automatically once merged.
42
+
43
+ Force pushes are blocked everywhere: do not rebase or amend commits that are already pushed, push new commits instead.
44
+
45
+ ## Commits
46
+
47
+ Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/): `^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-z0-9._/-]+\))?!?: .{1,100}`. The `commit-msg` hook checks them locally.
48
+
49
+ Group commits by unit of meaning, not by file: neither one giant commit nor one commit per file.
50
+
51
+ ## Pull requests
52
+
53
+ - **Title**: a Conventional Commits subject as well. It is not checked automatically, so get it right by hand: on merge into `develop` it becomes the commit subject that the changelog keeps.
54
+ - **Description**: follow the template. Under `## Changes`, one bullet per logical change as `**type(scope)**` — what and why; under `## Tests`, the files and cases, the `pytest` result and the coverage.
55
+ - **Merge method**: pull requests into `develop` are squashed, so the title and description become the commit subject and body. Release and hotfix branches are merged into `main` with a merge commit, and `main` is merged back into `develop` with a merge commit, never a squash.
56
+
57
+ ## Code layout
58
+
59
+ - The package lives at the repository root as `maat_vuln/` (no `src/`). Subpackages are created when a feature needs them, never in advance.
60
+ - Each subpackage re-exports its public symbols from its `__init__.py` via `__all__`. Code outside a subpackage imports from the subpackage (`from maat_vuln.models import Finding`), never from its submodules. `import-linter` enforces this: when you add a submodule with public exports, add it to the `forbidden_modules` of its subpackage's contract in `pyproject.toml`, in the same commit.
61
+ - The library never prints; only the CLI writes to the terminal.
62
+ - Thresholds, rule IDs and flag names are named constants, never inline literals.
63
+ - Output is deterministic: stable sort orders, RFC 3339 UTC timestamps, uppercase vulnerability IDs.
64
+
65
+ ## Code style
66
+
67
+ The ruff configuration in `pyproject.toml` is authoritative. Rules are never disabled to make code pass: the code changes instead.
68
+
69
+ - Line length is 79.
70
+ - Every module (test files and `conftest.py` included), class, function and method has a Google-style docstring.
71
+ - Every function and method is fully annotated, including `-> None`. Use built-in generics (`list[str]`) and `X | None`. `Any` is a last resort. Tests are exempt from annotations, not from docstrings.
72
+ - Comments explain why, not what. Commented-out code is never committed.
73
+ - `# pragma: no cover` is reserved for genuinely untestable infrastructure lines, not for reaching the coverage threshold.
74
+
75
+ ## Tests
76
+
77
+ - `tests/` mirrors the package structure, without `__init__.py` files. A test directory gets its own `conftest.py` when it needs fixtures.
78
+ - Coverage must stay at or above 80%.
79
+ - Tests never hit the network: mock HTTP with respx and use small committed fixtures (trimmed real feed samples) next to the tests that use them.
80
+
81
+ ## Documentation
82
+
83
+ Markdown files use one line per paragraph or list item (no hard wrapping), exactly one blank line between blocks and sentence-case headings. Text after a `**Label**:` continues in lowercase unless it starts with a proper noun.
84
+
85
+ Links in `README.md` are absolute URLs to the `main` branch, because the README is also the PyPI project page. Unreleased features are never documented as available; the README roadmap may announce them as planned.
86
+
87
+ ## Releases
88
+
89
+ Versions follow SemVer. Until 1.0, `fix` bumps the patch version, while `feat` and breaking changes bump the minor one. A roadmap milestone `v0.N` is the `0.N.x` release series. `CHANGELOG.md` is generated by git-cliff from the commit history.
90
+
91
+ Maintainers release as follows:
92
+
93
+ 1. Create `release/X.Y.Z` from `develop` (for a hotfix: `hotfix/<name>` from `main`).
94
+ 2. Set `version` in `pyproject.toml` to `git cliff --bumped-version` (without the `v`), run `git cliff --unreleased --tag vX.Y.Z --prepend CHANGELOG.md` and review the new section. Commit both as `chore(release): prepare X.Y.Z`.
95
+ 3. Push the branch: a `X.Y.Z.devN` rehearsal is published to TestPyPI. Install it in a clean virtual environment (`pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ maat-vuln==X.Y.Z.devN`, with the version the workflow published; `--pre` would also pull pre-releases of the dependencies) and run `maat` on a few CVE IDs.
96
+ 4. Open the pull request from `release/X.Y.Z` into `main` and merge it with a merge commit. Make sure the changelog date is the release day.
97
+ 5. Tag the merge commit on `main` (`git tag -a vX.Y.Z -m vX.Y.Z`) and push the tag: PyPI publishing and the GitHub release follow. Release tags cannot be moved or deleted.
98
+ 6. Open a pull request from `main` into `develop` and merge it with a merge commit. If it conflicts, resolve it on a temporary branch created from `main` (`git merge develop`, fix, pull request into `develop` with a merge commit), never by committing to `main`.