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.
- maat_vuln-0.1.0/.github/PULL_REQUEST_TEMPLATE.md +9 -0
- maat_vuln-0.1.0/.github/workflows/ci.yml +49 -0
- maat_vuln-0.1.0/.github/workflows/publish.yml +93 -0
- maat_vuln-0.1.0/.gitignore +220 -0
- maat_vuln-0.1.0/.pre-commit-config.yaml +36 -0
- maat_vuln-0.1.0/CHANGELOG.md +17 -0
- maat_vuln-0.1.0/CLAUDE.md +118 -0
- maat_vuln-0.1.0/CONTRIBUTING.md +98 -0
- maat_vuln-0.1.0/LICENSE +201 -0
- maat_vuln-0.1.0/PKG-INFO +143 -0
- maat_vuln-0.1.0/README.md +95 -0
- maat_vuln-0.1.0/docs/design.md +157 -0
- maat_vuln-0.1.0/maat_vuln/__init__.py +15 -0
- maat_vuln-0.1.0/maat_vuln/cli/__init__.py +5 -0
- maat_vuln-0.1.0/maat_vuln/cli/main.py +391 -0
- maat_vuln-0.1.0/maat_vuln/engine/__init__.py +15 -0
- maat_vuln-0.1.0/maat_vuln/engine/core.py +228 -0
- maat_vuln-0.1.0/maat_vuln/feeds/__init__.py +55 -0
- maat_vuln-0.1.0/maat_vuln/feeds/cvss.py +191 -0
- maat_vuln-0.1.0/maat_vuln/feeds/epss.py +106 -0
- maat_vuln-0.1.0/maat_vuln/feeds/http.py +149 -0
- maat_vuln-0.1.0/maat_vuln/feeds/kev.py +85 -0
- maat_vuln-0.1.0/maat_vuln/models/__init__.py +68 -0
- maat_vuln-0.1.0/maat_vuln/models/finding.py +127 -0
- maat_vuln-0.1.0/maat_vuln/models/input.py +26 -0
- maat_vuln-0.1.0/maat_vuln/models/report.py +84 -0
- maat_vuln-0.1.0/maat_vuln/models/signals.py +62 -0
- maat_vuln-0.1.0/maat_vuln/policy/__init__.py +29 -0
- maat_vuln-0.1.0/maat_vuln/policy/default.py +228 -0
- maat_vuln-0.1.0/maat_vuln/snapshot/__init__.py +39 -0
- maat_vuln-0.1.0/maat_vuln/snapshot/store.py +226 -0
- maat_vuln-0.1.0/notes.md +12 -0
- maat_vuln-0.1.0/pyproject.toml +215 -0
- maat_vuln-0.1.0/schemas/input.schema.json +221 -0
- maat_vuln-0.1.0/schemas/report.schema.json +409 -0
- maat_vuln-0.1.0/scripts/generate_schemas.py +64 -0
- maat_vuln-0.1.0/tests/cli/conftest.py +64 -0
- maat_vuln-0.1.0/tests/cli/test_main.py +342 -0
- maat_vuln-0.1.0/tests/engine/test_core.py +230 -0
- maat_vuln-0.1.0/tests/feeds/cvss_bulk.json +189 -0
- maat_vuln-0.1.0/tests/feeds/epss.csv +5 -0
- maat_vuln-0.1.0/tests/feeds/kev.json +40 -0
- maat_vuln-0.1.0/tests/feeds/test_cvss.py +122 -0
- maat_vuln-0.1.0/tests/feeds/test_epss.py +94 -0
- maat_vuln-0.1.0/tests/feeds/test_http.py +168 -0
- maat_vuln-0.1.0/tests/feeds/test_kev.py +88 -0
- maat_vuln-0.1.0/tests/models/test_finding.py +137 -0
- maat_vuln-0.1.0/tests/models/test_input.py +36 -0
- maat_vuln-0.1.0/tests/models/test_report.py +106 -0
- maat_vuln-0.1.0/tests/models/test_signals.py +75 -0
- maat_vuln-0.1.0/tests/policy/test_default.py +198 -0
- maat_vuln-0.1.0/tests/snapshot/test_store.py +202 -0
|
@@ -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`.
|