tooling-python

name	tooling-python
description	Python audit tooling: ruff (linting), mypy (types), bandit (SAST), pip-audit (CVEs), radon (complexity), vulture (dead code), mutmut (mutations). Use during audit phases for Python projects.

Python Audit Tooling

Запуск SAST/quality tools для Python проектов.

Когда применять

• В audit phases для Python проектов
• После того как language-detector определил Python в проекте
• Tools проверены на наличие через command -v <tool>

Tools

Ruff (linting)

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)

mypy --no-incremental --strict --json-report /tmp/mypy-report . 2>/dev/null

Если strict ломает - попробовать без --strict:

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)

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)

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)

# 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)

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)

Внимание: медленный (часы для крупного проекта).

# 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

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:

## 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 проектов дополнительно:

# 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 особенно)