tooling-python

# Python Audit Tooling Запуск SAST/quality tools для Python проектов. ## Когда применять - В audit phases для Python проектов - После того как `language-detector` определил Python в проекте - Tools проверены на наличие через `command -v <tool>` ## Tools ### Ruff (linting) ```bash ruff check . --output-format=json > /tmp/ruff.json 2>/dev/null ``` Установка если нет: `pip install ruff` (recommended) или через `pre-commit`. Парсить: - Errors (severity: HIGH-MEDIUM зависит от rule) - Warnings (severity: LOW) - Style issues (можно skip если есть formatter) ### MyPy (types) ```bash mypy --no-incremental --strict --json-report /tmp/mypy-report . 2>/dev/null ``` Если strict ломает - попробовать без `--strict`: ```bash mypy . --json-report /tmp/mypy-report 2>/dev/null ``` Findings по severity: - `error` codes - HIGH/MEDIUM - `note` codes - LOW Common issues: - Untyped function definitions in core modules - `Any` types где должны быть конкретные - Missing return type annotations ### Bandit (SAST) ```bash bandit -r src/ -f json -o /tmp/bandit.json --skip B101 2>/dev/null ``` `--skip B101` пропускает `assert_used` - common false positive в Django. Severity mapping: - `HIGH` confidence + `HIGH` severity → CRITICAL - `HIGH` + `MEDIUM` → HIGH - `MEDIUM` + `MEDIUM` → MEDIUM - Lower → LOW Common findings: - `subprocess_popen_with_shell_equals_true` (B602) - command injection - `request_without_timeout` (B113) - `hardcoded_password_string` (B105) ### Pip-audit (CVE check) ```bash pip-audit --format=json --output=/tmp/pip-audit.json 2>/dev/null ``` Альтернатива: `safety check --json` Парсить: - Critical CVEs (CVSS >= 9.0) → BLOCKER (если в production deps) - High CVEs → CRITICAL - Medium → HIGH/MEDIUM - Cross-reference с CISA KEV если возможно ### Radon (complexity) ```bash # Cyclomatic complexity radon cc -j -s . > /tmp/radon-cc.json 2>/dev/null # Maintainability index radon mi -j . > /tmp/radon-mi.json 2>/dev/null # Halstead metrics radon hal -j . > /tmp/radon-hal.json 2>/dev/null ``` CC thresholds: - A (1-5): excellent - B (6-10): good - C (11-20): acceptable - D (21-30): high (HIGH finding) - E (31-40): very high (CRITICAL finding) - F (40+): critical (BLOCKER finding в hot path) ### Vulture (dead code) ```bash vulture src/ --min-confidence 80 > /tmp/vulture.txt 2>/dev/null ``` `--min-confidence 80` - чтобы избежать false positives. Vulture часто триггерится на: - Django ORM relations (used through introspection) - Pytest fixtures (used by test runner) - Click command handlers Use confidence >= 80% only. ### Mutmut (mutation testing - DEEP MODE ONLY) **Внимание**: медленный (часы для крупного проекта). ```bash # Setup mutmut run --paths-to-mutate=src/ --runner='pytest -x' # Results mutmut results > /tmp/mutmut-results.txt mutmut html # creates html/index.html ``` В deep mode: - Запускать только на критичных модулях (не всё проект) - Спросить пользователя подтверждение перед запуском (estimate time first) - Если timeout > 4 hours - skip и пометить incomplete ### Detect-secrets ```bash detect-secrets scan --all-files > /tmp/secrets-baseline.json ``` Если базовая история проекта содержит секреты - они попадут в `secrets-baseline.json`. Reviewer должен пересмотреть baseline манyally. ## Output Сырые outputs в `docs/audit/<TS>/<phase>/tooling-output/python/`. Парсинг JSON outputs в findings формате (см. `templates/finding.schema.json`). ## Tool unavailability Если tool не установлен - **не падать**, документировать missing tool в audit report: ```markdown ## Missing tools (Python) The following tools were not available; coverage of Python audit was reduced: - bandit: not installed (`pip install bandit`) - mutmut: not installed; mutation testing skipped ``` ## Specific Django/DRF checks Для Django проектов дополнительно: ```bash # Django check command python manage.py check --deploy 2>/dev/null # Django security check python manage.py check --tag security 2>/dev/null ``` Эти commands выявляют: - DEBUG = True в production - Missing security middleware - Insecure SECRET_KEY - HSTS settings ## Environment isolation Если проект использует virtual env: - `.venv/` или `venv/` - стандартные пути - Активировать перед запуском tools (`source .venv/bin/activate`) - Tools должны видеть установленные dependencies проекта (pip-audit, mypy особенно)