Pipeline CI/CD sécurisé : guide pratique Python + GitHub Actions

En 2024, l'attaque xz-utils a démontré qu'un mainteneur malveillant pouvait injecter une backdoor dans un projet open source critique. La seule défense ? Une chaîne de build traçable et vérifiable où chaque étape est attestée.

Ce guide vous accompagne pas à pas pour construire un pipeline CI/CD hautement sécurisé pour un projet Python. À la fin, vous aurez :

• Un dépôt GitHub avec branch protection et Scorecard
• Des dépendances épinglées avec hash et auditées automatiquement
• Une image Docker avec attestation SLSA L3 et SBOM
• Des artefacts signés avec Sigstore (keyless)
• Des vérifications automatiques à chaque étape

Objectif pédagogique

Ce guide synthétise les concepts des autres guides de la section supply chain. Si un concept n'est pas clair, suivez les liens vers les guides détaillés.

Ce que vous allez apprendre

• Configurer un dépôt GitHub durci : rulesets, signature des commits, Scorecard
• Épingler les dépendances Python par hash et les actions par SHA de commit
• Construire une image Docker multi-stage avec un utilisateur non-root
• Générer une attestation SLSA L3 et un SBOM à chaque release
• Signer l'image avec Cosign en mode keyless et vérifier sa provenance
• Centraliser la visibilité supply chain de tous vos services avec GUAC

Ce qu'on va construire

Une application Python minimaliste (API FastAPI) avec un pipeline qui :

1. Analyse le code : linting, tests, SAST avec attestations in-toto
2. Audite les dépendances : vulnérabilités, intégrité (hash pinning)
3. Construit l'image Docker avec attestation SLSA L3
4. Génère le SBOM (liste des composants) en SPDX et CycloneDX
5. Signe l'image avec Cosign (keyless via Sigstore)
6. Publie sur GHCR avec provenance vérifiable
7. Ingère dans GUAC pour visibilité globale sur les dépendances
8. Évalue avec Scorecard les bonnes pratiques du dépôt

┌─────────────────────────────────────────────────────────────────────────────┐
│                            GitHub Actions                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐                 │
│  │  Lint    │ → │  Test    │ → │  SAST    │ → │  Audit   │                 │
│  │  ruff    │   │  pytest  │   │  bandit  │   │pip-audit │                 │
│  │ + in-toto│   │ + in-toto│   │          │   │          │                 │
│  └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘                 │
│       │              │              │              │                        │
│       └──────────────┴──────────────┴──────────────┘                        │
│                              ↓                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                        Build & Attest                                 │  │
│  │  Docker build → SLSA L3 attestation → SBOM (Syft) → Cosign sign      │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                              ↓                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                   GitHub Container Registry                           │  │
│  │  ghcr.io/owner/app@sha256:...                                        │  │
│  │  ├── attestation SLSA L3 (in-toto format)                            │  │
│  │  ├── signature Cosign (Sigstore keyless)                             │  │
│  │  ├── SBOM SPDX + CycloneDX                                           │  │
│  │  └── links in-toto (lint, test, audit, build)                        │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                              ↓                                              │
│  ┌────────────────────────┐     ┌────────────────────────┐                 │
│  │         GUAC           │     │       Scorecard        │                 │
│  │  Graphe dépendances    │     │  Score sécurité repo   │                 │
│  │  + certifier OSV       │     │  Branch protection ✓   │                 │
│  │  → alertes CVE 0-day   │     │  CODEOWNERS ✓          │                 │
│  └────────────────────────┘     └────────────────────────┘                 │
└─────────────────────────────────────────────────────────────────────────────┘

Prérequis

Avant de commencer, assurez-vous d'avoir les Connaissances préalables recommandées :

SLSA : les niveaux de maturité

Sigstore : signature keyless

SBOM : inventaire des composants

Scorecard : évaluer un dépôt

Si c'est le cas, allons-y ! Commençons pas installer les outils localement.

Élément	Version minimale	Vérification	Installation
Git	2.34+	git --version	Guide Git
Python	3.11+	python --version	Guide pyenv
Docker	24+	docker --version	Guide Docker
Gitsign	0.10+	gitsign version	Guide Gitsign
Cosign	2.0+	cosign version	Guide Cosign
Syft	1.0+	syft version	Guide Syft
Trivy	0.50+	trivy version	Guide Trivy
slsa-verifier	2.0+	slsa-verifier version	GitHub

Glissez pour voir

Git 2.34+ requis pour Gitsign

Gitsign utilise le format de signature x509 qui nécessite Git 2.34 ou supérieur. Vérifiez votre version avec git --version et mettez à jour si nécessaire.

Étape 1 : Créer le dépôt GitHub

1.1 Initialiser le dépôt

La première étape est de créer un dépôt GitHub correctement configuré. Les choix faits ici impactent directement votre score Scorecard.

1. Créer le dépôt : Allez sur github.com/new

2. Configurer les paramètres de base :

   Paramètre	Valeur recommandée	Pourquoi
   Repository name	secure-python-pipeline	Nom explicite
   Description	"API Python avec pipeline CI/CD sécurisé"	Aide au référencement
   Visibility	Public	Scorecard fonctionne mieux sur les dépôts publics
   Add README	✅ Oui	Point d'entrée pour les contributeurs
   Add .gitignore	Python	Exclut __pycache__, .venv, .pytest_cache
   License	MIT ou Apache 2.0	Clarté juridique, check License Scorecard

   Glissez pour voir

3. Cliquer sur "Create repository"

Pourquoi un dépôt public ?

Scorecard peut analyser les dépôts privés, mais certains checks (comme Signed-Releases) fonctionnent mieux sur les dépôts publics car ils vérifient les signatures dans les logs de transparence Rekor (publics par défaut).

Si vous devez rester en privé, vous pouvez quand même atteindre un bon score, mais vous devrez configurer Sigstore en mode privé.

Cloner le dépôt et créer une branche de travail :

# Cloner le dépôt (remplacez VOTRE_USER par votre username GitHub)
git clone https://github.com/VOTRE_USER/secure-python-pipeline.git
cd secure-python-pipeline

# Créer immédiatement une branche de travail
# (les rulesets bloqueront les commits directs sur main)
git checkout -b setup

# Vérifier que tout est en place
ls -la
# Vous devriez voir : .git/ .gitignore LICENSE README.md

Pourquoi une branche ?

Les rulesets que nous configurons à l'étape suivante interdisent les commits directs sur main. Tout le code sera développé dans la branche setup, puis mergé via une Pull Request à l'étape 5.

Configurer Git localement (si pas déjà fait) :

# Configurer votre identité (utilisée pour les commits)
git config user.name "Votre Nom"
git config user.email "votre.email@example.com"

Configurer Gitsign pour la signature keyless

Pour ce guide, nous utilisons Gitsign, la signature keyless avec Sigstore. Contrairement à GPG ou SSH, vous n'avez aucune clé à gérer : vous vous authentifiez avec votre compte GitHub et Sigstore s'occupe du reste.

Installer Gitsign :

# macOS
brew install sigstore/tap/gitsign

# Linux (téléchargement direct)
GITSIGN_VERSION=$(curl -s https://api.github.com/repos/sigstore/gitsign/releases/latest | grep tag_name | cut -d '"' -f 4)
curl -LO "https://github.com/sigstore/gitsign/releases/download/${GITSIGN_VERSION}/gitsign_${GITSIGN_VERSION#v}_linux_amd64"
chmod +x gitsign_*_linux_amd64
sudo mv gitsign_*_linux_amd64 /usr/local/bin/gitsign

# Vérifier l'installation
gitsign version

Configurer Git pour utiliser Gitsign (dans ce projet uniquement) :

# Activer la signature automatique des commits
git config --local commit.gpgsign true

# Utiliser le format x509 (requis pour Gitsign)
git config --local gpg.format x509

# Spécifier Gitsign comme programme de signature
git config --local gpg.x509.program gitsign

Tester la signature :

# Créer un fichier de test
echo "test" > test.txt
git add test.txt
git commit -m "test: vérification signature gitsign"

Un navigateur s'ouvre pour vous authentifier avec votre compte GitHub (ou Google/Microsoft). Après authentification :

• Fulcio délivre un certificat éphémère (~10 minutes)
• Votre commit est signé avec ce certificat
• La signature est enregistrée dans Rekor (log de transparence public)

Vérifier la signature :

git log --show-signature -1

Sortie attendue :

commit abc123...
gitsign: Signature made Mon Dec 30 10:00:00 2024 CET
gitsign: Good signature from "votre-email@example.com"
gitsign: WARNING: no matching key found in keyring
    This is expected for keyless signing

WARNING: no matching key found

Ce warning est normal avec Gitsign. Contrairement à GPG, il n'y a pas de clé locale, la vérification se fait via Rekor. Pour vérifier proprement :

# Remplacez par l'email de votre compte GitHub
gitsign verify --certificate-identity=VOTRE_EMAIL_GITHUB \
  --certificate-oidc-issuer=https://github.com/login/oauth HEAD

Comment trouver votre identity ? Si vous vous trompez d'email, le message d'erreur vous indique la bonne valeur :

got subjects [votre-vrai-email@example.com] with issuer https://github.com/login/oauth

L'email entre crochets (got subjects [...]) est celui à utiliser.

Configuration globale vs locale

Nous utilisons --local pour configurer Gitsign uniquement dans ce projet. Pour l'activer sur tous vos projets :

git config --global commit.gpgsign true
git config --global gpg.format x509
git config --global gpg.x509.program gitsign

Guide complet Gitsign Installation, configuration avancée et vérification

1.2 Configurer les rulesets de branche

Les rulesets (ensembles de règles) remplacent les anciennes "branch protection rules". Ils permettent de définir des contraintes sur les branches et tags. C'est une exigence SLSA Source L2 pour protéger l'intégrité du code source.

Rulesets vs Branch Protection Rules

Les rulesets offrent plusieurs avantages par rapport aux anciennes règles :

• Visibilité : tout utilisateur avec accès lecture peut voir les rulesets actifs
• Statuts : Active, Disabled (pas besoin de supprimer pour désactiver)
• Layering : plusieurs rulesets peuvent s'appliquer, le plus restrictif gagne
• Métadonnées : contraintes sur les messages de commit, emails, etc.

1. Accéder aux paramètres :

   • Allez sur votre dépôt GitHub
   • Cliquez sur Settings (onglet en haut à droite)
   • Dans la sidebar gauche, section "Code and automation", cliquez sur Rules → Rulesets

2. Créer un nouveau ruleset :

   • Cliquez sur New ruleset → New branch ruleset
   • Ruleset name : main-protection (nom descriptif)
   • Enforcement status : Active (appliqué immédiatement)

3. Configurer le ciblage (Target branches) :

   • Cliquez sur Add target → Include default branch
   • Cela cible automatiquement main (ou master selon votre config)

   Patterns fnmatch

   Vous pouvez cibler plusieurs branches avec des patterns :

   • release/**/* : toutes les branches sous release/
   • feature-* : toutes les branches commençant par feature-

4. Configurer les règles de base :

   Dans la section Rules, activez ces protections :

   Règle	Action	Effet	Check Scorecard
   Restrict deletions	✅ Cocher	Empêche la suppression de la branche	,
   Require linear history	✅ Cocher	Force squash ou rebase (pas de merge commits)	,
   Block force pushes	✅ Cocher (défaut)	Empêche git push --force	,

   Glissez pour voir

5. Configurer "Require a pull request before merging" :

   Cette règle est essentielle pour le check Code-Review de Scorecard.

   • ✅ Cocher Require a pull request before merging
   • Cliquer sur la flèche pour déplier les options :

   Option	Valeur	Explication
   Required approvals	1	Nombre minimum de reviewers (augmentez pour les projets critiques)
   Dismiss stale pull request approvals when new commits are pushed	✅	Invalide les approvals si le code change après review
   Require review from Code Owners	✅	Force l'approbation par les CODEOWNERS
   Require approval of the most recent reviewable push	✅	L'auteur du dernier push ne peut pas auto-approuver
   Require conversation resolution before merging	✅	Tous les commentaires doivent être résolus

   Glissez pour voir

6. Configurer "Require status checks to pass before merging" :

   Cette règle garantit que la CI passe avant tout merge.

   • ✅ Cocher Require status checks to pass
   • ✅ Cocher Require branches to be up to date before merging (mode strict)
   • Cliquer sur Add checks et ajouter les jobs de votre CI :
     • lint (job Ruff)
     • test (job Pytest)
     • sast (job Bandit)
     • audit (job pip-audit)

   Status checks introuvables

   Les status checks n'apparaissent qu'après leur première exécution. Créez d'abord vos workflows (étape 4), poussez-les, puis revenez configurer les required status checks.

7. Configurer "Require signed commits" :

   • ✅ Cocher Require signed commits
   • Seuls les commits signés seront acceptés

   GitHub reconnaît trois types de signatures :

   Méthode	Badge "Verified"	Gestion de clés
   GPG	✅ Natif	Clé à créer et protéger
   SSH	✅ Natif	Utilise votre clé SSH
   Gitsign	⚠️ Via Rekor	Aucune (keyless)

   Glissez pour voir

   Gitsign et le badge Verified

   Les commits signés avec Gitsign apparaissent comme "Unverified" sur GitHub car GitHub ne vérifie pas encore les signatures Sigstore nativement.

   Ce n'est pas un problème : la signature reste vérifiable via Rekor et la commande gitsign verify. Pour les projets supply chain security, la vérifiabilité dans Rekor est plus importante que le badge cosmétique.

   Si le badge "Verified" est critique pour vous, ajoutez votre clé publique GPG ou SSH dans GitHub (Settings → SSH and GPG keys).

8. Configurer le bypass (optionnel mais recommandé) :

   Dans la section Bypass list, vous pouvez autoriser certains rôles à contourner les règles en cas d'urgence :

   • Cliquez sur Add bypass → sélectionnez Repository admin
   • Choisissez For pull requests only (pas de push direct, mais peut merger sans attendre)

   ⚠️ Attention : n'abusez pas des bypass, ils réduisent votre score Scorecard.

9. Sauvegarder :

   • Cliquez sur Create en bas de la page
   • Le ruleset est immédiatement actif

Récapitulatif des règles configurées :

┌─────────────────────────────────────────────────────────────────────────┐
│                    Ruleset "main-protection"                            │
├─────────────────────────────────────────────────────────────────────────┤
│  Target: default branch (main)                                          │
│  Status: Active                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│  ✅ Restrict deletions                                                  │
│  ✅ Require linear history                                              │
│  ✅ Block force pushes                                                  │
│  ✅ Require pull request (1 approval, dismiss stale, CODEOWNERS)        │
│  ✅ Require status checks (lint, test, sast, audit + up-to-date)        │
│  ✅ Require signed commits                                              │
├─────────────────────────────────────────────────────────────────────────┤
│  Bypass: Repository admin (pull requests only)                          │
└─────────────────────────────────────────────────────────────────────────┘

Premiers commits

La branch protection s'applique immédiatement. Pour le setup initial, vous avez deux options :

1. Désactiver temporairement : passez le ruleset en "Disabled", faites vos commits initiaux, puis réactivez-le
2. Travailler en PR dès le début : créez une branche setup, commitez tout dedans, puis ouvrez une PR vers main

L'option 2 est recommandée car elle vous force à valider votre CI dès le départ.

1.3 Activer Scorecard

OpenSSF Scorecard analyse automatiquement votre dépôt et attribue un score de sécurité.

Scorecard fonctionne via une GitHub Action, pas d'app à installer. Le workflow scorecard.yml sera ajouté à l'étape 4. Une fois en place :

• Les résultats apparaissent dans l'onglet Security > Code scanning alerts
• Votre score est visible sur scorecard.dev (dépôts publics)

1.4 Fichiers pour maximiser le score Scorecard

Scorecard évalue plusieurs critères. Pour atteindre un score élevé (8+/10), vous devez ajouter ces fichiers.

CODEOWNERS (Code-Review check)

Le fichier CODEOWNERS définit qui doit approuver les modifications sur chaque partie du code. C'est essentiel pour le check Code-Review.

.github/CODEOWNERS :

# Propriétaires par défaut pour tout le dépôt
* @VOTRE_USER

# Sécurité : équipe sécurité doit approuver les workflows
.github/workflows/ @VOTRE_USER
.github/CODEOWNERS @VOTRE_USER

# Configuration Docker
Dockerfile @VOTRE_USER
.dockerignore @VOTRE_USER

# Dépendances : revue obligatoire
requirements*.txt @VOTRE_USER
pyproject.toml @VOTRE_USER

CODEOWNERS et branch protection

Pour que CODEOWNERS soit effectif, activez "Require review from Code Owners" dans les règles de protection de branche.

SECURITY.md (Security-Policy check)

Le fichier SECURITY.md décrit comment signaler les vulnérabilités. C'est obligatoire pour le check Security-Policy.

SECURITY.md :

# Politique de sécurité

## Versions supportées

| Version | Supportée |
| ------- | --------- |
| 1.x     | ✅        |
| < 1.0   | ❌        |

## Signaler une vulnérabilité

**Ne créez PAS d'issue publique pour les vulnérabilités de sécurité.**

Utilisez plutôt le [signalement privé GitHub](../../security/advisories/new)
ou envoyez un email à : `security@votre-domaine.com`

### Informations à inclure

- Description de la vulnérabilité
- Étapes pour reproduire
- Version affectée
- Impact potentiel

### Délai de réponse

- Accusé de réception : 48h
- Première évaluation : 7 jours
- Correctif (selon sévérité) : 30-90 jours

## Pratiques de sécurité

Ce projet applique :

- Analyse statique (Bandit, Ruff)
- Audit des dépendances (pip-audit)
- Signature des images (Cosign/Sigstore)
- Attestation SLSA L3
- Scan de vulnérabilités (Trivy)

Templates d'issues (bonnes pratiques)

Les templates structurent les signalements et améliorent la qualité des issues.

.github/ISSUE_TEMPLATE/bug_report.yml :

name: "🐛 Bug Report"
description: "Signaler un bug ou un comportement inattendu"
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: |
        Merci de prendre le temps de signaler ce bug !

  - type: textarea
    id: description
    attributes:
      label: "Description du bug"
      description: "Décrivez clairement le problème rencontré"
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: "Étapes pour reproduire"
      description: "Comment reproduire le bug ?"
      placeholder: |
        1. Aller sur '...'
        2. Cliquer sur '...'
        3. Voir l'erreur
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: "Comportement attendu"
      description: "Que devrait-il se passer ?"
    validations:
      required: true

  - type: input
    id: version
    attributes:
      label: "Version"
      description: "Quelle version utilisez-vous ?"
      placeholder: "v1.0.0"
    validations:
      required: true

  - type: dropdown
    id: os
    attributes:
      label: "Système d'exploitation"
      options:
        - Linux
        - macOS
        - Windows
        - Autre
    validations:
      required: true

.github/ISSUE_TEMPLATE/feature_request.yml :

name: "✨ Feature Request"
description: "Proposer une nouvelle fonctionnalité"
labels: ["enhancement"]
body:
  - type: markdown
    attributes:
      value: |
        Merci de proposer une amélioration !

  - type: textarea
    id: problem
    attributes:
      label: "Problème à résoudre"
      description: "Quel problème cette fonctionnalité résoudrait-elle ?"
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: "Solution proposée"
      description: "Décrivez votre idée de solution"
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: "Alternatives considérées"
      description: "Avez-vous envisagé d'autres approches ?"

  - type: textarea
    id: context
    attributes:
      label: "Contexte additionnel"
      description: "Captures d'écran, liens, exemples..."

.github/ISSUE_TEMPLATE/config.yml :

blank_issues_enabled: false
contact_links:
  - name: "💬 Discussions"
    url: https://github.com/VOTRE_USER/secure-python-pipeline/discussions
    about: "Questions générales et discussions"
  - name: "📖 Documentation"
    url: https://github.com/VOTRE_USER/secure-python-pipeline#readme
    about: "Consultez la documentation avant de poser une question"

Template de Pull Request

Le template PR guide les contributeurs et assure des descriptions complètes.

.github/PULL_REQUEST_TEMPLATE.md :

## Description

<!-- Décrivez vos changements en détail -->

## Type de changement

- [ ] 🐛 Bug fix (changement non-breaking qui corrige un problème)
- [ ] ✨ Nouvelle fonctionnalité (changement non-breaking qui ajoute une fonction)
- [ ] 💥 Breaking change (changement qui casse la compatibilité)
- [ ] 📝 Documentation (mise à jour de la doc uniquement)
- [ ] 🧪 Tests (ajout ou modification de tests)
- [ ] 🔧 Configuration (CI, dépendances, config)

## Checklist

- [ ] Mon code suit les conventions du projet
- [ ] J'ai testé mes changements localement
- [ ] J'ai ajouté des tests si nécessaire
- [ ] J'ai mis à jour la documentation si nécessaire
- [ ] Mes commits suivent les [Conventional Commits](https://conventionalcommits.org)

## Tests effectués

<!-- Décrivez les tests que vous avez effectués -->

## Captures d'écran (si applicable)

<!-- Ajoutez des captures d'écran pour les changements visuels -->

## Issues liées

<!-- Utilisez "Fixes #123" ou "Closes #123" pour lier automatiquement -->

CONTRIBUTING.md (Maintained check)

CONTRIBUTING.md :

# Guide de contribution

Merci de votre intérêt pour ce projet !

## Prérequis

- Python 3.11+
- Docker 24+
- Git

## Installation locale

```bash
git clone https://github.com/VOTRE_USER/secure-python-pipeline.git
cd secure-python-pipeline
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
```

## Lancer les tests

```bash
pytest
ruff check src/ tests/
bandit -r src/
```

## Processus de contribution

1. Forkez le projet
2. Créez une branche (`git checkout -b feature/ma-feature`)
3. Commitez vos changements (`git commit -m 'feat: ajoute ma feature'`)
4. Poussez la branche (`git push origin feature/ma-feature`)
5. Ouvrez une Pull Request

## Conventions

- **Commits** : suivez [Conventional Commits](https://conventionalcommits.org)
- **Code** : formaté avec Ruff
- **Tests** : couverture minimale 80%

## Code de conduite

Ce projet suit le [Contributor Covenant](https://www.contributor-covenant.org/).
Soyez respectueux et inclusif.

README.md (Documentation check)

Un bon README est essentiel pour le check Maintained et pour accueillir les contributeurs. Il doit inclure les badges de sécurité.

README.md :

# Secure Python Pipeline

[![CI](https://github.com/VOTRE_USER/secure-python-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/VOTRE_USER/secure-python-pipeline/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/VOTRE_USER/secure-python-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/VOTRE_USER/secure-python-pipeline)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/XXXXX/badge)](https://www.bestpractices.dev/projects/XXXXX)

API Python de démonstration avec pipeline CI/CD hautement sécurisé.

## 🔒 Sécurité

Ce projet implémente les bonnes pratiques de supply chain security :

| Protection | Outil | Status |
|------------|-------|--------|
| Attestation SLSA L3 | GitHub Attestations | ✅ |
| Signature d'image | Cosign (Sigstore) | ✅ |
| SBOM | Syft (SPDX + CycloneDX) | ✅ |
| Scan vulnérabilités | Trivy, pip-audit | ✅ |
| Analyse statique | Bandit, Ruff | ✅ |
| Dépendances épinglées | Hash pinning | ✅ |

### Vérifier l'image

```bash
# Vérifier la signature Cosign
cosign verify \
  --certificate-identity-regexp="https://github.com/VOTRE_USER/secure-python-pipeline" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ghcr.io/VOTRE_USER/secure-python-pipeline:latest

# Vérifier l'attestation SLSA
gh attestation verify oci://ghcr.io/VOTRE_USER/secure-python-pipeline:latest \
  --owner VOTRE_USER
```

## 🚀 Démarrage rapide

### Prérequis

- Python 3.11+
- Docker 24+

### Installation locale

```bash
git clone
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Lancer l'application

```bash
uvicorn app.main:app --reload
```

L'API est disponible sur http://localhost:8000

### Avec Docker

```bash
docker pull ghcr.io/VOTRE_USER/secure-python-pipeline:latest
docker run -p 8000:8000 ghcr.io/VOTRE_USER/secure-python-pipeline:latest
```

## 📚 API

| Endpoint | Méthode | Description |
|----------|---------|-------------|
| `/` | GET | Message de bienvenue |
| `/health` | GET | Health check pour Kubernetes |

## 🧪 Tests

```bash
# Installer les dépendances de dev
pip install -r requirements-dev.txt

# Lancer les tests
pytest

# Linting
ruff check src/ tests/

# Analyse de sécurité
bandit -r src/
```

## 📝 Licence

Sous licence MIT - voir le fichier `LICENSE` à la racine du dépôt.

## 🤝 Contribuer

Voir le fichier `CONTRIBUTING.md` à la racine du dépôt.

## 🔐 Signaler une vulnérabilité

Voir le fichier `SECURITY.md` à la racine du dépôt.

Récapitulatif des checks Scorecard

Ce tableau récapitule les checks Scorecard couverts par les fichiers et la configuration ajoutés jusqu'ici, et signale ceux qui restent optionnels.

Check	Fichier/Config	Impact
Branch-Protection	Règles de branche	✅ Déjà fait
Code-Review	CODEOWNERS + branch rules	✅
Security-Policy	SECURITY.md	✅
Dependency-Update-Tool	dependabot.yml	✅ Déjà fait
Pinned-Dependencies	SHA dans workflows	✅ Déjà fait
Token-Permissions	permissions: read	✅ Déjà fait
SAST	Bandit dans CI	✅ Déjà fait
Signed-Releases	Cosign signature	✅ Déjà fait
Vulnerabilities	Trivy, pip-audit	✅ Déjà fait
Maintained	Commits récents, CONTRIBUTING	✅
License	LICENSE file	✅ Déjà fait
Dangerous-Workflow	Pas de pull_request_target	✅ Déjà fait
Fuzzing	OSS-Fuzz (optionnel)	⚠️ Avancé
CII-Best-Practices	Badge OpenSSF	⚠️ Optionnel

Glissez pour voir

Score cible

Avec tous ces fichiers, vous devriez atteindre un score 8-9/10. Les checks Fuzzing et CII-Best-Practices sont optionnels et plus complexes à mettre en place.

Étape 2 : Structure du projet Python

2.1 Arborescence cible

Voici la structure finale du projet :

• Répertoire.github/

  • CODEOWNERS
  • RépertoireISSUE_TEMPLATE/

    • bug_report.yml
    • feature_request.yml
    • config.yml
  • PULL_REQUEST_TEMPLATE.md
  • dependabot.yml
  • Répertoireworkflows/

    • ci.yml
    • release.yml
    • scorecard.yml
• Répertoiresrc/

  • Répertoireapp/

    • __init__.py
    • main.py
• Répertoiretests/

  • __init__.py
  • test_main.py
• .dockerignore
• .gitignore ← CRITIQUE : doit contenir .venv/
• .python-version
• CONTRIBUTING.md
• Dockerfile
• pyproject.toml
• requirements.txt
• requirements-dev.txt
• SECURITY.md

Le .gitignore est non négociable

Le fichier .gitignore doit être créé avant le premier commit et doit contenir .venv/. Sans cela, vous risquez de commiter votre environnement virtuel, ce qui fera échouer 3 checks Scorecard et fera chuter votre score de ~9/10 à ~7/10.

Voir la section 2.4 ci-dessous pour le contenu exact du .gitignore.

2.2 Créer l'application Python

src/app/main.py : une API FastAPI minimaliste :

"""API de démonstration pour pipeline sécurisé."""
from fastapi import FastAPI

app = FastAPI(
    title="Secure Python Pipeline Demo",
    version="1.0.0",
    description="Application de démonstration avec supply chain sécurisée",
)


@app.get("/")
async def root() -> dict[str, str]:
    """Endpoint racine."""
    return {"message": "Hello, Secure World!"}


@app.get("/health")
async def health() -> dict[str, str]:
    """Endpoint de santé pour les probes Kubernetes."""
    return {"status": "healthy"}

src/app/__init__.py : fichier vide pour le package :

"""Package principal de l'application."""

tests/test_main.py : tests unitaires :

"""Tests pour l'API."""
from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)


def test_root() -> None:
    """Test de l'endpoint racine."""
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, Secure World!"}


def test_health() -> None:
    """Test de l'endpoint de santé."""
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json()["status"] == "healthy"

tests/__init__.py : fichier vide :

"""Package de tests."""

2.3 Configurer les dépendances avec hash

Les dépendances épinglées avec hash garantissent l'intégrité. Même si PyPI était compromis, pip refuserait d'installer un fichier modifié.

pyproject.toml : configuration du projet :

[project]
name = "secure-python-pipeline"
version = "1.0.0"
description = "Démonstration pipeline CI/CD sécurisé"
requires-python = ">=3.11"
license = {text = "MIT"}

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
target-version = "py311"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I", "S", "B", "C4", "UP"]

[tool.ruff.lint.per-file-ignores]
# S101 = assert (normal dans les tests pytest)
"tests/**/*.py" = ["S101"]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]

[tool.bandit]
exclude_dirs = ["tests", ".venv"]

requirements.txt, À GÉNÉRER, ne pas copier-coller :

NE PAS copier-coller ce fichier

Les hashs ci-dessous sont obsolètes. Vous devez les régénérer avec pip-compile. Si vous copiez ce fichier tel quel, vous aurez une erreur THESE PACKAGES DO NOT MATCH THE HASHES.

# 1. Installer pip-tools
pip install pip-tools

# 2. Créer requirements.in (fichier source sans hash)
cat > requirements.in << EOF
fastapi
uvicorn
EOF

# 3. Générer requirements.txt avec TOUTES les dépendances et hashs
pip-compile --generate-hashes requirements.in -o requirements.txt

Le fichier sera long

pip-compile génère un requirements.txt avec toutes les dépendances transitives (anyio, idna, sniffio, typing-extensions, etc.) et tous leurs hashs. Le fichier fera plusieurs centaines de lignes, c'est normal.

Exemple de début du fichier généré :

# This file is autogenerated by pip-compile with Python 3.11
# by the following command:
#
#    pip-compile --generate-hashes requirements.in
#
annotated-types==0.7.0 \
    --hash=sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc879daf1b616d8de89816493b8fd5c794f47 \
    --hash=sha256:aff07c09a53a08bc8cfcffe6d35c79b16d9bd46c9f8a963c74de09b9fb89ef34
    # via pydantic
anyio==4.7.0 \
    --hash=sha256:5aadc6a1bbb7cdb0bede386cac5e2940f5e2ff3aa20277e991cf028e0585ce94 \
    --hash=sha256:f75253795a87df48568485fd18cdd2a3fa5c4f7c5be8e5e36637733fce06fed6
    # via
    #   httpcore
    #   starlette
# ... (beaucoup d'autres dépendances)

Ne modifiez pas ce fichier manuellement. Utilisez toujours pip-compile.

Exemple de sortie (extrait, le fichier complet fait 200-300 lignes) :

# This file is autogenerated by pip-compile with Python 3.11
annotated-types==0.7.0 \
    --hash=sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc879daf1b616d8de89816493b8fd5c794f47
    # via pydantic
anyio==4.7.0 \
    --hash=sha256:5aadc6a1bbb7cdb0bede386cac5e2940f5e2ff3aa20277e991cf028e0585ce94
    # via starlette
# ... (50+ autres packages avec leurs hashs)
fastapi==0.115.6 \
    --hash=sha256:... (hash du jour)
# ... etc

Ne pas copier cet exemple

Ce n'est qu'un aperçu. Utilisez le fichier généré par pip-compile sur votre machine, il contiendra les hashs corrects et complets.

requirements-dev.txt : dépendances de développement :

# Outils de qualité
ruff>=0.8.0
bandit>=1.7.0
pip-audit>=2.7.0

# Tests
pytest>=8.0.0
pytest-cov>=6.0.0  # Plugin coverage pour pytest
httpx>=0.27.0  # Pour TestClient FastAPI

# Build
pip-tools>=7.4.0

2.4 Créer le .gitignore

Critique : Le dossier .venv/ ne doit jamais être committé. Il contient des binaires spécifiques à votre système et fait échouer les checks Scorecard.

.gitignore :

# Python runtime
__pycache__/
*.py[cod]
*$py.class
*.so
.Python

# Environnements virtuels (CRITIQUE - ne jamais commiter)
.venv/
venv/
ENV/
env/

# Outils Python
.pytest_cache/
.ruff_cache/
.mypy_cache/
htmlcov/
.coverage
.tox/
dist/
build/
*.egg-info/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

Si vous avez déjà committé .venv/

Si vous avez déjà committé .venv/ par erreur :

# Créer le .gitignore avec le contenu ci-dessus
cat > .gitignore << 'EOF'
.venv/
# ... (copier le contenu complet ci-dessus)
EOF

# Supprimer .venv/ de Git (mais pas du disque)
git rm -r --cached .venv/

# Commiter
git add .gitignore
git commit -m "fix: remove venv from git and add proper gitignore"

Pourquoi c'est critique ? Scorecard tente de scanner tous les fichiers, y compris ceux dans .venv/. Les binaires Python dans .venv/bin/ causent des erreurs path escapes from parent, ce qui fait échouer les checks Binary-Artifacts, Pinned-Dependencies et SAST.

2.5 Créer le Dockerfile multi-stage

Un Dockerfile multi-stage réduit la surface d'attaque en n'incluant que le strict nécessaire dans l'image finale. L'image de base est épinglée par digest @sha256, comme les actions par SHA : c'est ce qui garantit un build reproductible même si le tag python:3.11-slim est republié sur le registre.

Dockerfile :

# syntax=docker/dockerfile:1

# =============================================================================
# Stage 1 : Builder - Installer les dépendances dans un venv
# =============================================================================
FROM python:3.11-slim@sha256:a3ab0b966bc4e91546a033e22093cb840908979487a9fc0e6e38295747e49ac0 AS builder

# Éviter les fichiers .pyc et activer le mode unbuffered
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Copier uniquement les fichiers de dépendances d'abord (cache Docker)
COPY requirements.txt .

# Créer un virtualenv et installer les dépendances
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# --require-hashes force la vérification des hash
RUN pip install --no-cache-dir --require-hashes -r requirements.txt

# =============================================================================
# Stage 2 : Production - Image minimale
# =============================================================================
FROM python:3.11-slim@sha256:a3ab0b966bc4e91546a033e22093cb840908979487a9fc0e6e38295747e49ac0 AS production

# Labels OCI pour la traçabilité (utilisés par Syft pour le SBOM)
LABEL org.opencontainers.image.source="https://github.com/VOTRE_USER/secure-python-pipeline"
LABEL org.opencontainers.image.description="API Python avec supply chain sécurisée"
LABEL org.opencontainers.image.licenses="MIT"

# Créer un utilisateur non-root
RUN groupadd --gid 1000 appgroup && \
    useradd --uid 1000 --gid 1000 --shell /bin/false appuser

WORKDIR /app

# Copier le virtualenv depuis le builder
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Copier le code source
COPY --chown=appuser:appgroup src/ ./src/

# Passer en utilisateur non-root
USER appuser

# Port exposé (documentation)
EXPOSE 8000

# Healthcheck intégré
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1

# Commande de démarrage
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

2.6 Créer le .dockerignore

.dockerignore : exclure les fichiers inutiles du contexte Docker :

# Git
.git
.gitignore

# Python
__pycache__
*.pyc
*.pyo
.venv
.pytest_cache
.ruff_cache
.mypy_cache

# IDE
.vscode
.idea

# Tests et docs
tests/
docs/
*.md

# CI/CD
.github/

Étape 3 : Configurer Dependabot

Dependabot crée automatiquement des PR pour mettre à jour vos dépendances quand des vulnérabilités sont découvertes.

.github/dependabot.yml :

version: 2
updates:
  # Dépendances Python
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
    commit-message:
      prefix: "chore(deps):"
    labels:
      - "dependencies"
      - "python"
    # Grouper les mises à jour mineures
    groups:
      python-minor:
        patterns:
          - "*"
        update-types:
          - "minor"
          - "patch"

  # Actions GitHub
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
    commit-message:
      prefix: "chore(ci):"
    labels:
      - "dependencies"
      - "github-actions"

  # Dockerfile
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "chore(docker):"

Auto-merge des PRs Dependabot

Option 1 : Merger manuellement avec gh CLI

# Lister toutes les PRs Dependabot
gh pr list --author "app/dependabot"

# Merger toutes les PRs Dependabot qui passent la CI
gh pr list --author "app/dependabot" --json number,title,statusCheckRollup \
  --jq '.[] | select(.statusCheckRollup[]?.conclusion=="SUCCESS") | .number' \
  | xargs -I {} gh pr merge {} --admin --squash --delete-branch

# Ou merger une seule PR spécifique
gh pr merge 5 --admin --squash --delete-branch

Option 2 : Workflow auto-merge (recommandé)

Pour auto-merger les PRs Dependabot qui passent la CI, ajoutez ce workflow :

.github/workflows/dependabot-automerge.yml :

name: Dependabot Auto-merge

on: pull_request

# Aucun droit par défaut : le job demande le strict nécessaire
permissions: {}

jobs:
  automerge:
    runs-on: ubuntu-24.04
    # On vérifie l'auteur de la PR, pas github.actor (usurpable lors d'un re-run)
    if: github.event.pull_request.user.login == 'dependabot[bot]'
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Enable auto-merge
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr merge --auto --squash "$PR_URL"

Les PRs Dependabot seront automatiquement mergées dès que la CI passe.

⚠️ Important : cette approche fonctionne uniquement si vous n'exigez pas d'approbation pour les PRs, ou si vous configurez le bypass pour Dependabot dans les rulesets.

Étape 4 : Créer les workflows GitHub Actions

4.1 Workflow CI (tests et qualité)

Ce workflow s'exécute sur chaque PR et commit sur main. Il vérifie la qualité du code avant le merge.

.github/workflows/ci.yml :

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Aucun droit par défaut : chaque job demande le strict nécessaire
permissions: {}

jobs:
  # ===========================================================================
  # Job 1 : Lint avec Ruff
  # ===========================================================================
  lint:
    name: Lint (Ruff)
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: "3.11"

      - name: Install Ruff
        run: pip install ruff==0.8.4

      - name: Run Ruff formatter check
        run: ruff format --check src/ tests/

      - name: Run Ruff linter
        run: ruff check src/ tests/

  # ===========================================================================
  # Job 2 : Tests avec Pytest
  # ===========================================================================
  test:
    name: Test (Pytest)
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install --require-hashes -r requirements.txt
          pip install --require-hashes -r requirements-dev.txt

      - name: Run tests with coverage
        run: pytest --cov=src/app --cov-report=xml

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
        with:
          files: coverage.xml
          fail_ci_if_error: false

  # ===========================================================================
  # Job 3 : SAST avec Bandit
  # ===========================================================================
  sast:
    name: SAST (Bandit)
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: "3.11"

      - name: Install Bandit
        run: pip install bandit==1.8.0

      - name: Run Bandit
        run: bandit -r src/ -f json -o bandit-report.json || true

      - name: Upload Bandit report
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: bandit-report
          path: bandit-report.json

  # ===========================================================================
  # Job 4 : Audit des dépendances
  # ===========================================================================
  audit:
    name: Dependency Audit
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: "3.11"

      - name: Install pip-audit
        run: pip install pip-audit==2.7.3

      - name: Run pip-audit
        run: pip-audit -r requirements.txt --strict

  # ===========================================================================
  # Job 5 : Build Docker (sans push, juste vérification)
  # ===========================================================================
  build-check:
    name: Docker Build Check
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

      - name: Build image (no push)
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
        with:
          context: .
          push: false
          tags: test-build:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Actions épinglées par SHA

Remarquez que chaque action est épinglée par son SHA de commit complet (@8e8c483db84b4bee98b60c0593521ed34d9990e8) plutôt que par tag (@v6), suivi d'un commentaire de version pour la lisibilité. C'est une exigence SLSA Build L3 : les dépendances de build doivent être immuables. Le guide Épingler par SHA détaille la méthode.

4.2 Workflow Release (build, sign, publish)

Ce workflow se déclenche sur les tags v*. Il construit l'image avec attestation SLSA, génère le SBOM et signe avec Cosign.

.github/workflows/release.yml :

name: Release

on:
  push:
    tags:
      - "v*"

# Aucun droit par défaut : chaque job demande le strict nécessaire
permissions: {}

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  # ===========================================================================
  # Job 1 : Build, Attest, Sign, Push
  # ===========================================================================
  build-and-push:
    name: Build, Attest & Push
    runs-on: ubuntu-24.04

    # Permissions spécifiques au job
    permissions:
      contents: read
      packages: write          # Pour push vers GHCR
      id-token: write          # Pour Sigstore OIDC
      attestations: write      # Pour GitHub Attestations

    outputs:
      digest: ${{ steps.build.outputs.digest }}
      image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata for Docker
        id: meta
        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=semver,pattern=v{{version}}

      - name: Build and push image
        id: build
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          provenance: true  # Génère l'attestation SLSA
          sbom: true        # Génère le SBOM avec Syft

      # =========================================================================
      # Attestation GitHub (SLSA Build L3)
      # =========================================================================
      - name: Generate SLSA attestation
        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest: ${{ steps.build.outputs.digest }}
          push-to-registry: true

      # =========================================================================
      # Signature Cosign (keyless via Sigstore)
      # =========================================================================
      - name: Install Cosign
        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0

      - name: Sign image with Cosign
        env:
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          IMAGE_REF="${REGISTRY}/${IMAGE_NAME}@${DIGEST}"
          echo "Signing: $IMAGE_REF"
          cosign sign --yes "$IMAGE_REF"
          echo "Verifying signature..."
          cosign verify \
            --certificate-identity-regexp="https://github.com/${GITHUB_REPOSITORY}" \
            --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
            "$IMAGE_REF"

  # ===========================================================================
  # Job 2 : Générer SBOM détaillé avec Syft
  # ===========================================================================
  sbom:
    name: Generate SBOM
    runs-on: ubuntu-24.04
    needs: build-and-push
    permissions:
      contents: read
      packages: write          # Pour attacher le SBOM à l'image dans GHCR

    steps:
      - name: Log in to GitHub Container Registry
        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Install Syft
        uses: anchore/sbom-action/download-syft@a930d0ac434e3182448fe678398ba5713717112a # v0.21.0

      - name: Generate SBOM (SPDX)
        env:
          IMAGE_REF: ${{ needs.build-and-push.outputs.image }}@${{ needs.build-and-push.outputs.digest }}
        run: syft "$IMAGE_REF" -o spdx-json=sbom-spdx.json

      - name: Generate SBOM (CycloneDX)
        env:
          IMAGE_REF: ${{ needs.build-and-push.outputs.image }}@${{ needs.build-and-push.outputs.digest }}
        run: syft "$IMAGE_REF" -o cyclonedx-json=sbom-cyclonedx.json

      - name: Upload SBOM artifacts
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: sbom
          path: |
            sbom-spdx.json
            sbom-cyclonedx.json

      # Attacher le SBOM à l'image avec Cosign
      - name: Install Cosign
        uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0

      - name: Attach SBOM to image
        env:
          IMAGE_REF: ${{ needs.build-and-push.outputs.image }}@${{ needs.build-and-push.outputs.digest }}
        run: cosign attach sbom --sbom sbom-spdx.json "$IMAGE_REF"

  # ===========================================================================
  # Job 3 : Scanner les vulnérabilités avec Trivy
  # ===========================================================================
  scan:
    name: Vulnerability Scan
    runs-on: ubuntu-24.04
    needs: build-and-push
    permissions:
      packages: read            # Pour récupérer l'image depuis GHCR
      security-events: write    # Pour publier le rapport SARIF

    steps:
      - name: Run Trivy scanner
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: "${{ needs.build-and-push.outputs.image }}@${{ needs.build-and-push.outputs.digest }}"
          format: "sarif"
          output: "trivy-results.sarif"
          severity: "CRITICAL,HIGH"

      - name: Upload Trivy results to GitHub Security
        uses: github/codeql-action/upload-sarif@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
        with:
          sarif_file: "trivy-results.sarif"

4.3 Workflow CodeQL (analyse de sécurité statique)

Ce workflow analyse automatiquement votre code Python pour détecter des vulnérabilités de sécurité et des erreurs de qualité avec CodeQL.

.github/workflows/codeql.yml :

name: CodeQL

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  schedule:
    # Analyser tous les lundis à 6h
    - cron: '0 6 * * 1'

# Aucun droit par défaut : le job demande le strict nécessaire
permissions: {}

jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-24.04

    permissions:
      security-events: write
      actions: read
      contents: read

    strategy:
      fail-fast: false
      matrix:
        language: [ 'python' ]

    steps:
      - name: Checkout repository
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Initialize CodeQL
        uses: github/codeql-action/init@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
        with:
          languages: ${{ matrix.language }}
          queries: security-extended,security-and-quality

      - name: Autobuild
        uses: github/codeql-action/autobuild@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
        with:
          category: "/language:${{ matrix.language }}"

Queries étendues

queries: security-extended,security-and-quality active les requêtes avancées de CodeQL, détectant plus de problèmes que l'analyse standard. Cela augmente légèrement le temps d'analyse mais améliore la couverture sécurité.

4.4 Workflow Scorecard

Ce workflow évalue les pratiques de sécurité de votre dépôt et publie les résultats sur OpenSSF Scorecard.

.github/workflows/scorecard.yml :

name: Scorecard

on:
  # Exécution hebdomadaire
  schedule:
    - cron: "0 6 * * 1"
  # Exécution sur push main (pour mise à jour rapide)
  push:
    branches: [main]

# Aucun droit par défaut : le job demande le strict nécessaire
permissions: {}

jobs:
  analysis:
    name: Scorecard Analysis
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      security-events: write
      id-token: write  # Pour publier sur scorecard.dev

    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Run Scorecard
        uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
        with:
          results_file: results.sarif
          results_format: sarif
          publish_results: true

      - name: Upload results to GitHub Security
        uses: github/codeql-action/upload-sarif@5d4e8d1aca955e8d8589aabd499c5cae939e33c7 # v4.31.9
        with:
          sarif_file: results.sarif

4.5 Workflow de vérification SLSA

Ce workflow vérifie automatiquement les attestations SLSA de vos releases, assurant qu'elles sont valides et n'ont pas été compromises.

.github/workflows/verify-slsa.yml :

name: SLSA Verification

on:
  schedule:
    # Vérifier toutes les nuits
    - cron: '0 2 * * *'
  workflow_dispatch:

# Aucun droit par défaut : le job demande le strict nécessaire
permissions: {}

jobs:
  verify:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Install slsa-verifier
        run: |
          curl -LO https://github.com/slsa-framework/slsa-verifier/releases/latest/download/slsa-verifier-linux-amd64
          chmod +x slsa-verifier-linux-amd64
          sudo mv slsa-verifier-linux-amd64 /usr/local/bin/slsa-verifier

      - name: Get latest tag
        id: latest
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          LATEST_TAG=$(gh api "repos/$GITHUB_REPOSITORY/tags" --jq '.[0].name')
          echo "tag=$LATEST_TAG" >> "$GITHUB_OUTPUT"

      - name: Get image digest
        id: digest
        env:
          RELEASE_TAG: ${{ steps.latest.outputs.tag }}
        run: |
          DIGEST=$(docker pull "ghcr.io/$GITHUB_REPOSITORY:$RELEASE_TAG" 2>&1 | grep "Digest:" | cut -d' ' -f2)
          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"

      - name: Verify SLSA with GitHub Attestations
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          IMAGE_DIGEST: ${{ steps.digest.outputs.digest }}
        run: |
          gh attestation verify "oci://ghcr.io/$GITHUB_REPOSITORY@$IMAGE_DIGEST" \
            --owner "$GITHUB_REPOSITORY_OWNER"

      - name: Report status
        if: always()
        env:
          JOB_STATUS: ${{ job.status }}
          RELEASE_TAG: ${{ steps.latest.outputs.tag }}
        run: |
          if [ "$JOB_STATUS" = "success" ]; then
            echo "Vérification SLSA réussie pour $RELEASE_TAG"
          else
            echo "Vérification SLSA échouée pour $RELEASE_TAG"
            exit 1
          fi

Vérification continue

Ce workflow s'exécute quotidiennement pour détecter toute modification ou compromission des attestations SLSA après publication. C'est une couche de sécurité supplémentaire qui vérifie l'intégrité de vos releases dans le temps.

Étape 5 : Premier déploiement

Vous avez travaillé dans la branche setup. Les rulesets bloquent les commits directs sur main, c'est normal, c'est ce qu'on veut ! Nous allons merger via une Pull Request en utilisant GitHub CLI.

1. Installer les dépendances :

   # Créer un environnement virtuel Python
   python -m venv .venv
   source .venv/bin/activate  # Linux/macOS
   # .venv\Scripts\activate   # Windows
   
   # Mettre à jour pip (important pour éviter CVE-2025-8869)
   pip install --upgrade pip
   
   # Installer les dépendances de production et développement
   pip install -r requirements.txt -r requirements-dev.txt

   CVE pip

   Si pip-audit vous alerte sur une CVE dans pip, mettez-le à jour :

   pip install --upgrade pip
   pip-audit  # Devrait être propre maintenant

   Dépendances dev

   Le fichier requirements-dev.txt contient ruff, pytest, bandit, pip-audit, tous les outils nécessaires pour les tests locaux.

2. Tester localement avant de push :

   # Formatter le code automatiquement
   ruff format src/ tests/
   
   # Vérifier le linting
   ruff check src/ tests/
   
   # Lancer les tests
   pytest tests/ -v
   
   # Vérifier les vulnérabilités des dépendances
   pip-audit
   
   # Scanner le code avec Bandit
   bandit -r src/ -c pyproject.toml

   Corriger les erreurs avant de continuer

   Si ruff check ou pytest échouent, corrigez les problèmes avant de commiter. La CI rejettera la PR sinon.

   Ordre recommandé :

   1. ruff format → formatter automatiquement
   2. ruff check --fix → corriger les problèmes auto-fixables
   3. Corriger manuellement les erreurs restantes
   4. Relancer ruff check → doit être ✓ propre

   ruff check src/ tests/ --fix
   ruff format src/ tests/

3. Commiter tous les fichiers dans la branche setup :

   # Vérifiez que vous êtes sur la branche setup
   git branch --show-current
   # Doit afficher : setup
   
   # ⚠️ CRITIQUE : Vérifier que .venv/ n'est PAS tracké
   git status --ignored
   # .venv/ doit apparaître sous "Ignored files"
   # Si .venv/ apparaît sous "Untracked" ou "Changes", c'est un problème !
   
   # Vérifier que .gitignore existe et contient .venv/
   grep -q "^\.venv/" .gitignore && echo "✓ .gitignore OK" || echo "❌ .gitignore manquant"
   
   git add .
   git commit -m "feat: initial secure pipeline setup"
   git push origin setup

   Si .venv/ est tracké

   Si git status montre .venv/ dans les fichiers à commiter :

   # Supprimer .venv/ du staging
   git reset .venv/
   
   # Vérifier que .gitignore contient .venv/
   echo ".venv/" >> .gitignore
   
   # Re-commiter
   git add .gitignore
   git commit -m "feat: initial secure pipeline setup"

   Pourquoi c'est critique ? Commiter .venv/ fait échouer 3 checks Scorecard (Binary-Artifacts, Pinned-Dependencies, SAST) et fait chuter votre score de ~9/10 à ~7/10.

4. Créer une Pull Request avec gh :

   gh pr create \
     --title "feat: initial secure pipeline setup" \
     --body "Setup initial du pipeline CI/CD sécurisé :
   
   - Configuration Gitsign (signature keyless)
   - Projet Python FastAPI avec tests
   - Workflows CI, Release et Scorecard
   - Fichiers Scorecard (CODEOWNERS, SECURITY.md, templates)
   - Dockerfile multi-stage sécurisé" \
     --base main

5. Suivre l'exécution de la CI :

   # Ouvrir la PR dans le navigateur pour voir les checks
   gh pr view --web
   
   # Ou suivre le statut en CLI
   gh pr checks --watch

6. Merger la PR (une fois les checks verts) :

   gh pr merge --squash --delete-branch

   Erreur : At least 1 approving review is required

   Si vous obtenez cette erreur, c'est que vous êtes seul sur le projet et ne pouvez pas vous auto-approuver.

   Solution rapide :

   gh pr merge --admin --squash --delete-branch

   Le flag --admin bypass les protections. Vous pouvez aussi modifier temporairement le ruleset pour mettre 0 approbations requises.

   Erreur : Commits must have verified signatures

   Ce problème vient de Gitsign : les commits sont signés (vérifiables via Rekor) mais GitHub les affiche comme "Unverified" car GitHub ne reconnaît que GPG/SSH, pas Sigstore.

   Solutions :

   Option 1 : Bypass admin (recommandé pour projets solo)

   gh pr merge --admin --squash --delete-branch

   Option 2 : Configurer le bypass permanent

   1. GitHub → Settings → Rules → Rulesets → main-protection
   2. Section "Bypass list" → Add bypass
   3. Sélectionnez "Repository admin" ou votre username
   4. Save changes

   Désormais vos PRs pourront être mergées même avec commits "Unverified".

   Option 3 : Désactiver la vérification de signature

   1. GitHub → Settings → Rules → Rulesets → main-protection
   2. Décochez "Require signed commits"
   3. Save changes

   Note : Vos commits sont signés et sécurisés (vérifiables avec gitsign verify), c'est juste que GitHub ne les reconnaît pas encore comme "Verified". C'est une limitation actuelle de GitHub vis-à-vis de Sigstore.

7. Mettre à jour votre copie locale :

   git checkout main
   git reset --hard origin/main

   Pourquoi reset au lieu de pull ?

   Avec squash merge, tous vos commits locaux ont été écrasés en un seul commit sur main. Un git pull classique échouerait car les historiques ont divergé. Le reset --hard force la synchronisation avec origin/main.

8. Créer le premier tag :

   git tag v1.0.0
   git push origin v1.0.0

9. Vérifier le workflow Release :

   # Suivre l'exécution du workflow Release
   gh run watch

10. Vérifier Scorecard : Après quelques minutes, votre score apparaît sur scorecard.dev

Pourquoi cette méthode ?

En passant par une PR dès le premier déploiement, vous :

• Validez que vos workflows fonctionnent correctement
• Respectez le processus que vous appliquerez pour tous les futurs changements
• Confirmez que les rulesets sont bien configurés

C'est la méthode "dogfooding", vous utilisez vos propres outils.

5.1 Débugger un score Scorecard bas

Si votre score Scorecard est inférieur à 8/10, exécutez Scorecard localement pour identifier les problèmes :

# Installer Scorecard CLI
go install github.com/ossf/scorecard/v5/cmd/scorecard@latest

# Scanner votre repo
scorecard --repo=github.com/VOTRE_USER/secure-python-pipeline --show-details

Problèmes courants et solutions

Check	Score	Cause	Solution
Token-Permissions	0/10	permissions: read-all ou permissions: {}	Définir permissions: contents: read explicitement au niveau global de chaque workflow
Binary-Artifacts	Erreur	.venv/ committé	Ajouter .venv/ au .gitignore et supprimer du repo
Pinned-Dependencies	Erreur	.venv/ committé	Même solution
SAST	Erreur	.venv/ committé	Même solution
Fuzzing	0/10	Pas de fuzzing	Optionnel, voir section fuzzing ci-dessous

Glissez pour voir

Fixer Token-Permissions :

Tous vos workflows doivent avoir permissions minimales :

# ❌ Mauvais - aucun bloc permissions : le jeton hérite des droits par défaut
# (pas de permissions: déclaré)

# ❌ Mauvais - read-all accorde la lecture sur toutes les portées
permissions: read-all

# ✅ Bon - explicite et minimal
permissions:
  contents: read

Fixer Binary-Artifacts / Pinned-Dependencies / SAST :

Ces erreurs viennent du même problème : .venv/ ne doit jamais être committé.

# 1. Ajouter au .gitignore
echo ".venv/" >> .gitignore

# 2. Supprimer du repo
git rm -r --cached .venv/
git commit -m "fix: remove venv from git"
git push

# 3. Re-scanner
scorecard --repo=github.com/VOTRE_USER/secure-python-pipeline --show-details

Exemple de .gitignore complet :

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
.pytest_cache/
.ruff_cache/
.mypy_cache/
dist/
build/
*.egg-info/
.venv/
venv/
ENV/
env/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

Étape 6 : Vérifier les artefacts

Maintenant que l'image est publiée, vérifions que tout est correct.

6.1 Vérifier la signature Cosign

La signature Cosign prouve que l'image vient bien de votre workflow de release. La commande cosign verify contrôle le certificat keyless contre l'identité GitHub attendue : si l'image a été substituée, la vérification échoue.

# Définir les variables
export IMAGE=ghcr.io/VOTRE_USER/secure-python-pipeline
export TAG=v1.0.0

# Vérifier la signature
cosign verify \
  --certificate-identity-regexp="https://github.com/VOTRE_USER/secure-python-pipeline" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ${IMAGE}:${TAG}

Sortie attendue :

Verification for ghcr.io/VOTRE_USER/secure-python-pipeline:v1.0.0 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified
  - The code-signing certificate was verified using trusted certificate authority certificates

[{"critical":{"identity":{"docker-reference":"ghcr.io/..."},...}]

Erreur : no signatures found

Si vous obtenez Error: no signatures found, cela signifie que l'image n'a pas été signée. Causes possibles :

1. Le workflow Release n'a pas été déclenché

# Vérifier les runs du workflow
gh run list --workflow=release.yml --limit 5

# Si aucun run, vérifier que le tag commence par 'v'
git tag  # Doit afficher v1.0.0, pas 1.0.0

2. Le workflow a échoué

# Voir les logs du dernier run
gh run view --log

# Chercher les erreurs dans la step "Sign image"

3. L'image n'existe pas

# Vérifier que l'image a été poussée
crane ls ${IMAGE}

# Ou essayer de la pull
docker pull ${IMAGE}:${TAG}

4. Mauvais tag/digest

# Lister tous les tags disponibles
crane ls ${IMAGE}

# Essayer avec le digest
DIGEST=$(crane digest ${IMAGE}:${TAG})
cosign verify \
  --certificate-identity-regexp="https://github.com/VOTRE_USER/secure-python-pipeline" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ${IMAGE}@${DIGEST}

Solution : Re-déclencher le workflow

# Supprimer et recréer le tag
git tag -d v1.0.0
git push --delete origin v1.0.0
git tag v1.0.0
git push origin v1.0.0

# Suivre l'exécution
gh run watch

6.2 Vérifier l'attestation SLSA

L'attestation SLSA va plus loin que la signature : elle relie l'image au commit source et au workflow qui l'a construite. La commande gh attestation verify valide cette provenance auprès de l'API GitHub.

# Récupérer le digest
DIGEST=$(crane digest ${IMAGE}:${TAG})

# Vérifier l'attestation SLSA
gh attestation verify oci://${IMAGE}@${DIGEST} \
  --owner VOTRE_USER

Sortie attendue :

✓ Verification succeeded!

sha256:abc123... was attested by a]Sigstore entry with ID 12345678

6.3 Inspecter le SBOM

Le SBOM attaché à l'image liste l'ensemble de ses composants. L'inspecter confirme qu'il a bien été généré et permet de repérer une dépendance inattendue avant de déployer.

# Télécharger le SBOM attaché
cosign download sbom ${IMAGE}:${TAG} > sbom.json

# Voir le contenu (jq pour formater)
cat sbom.json | jq '.packages[:5]'

6.4 Scanner localement avec Trivy

Le scan exécuté en CI peut dater de plusieurs heures. Relancer Trivy en local donne l'état des vulnérabilités connues au moment précis où vous contrôlez l'image, juste avant un déploiement.

# Scanner l'image pour vulnérabilités
trivy image ${IMAGE}:${TAG}

# Scanner uniquement les CRITICAL et HIGH
trivy image --severity CRITICAL,HIGH ${IMAGE}:${TAG}

Étape 7 : Intégrer GUAC pour la visibilité globale

Vous avez maintenant des SBOM et des attestations pour chaque image. Mais si vous gérez 50 services, comment répondre rapidement à : "Quels services utilisent la dépendance vulnérable CVE-2024-XXXX ?"

GUAC (Graph for Understanding Artifact Composition) agrège tous vos SBOM et attestations dans un graphe de connaissances interrogeable. C'est le centre de contrôle de votre supply chain.

7.1 Déployer GUAC localement

Pour ce tutoriel, nous déployons GUAC en local. En production, vous le déploierez sur un serveur dédié ou dans Kubernetes.

# Cloner le dépôt GUAC
git clone https://github.com/guacsec/guac.git
cd guac

# Démarrer tous les services avec Docker Compose
docker compose up -d

# Vérifier que les services tournent
docker compose ps

Services disponibles :

Service	Port	Usage
GraphQL API	8080	Requêtes programmatiques
Visualizer	3000	Interface web d'exploration

Glissez pour voir

7.2 Ajouter l'ingestion GUAC au workflow Release

Ajoutez ce job dans .github/workflows/release.yml après le job sbom :

  # ===========================================================================
  # Job 4 : Ingérer dans GUAC
  # ===========================================================================
  guac-ingest:
    name: Ingest to GUAC
    runs-on: ubuntu-24.04
    needs: [build-and-push, sbom]
    permissions:
      contents: read
    # Uniquement si vous avez un GUAC hébergé (décommentez et adaptez l'URL)
    # if: ${{ vars.GUAC_API_URL != '' }}

    steps:
      - name: Download SBOM artifacts
        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
        with:
          name: sbom

      - name: Install guacone CLI
        run: |
          curl -sSL https://github.com/guacsec/guac/releases/latest/download/guacone-linux-amd64 \
            -o /usr/local/bin/guacone
          chmod +x /usr/local/bin/guacone

      - name: Ingest SBOM to GUAC
        env:
          GUAC_API_URL: ${{ vars.GUAC_API_URL || 'http://localhost:8080/query' }}
        run: |
          # Ingérer le SBOM SPDX
          guacone collect files sbom-spdx.json --gql-addr "$GUAC_API_URL"

          # Ingérer le SBOM CycloneDX
          guacone collect files sbom-cyclonedx.json --gql-addr "$GUAC_API_URL"

      - name: Ingest image from OCI registry
        env:
          GUAC_API_URL: ${{ vars.GUAC_API_URL || 'http://localhost:8080/query' }}
          IMAGE_REF: ${{ needs.build-and-push.outputs.image }}@${{ needs.build-and-push.outputs.digest }}
        run: |
          # Ingérer directement depuis le registry (récupère SBOM + attestations attachés)
          guacone collect oci "$IMAGE_REF" --gql-addr "$GUAC_API_URL"

GUAC hébergé

Pour que ce job fonctionne en CI, vous devez avoir une instance GUAC accessible depuis GitHub Actions. Définissez GUAC_API_URL dans les variables du dépôt (Settings → Secrets and variables → Variables).

En attendant, vous pouvez exécuter l'ingestion manuellement depuis votre poste.

7.3 Ingérer manuellement les artefacts

Si vous n'avez pas de GUAC hébergé, ingérez manuellement après chaque release :

# Variables
export IMAGE=ghcr.io/VOTRE_USER/secure-python-pipeline
export TAG=v1.0.0
export GUAC_API=http://localhost:8080/query

# Télécharger le SBOM depuis les artifacts GitHub
gh run download --name sbom

# Ingérer les SBOM
guacone collect files sbom-spdx.json --gql-addr ${GUAC_API}
guacone collect files sbom-cyclonedx.json --gql-addr ${GUAC_API}

# Ingérer depuis le registry OCI (récupère aussi les attestations)
guacone collect oci ${IMAGE}:${TAG} --gql-addr ${GUAC_API}

7.4 Requêter GUAC

Via l'interface web : Ouvrez http://localhost:3000 et explorez le graphe.

Via GraphQL : Trouvez tous les packages vulnérables dans votre image :

curl -s http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { CertifyVuln(certifyVulnSpec: {}) { package { namespaces { names { name } } } vulnerability { vulnerabilityIDs { vulnerabilityID } } } }"
  }' | jq '.data.CertifyVuln[] | {package: .package.namespaces[0].names[0].name, cve: .vulnerability.vulnerabilityIDs[0].vulnerabilityID}'

Exemple de sortie :

{"package": "requests", "cve": "CVE-2023-32681"}
{"package": "starlette", "cve": "CVE-2024-12345"}

7.5 Cas d'usage concrets avec GUAC

Question	Requête GUAC
"Quelles images utilisent log4j ?"	Rechercher IsDependencyOf avec package log4j
"Cette CVE nous affecte-t-elle ?"	CertifyVuln filtré par CVE ID
"D'où vient cette dépendance ?"	Traverser HasSourceAt depuis le package
"Cette image a-t-elle un SBOM ?"	Vérifier HasSBOM pour l'artifact
"Provenance SLSA de cette image ?"	Requêter HasSlsa

Glissez pour voir

Alertes automatiques

Combiné avec le certifier OSV de GUAC, vous pouvez créer des alertes automatiques quand une nouvelle CVE affecte un de vos composants. GUAC surveille en continu et enrichit le graphe.

Étape 8 : (Optionnel) Ajouter le fuzzing

Le fuzzing teste votre application avec des entrées aléatoires pour détecter des bugs inattendus (crashes, comportements anormaux). C'est optionnel pour un projet simple, mais améliore votre score Scorecard.

Pourquoi fuzzer ?

Le fuzzing découvre :

• Crashes : entrées qui font planter l'application
• Exceptions non gérées : cas limites oubliés
• Problèmes de sécurité : buffer overflows, injections, parsing errors

Solution rapide : Atheris (Python fuzzing)

Atheris est un fuzzer Python basé sur libFuzzer.

tests/fuzz_main.py :

"""Fuzzing de l'API avec Atheris."""
import atheris
import sys

with atheris.instrument_imports():
    from fastapi.testclient import TestClient
    from app.main import app


def test_one_input(data: bytes) -> None:
    """Fuzz test pour l'API."""
    client = TestClient(app)
    try:
        # Tester l'endpoint racine avec des données aléatoires
        client.get("/", params={"input": data.decode("utf-8", errors="ignore")})
    except (ValueError, UnicodeDecodeError):
        # Erreurs attendues - pas un bug
        pass


if __name__ == "__main__":
    atheris.Setup(sys.argv, test_one_input)
    atheris.Fuzz()

Ajouter à requirements-dev.txt :

atheris>=2.3.0

Ajouter à .github/workflows/ci.yml :

  # ===========================================================================
  # Job 6 : Fuzzing (optionnel)
  # ===========================================================================
  fuzz:
    name: Fuzzing
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          pip install -r requirements.txt -r requirements-dev.txt

      - name: Run fuzzing (60 seconds)
        run: |
          python tests/fuzz_main.py -max_total_time=60

Tester localement :

# Installer atheris
pip install atheris

# Lancer le fuzzing pendant 10 secondes
python tests/fuzz_main.py -max_total_time=10

Sortie attendue :

INFO: Running with entropic power schedule (0xFF, 100).
INFO: Seed: 1234567890
INFO: -max_len is not provided; libFuzzer will guess a good value based on the corpus.
#2      INITED exec/s: 0 rss: 45Mb
#1024   pulse  exec/s: 512 rss: 48Mb
...
Done 50000 runs in 10 second(s)

Si le fuzzing trouve un crash, Atheris l'affichera avec l'entrée qui a causé le problème.

Alternative : OSS-Fuzz (projets critiques)

Pour les projets open source largement utilisés, vous pouvez rejoindre OSS-Fuzz, le fuzzing continu de Google :

1. Suivre le guide d'intégration
2. Google exécute le fuzzing 24/7 sur vos commits
3. Vous recevez des rapports de bugs privés

Critères OSS-Fuzz :

• Projet open source avec > 10k utilisateurs ou dépendance critique
• Responsable de sécurité actif (SECURITY.md + réponses rapides)
• CI/CD configuré

Impact sur Scorecard

Le check Fuzzing passe à 10/10 si :

• Votre repo est sur OSS-Fuzz, ou
• Vous avez un workflow CI qui exécute du fuzzing, ou
• Vous mentionnez le fuzzing dans SECURITY.md

Pour un projet simple, ne pas avoir de fuzzing n'est pas bloquant. Mais pour les projets critiques (parseurs, crypto, API publiques), c'est fortement recommandé.

Étape 9 : Politique in-toto pour la chaîne complète

Jusqu'ici, nous avons des attestations SLSA qui prouvent que le build a eu lieu sur GitHub Actions. Mais comment garantir que toutes les étapes obligatoires (lint, test, scan) ont bien été exécutées avant la release ?

in-toto permet de définir un layout (politique) qui décrit les étapes requises. À chaque étape, un link (attestation) est généré. À la fin, la vérification compare les links au layout : si une étape manque ou si les hachages ne correspondent pas, l'artefact est rejeté.

9.1 Pourquoi aller au-delà de SLSA ?

Ce que SLSA prouve	Ce qu'in-toto ajoute
Le build vient de GitHub Actions	Toutes les étapes définies ont été exécutées
Le commit source est identifié	Les fichiers en entrée/sortie correspondent
Le builder est authentifié	Une politique signée définit les règles

Glissez pour voir

Scénario d'attaque bloqué : un attaquant compromet le workflow et commente l'étape de scan de vulnérabilités. Avec SLSA seul, l'image est quand même signée. Avec in-toto, la vérification échoue car le link "scan" est manquant.

9.2 Installer in-toto

# Installation via pip
pip install in-toto

# Vérifier l'installation
in-toto-run --version
in-toto-verify --version

9.3 Créer un layout (politique)

Le layout définit les étapes obligatoires et les clés autorisées. Créez un fichier layout.json :

layout.json

{
  "_type": "layout",
  "expires": "2026-12-31T23:59:59Z",
  "readme": "Layout pour secure-python-pipeline",
  "keys": {},
  "steps": [
    {
      "name": "lint",
      "expected_command": [],
      "threshold": 1,
      "pubkeys": [],
      "expected_materials": [
        ["MATCH", "*.py", "WITH", "PRODUCTS", "FROM", "lint"]
      ],
      "expected_products": []
    },
    {
      "name": "test",
      "expected_command": [],
      "threshold": 1,
      "pubkeys": [],
      "expected_materials": [
        ["MATCH", "*.py", "WITH", "PRODUCTS", "FROM", "lint"]
      ],
      "expected_products": []
    },
    {
      "name": "audit",
      "expected_command": [],
      "threshold": 1,
      "pubkeys": [],
      "expected_materials": [],
      "expected_products": []
    },
    {
      "name": "build",
      "expected_command": [],
      "threshold": 1,
      "pubkeys": [],
      "expected_materials": [
        ["MATCH", "*.py", "WITH", "PRODUCTS", "FROM", "test"],
        ["MATCH", "Dockerfile", "WITH", "PRODUCTS", "FROM", "test"]
      ],
      "expected_products": [
        ["CREATE", "image.tar"]
      ]
    }
  ],
  "inspect": []
}

Clés et signatures

Dans cet exemple simplifié, les pubkeys sont vides car nous utilisons GitHub Actions comme source de confiance. En production, vous signeriez le layout avec une clé privée et chaque step avec la clé du runner.

9.4 Générer des links dans le workflow

Modifiez votre workflow CI pour générer un link à chaque étape :

.github/workflows/ci.yml

jobs:
  lint:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Setup Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: '3.11'

      - name: Install in-toto
        run: pip install in-toto

      - name: Run lint with in-toto
        run: |
          in-toto-run \
            --step-name lint \
            --products src/*.py \
            --no-command \
            -- ruff check src/

      - name: Upload link
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: link-lint
          path: lint.link

  test:
    needs: lint
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
        with:
          persist-credentials: false

      - name: Setup Python
        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install in-toto pytest

      - name: Download lint link
        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
        with:
          name: link-lint

      - name: Run tests with in-toto
        run: |
          in-toto-run \
            --step-name test \
            --materials src/*.py \
            --products src/*.py \
            --no-command \
            -- pytest tests/

      - name: Upload link
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: link-test
          path: test.link

9.5 Vérifier la chaîne complète

Après le build, vérifiez que tous les links correspondent au layout :

# Télécharger tous les links
gh run download --name link-lint
gh run download --name link-test
gh run download --name link-audit
gh run download --name link-build

# Vérifier contre le layout
in-toto-verify \
  --layout layout.json \
  --layout-keys owner-pubkey.pem \
  --link-dir .

Résultat attendu :

The software product passed all verification.

Si une étape manque :

in-toto.exceptions.LinkNotFoundError: No link found for step 'audit'

9.6 Intégration avec SLSA et GUAC

Les attestations in-toto sont compatibles avec l'écosystème Sigstore :

# Les attestations SLSA sont au format in-toto
cosign download attestation ghcr.io/VOTRE_USER/secure-python-pipeline:v1.0.0 \
  | jq -r '.payload' | base64 -d | jq '._type'
# Sortie : "https://in-toto.io/Statement/v1"

# GUAC peut ingérer les links in-toto
guacone collect files *.link --gql-addr http://localhost:8080/query

Quand utiliser in-toto complet ?

• SLSA seul : suffisant pour la plupart des projets, prouve la provenance du build
• in-toto complet : nécessaire si vous devez prouver que des étapes spécifiques (review humaine, scan de sécurité) ont eu lieu

Pour ce guide, SLSA couvre les besoins courants. Explorez in-toto complet si vous avez des exigences de compliance strictes.

Guide complet in-toto Comprendre layouts, links et vérification en profondeur

Dépannage

Voici les erreurs les plus fréquentes rencontrées en construisant ce pipeline, avec leur cause probable et la correction à appliquer.

Symptôme	Cause probable	Solution
permission denied sur GHCR	Token sans scope packages:write	Vérifier les permissions du workflow
Cosign sign échoue	id-token: write manquant	Ajouter la permission dans le workflow
Attestation non trouvée	attestations: write manquant	Ajouter la permission
SBOM vide	Image sans packages détectables	Vérifier que Syft détecte le bon format
Scorecard score bas	Branch protection désactivée	Activer les protections recommandées
pip-audit échoue	Vulnérabilité dans une dépendance	Mettre à jour la dépendance concernée
GUAC ingestion échoue	URL GraphQL incorrecte	Vérifier GUAC_API_URL et la connectivité
GUAC ne voit pas les CVE	Certifier OSV pas lancé	Exécuter guacone certifier osv
in-toto verify échoue	Link manquant pour une étape	Vérifier que tous les jobs génèrent leur link
LinkNotFoundError	Artefact link non téléchargé	Vérifier download-artifact dans le workflow

Glissez pour voir

Débugger les permissions

Les permissions effectives du GITHUB_TOKEN sont affichées par GitHub lui-même : ouvrez l'exécution du workflow, dépliez le step « Set up job » et cherchez le bloc GITHUB_TOKEN Permissions. Il liste exactement les portées accordées au job.

N'écrivez jamais echo sur github.token ni toJSON(secrets) : cela revient à écrire un secret dans les logs.

Résumé des protections

Le pipeline empile plusieurs couches de protection, chacune fermant une voie d'attaque différente, du code source jusqu'à la visibilité globale de la supply chain. Ce tableau les récapitule de bout en bout.

Couche	Outil	Ce qu'il protège
Code	Ruff, Bandit	Qualité, vulnérabilités SAST
Dépendances	pip-audit, hash pinning	Vulnérabilités, intégrité
Build	SLSA attestation	Traçabilité du build
Image	Cosign signature	Authenticité de l'image
Inventaire	Syft SBOM	Liste des composants
Vulnérabilités	Trivy	CVE dans l'image
Repo	Scorecard	Pratiques de sécurité
Mises à jour	Dependabot	Dépendances obsolètes
Visibilité globale	GUAC	Graphe de toutes les dépendances et CVE
Politique pipeline	in-toto	Preuve que toutes les étapes ont été exécutées

Glissez pour voir

À retenir

1. Branch protection est le premier rempart : pas de commit direct sur main
2. Actions épinglées par SHA : les tags peuvent être modifiés, pas les SHA
3. Hash pinning pour les dépendances : garantit l'intégrité même si PyPI est compromis
4. SLSA attestation prouve que le build vient de votre CI, pas d'un laptop compromis
5. Signature Cosign permet à vos consommateurs de vérifier l'authenticité
6. SBOM documente exactement ce qui est dans l'image pour répondre aux audits
7. GUAC connecte tous vos SBOM pour répondre rapidement aux CVE 0-day
8. Scorecard vous donne une note et des axes d'amélioration concrets
9. in-toto garantit que le pipeline complet a été respecté (lint → test → audit → build)

Prochaines étapes

Checklist sécurité GitHub Actions Repasser chaque point de durcissement en revue

GUAC : graphe de dépendances Analyser les relations entre vos composants

in-toto : attestations complètes Définir des layouts et vérifier toute la chaîne de build

VEX : gérer les faux positifs Documenter les vulnérabilités non applicables

Ressources externes

Pour approfondir chaque maillon de la chaîne, ces références officielles complètent le guide.

• SLSA GitHub Generator
• GitHub Attestations documentation
• Cosign documentation
• OpenSSF Scorecard Checks
• pip-audit documentation

×

📖 Voir la documentation →