college-infos/scripts/check_secrets.py

#!/usr/bin/env python3
"""Vérifie l'absence de secrets littéraux avant un déploiement.

Le script inspecte le contenu textuel du dépôt, ou uniquement les fichiers
ajoutés/modifiés dans l'index avec ``--staged``. Il ne transmet jamais la
valeur détectée : les résultats ne contiennent que le chemin, le numéro de
ligne et le type de motif. Les fichiers d'environnement et les répertoires
générés sont exclus, car ils ne doivent pas être versionnés ni déployés.
"""

from __future__ import annotations

import argparse
import re
import subprocess  # nosec B404
from collections.abc import Callable, Iterable, Sequence
from dataclasses import dataclass
from pathlib import Path

_EXCLUDED_PARTS = frozenset({".git", ".venv", ".worktrees", "__pycache__", ".."})
_EXCLUDED_NAMES = frozenset({".env", ".secrets.baseline", "GUIDE_DEV_PYTHON.md"})
_EXCLUDED_TOP_LEVEL = frozenset({"tests"})
_ALLOWLIST_MARKER = "secret-check: allow"
_UNQUOTED_CONFIG_SUFFIXES = frozenset({".conf", ".ini", ".toml", ".yaml", ".yml"})
_TEXT_SUFFIXES = frozenset(
    {".conf", ".ini", ".json", ".md", ".py", ".service", ".timer", ".toml", ".txt", ".yaml", ".yml"}
)
_LITERAL_SECRET_RE = re.compile(
    r"(?ix)\b(?:api[_-]?key|access[_-]?token|auth(?:orization)?|icalsecurise|password|secret|token)"
    r"\s*[:=]\s*['\"][^'\"\r\n]{8,}['\"]"
)
_UNQUOTED_SECRET_RE = re.compile(
    r"(?ix)\b(?:api[_-]?key|access[_-]?token|auth(?:orization)?|icalsecurise|password|secret|token)"
    r"\s*[:=]\s*[a-z0-9][a-z0-9._~+/-]{7,}"
)
_URL_SECRET_RE = re.compile(
    r"(?ix)[?&](?:api[_-]?key|access[_-]?token|auth(?:orization)?|icalsecurise|password|secret|token)"
    r"=([^&#\s]{8,})"
)


@dataclass(frozen=True)
class SecretFinding:
    """Représente un motif sensible détecté sans exposer sa valeur.

    :ivar path: Chemin relatif du fichier concerné.
    :ivar line: Numéro de ligne du motif.
    :ivar rule: Règle ayant détecté le motif.
    """

    path: Path
    line: int
    rule: str


CommandRunner = Callable[..., subprocess.CompletedProcess[str]]


def _is_candidate(path: Path) -> bool:
    """Indique si un chemin peut être analysé comme fichier texte.

    :param path: Chemin relatif au dépôt.
    :return: ``True`` lorsque le fichier est textuel et non exclu.
    :rtype: bool
    """
    return (
        not path.is_absolute()
        and path.name not in _EXCLUDED_NAMES
        and path.parts[0] not in _EXCLUDED_TOP_LEVEL
        and not any(part in _EXCLUDED_PARTS for part in path.parts)
        and path.suffix in _TEXT_SUFFIXES
    )


def _repository_files(root: Path) -> list[Path]:
    """Liste les fichiers textuels présents dans le dépôt de travail.

    Les tests et la spécification historique ne font pas partie de l'artefact
    déployé : leurs sentinelles et exemples intentionnels ne doivent donc pas
    bloquer le déploiement.

    :param root: Racine du dépôt à analyser.
    :return: Chemins relatifs triés des fichiers analysables.
    :rtype: list[Path]
    """
    return sorted(
        path.relative_to(root)
        for path in root.rglob("*")
        if path.is_file() and _is_candidate(path.relative_to(root))
    )


def _staged_files(root: Path, runner: CommandRunner) -> list[Path]:
    """Retourne les fichiers ajoutés ou modifiés actuellement indexés.

    :param root: Racine du dépôt Git.
    :param runner: Exécuteur de sous-processus injectable pour les tests.
    :return: Chemins relatifs triés des fichiers indexés analysables.
    :rtype: list[Path]
    :raises RuntimeError: Si Git ne peut pas fournir les fichiers indexés.
    """
    result = runner(
        ["git", "diff", "--cached", "--name-only", "-z", "--diff-filter=ACMR"],
        cwd=root,
        capture_output=True,
        text=True,
        check=False,
    )
    if result.returncode != 0:
        raise RuntimeError("Impossible de lister les fichiers Git indexés") from None
    paths = [Path(value) for value in result.stdout.split("\0") if value]
    return sorted(path for path in paths if _is_candidate(path))


def find_secrets(root: Path, files: Iterable[Path]) -> list[SecretFinding]:
    """Détecte les motifs de secrets littéraux dans les fichiers désignés.

    Les lignes explicitement marquées ``secret-check: allow`` sont exclues :
    cette échappatoire doit rester locale à une fixture ou un exemple contrôlé.

    :param root: Racine du dépôt analysé.
    :param files: Chemins relatifs à inspecter.
    :return: Résultats triés par chemin, ligne et règle.
    :rtype: list[SecretFinding]
    """
    findings: list[SecretFinding] = []
    for relative_path in files:
        path = root / relative_path
        try:
            content = path.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            continue
        for number, line in enumerate(content.splitlines(), start=1):
            if _ALLOWLIST_MARKER in line:
                continue
            is_literal_secret = _LITERAL_SECRET_RE.search(line) or (
                relative_path.suffix in _UNQUOTED_CONFIG_SUFFIXES
                and _UNQUOTED_SECRET_RE.search(line)
            )
            if is_literal_secret:
                findings.append(SecretFinding(relative_path, number, "affectation-litterale"))
            if _URL_SECRET_RE.search(line):
                findings.append(SecretFinding(relative_path, number, "parametre-url"))
    return sorted(findings, key=lambda finding: (str(finding.path), finding.line, finding.rule))


def _parse_arguments(arguments: Sequence[str] | None = None) -> argparse.Namespace:
    """Analyse les options de vérification.

    :param arguments: Arguments explicites, ou ``None`` pour ceux du processus.
    :return: Options validées.
    :rtype: argparse.Namespace
    """
    parser = argparse.ArgumentParser(description="Vérifie les secrets avant déploiement.")
    parser.add_argument(
        "--staged",
        action="store_true",
        help="Analyse uniquement les fichiers ajoutés ou modifiés dans l'index Git.",
    )
    return parser.parse_args(arguments)


def main(
    arguments: Sequence[str] | None = None,
    *,
    root: Path | None = None,
    runner: CommandRunner = subprocess.run,
) -> int:
    """Exécute la vérification de secrets et retourne un code de sortie.

    :param arguments: Arguments de ligne de commande.
    :param root: Racine à analyser ; le dépôt du script par défaut.
    :param runner: Exécuteur Git injectable pour les tests.
    :return: ``0`` sans motif, ``1`` si un motif est trouvé, ``2`` si le contrôle échoue.
    :rtype: int
    """
    parsed_arguments = _parse_arguments(arguments)
    repository_root = root or Path(__file__).resolve().parents[1]
    try:
        files = (
            _staged_files(repository_root, runner)
            if parsed_arguments.staged
            else _repository_files(repository_root)
        )
    except RuntimeError as error:
        print(f"ERREUR: {error}")
        return 2
    findings = find_secrets(repository_root, files)
    if not findings:
        print("OK: aucun secret littéral détecté.")
        return 0
    for finding in findings:
        print(f"ECHEC: {finding.path}:{finding.line} ({finding.rule})")
    return 1


if __name__ == "__main__":
    raise SystemExit(main())