Guide de contribution

Contribuer au DuoKey PQC Scanner

Guide pour contribuer au développement du DuoKey PQC Scanner

S'applique à :

Rust DevelopmentOpen SourceCommunity

Merci de votre intérêt à contribuer au DuoKey PQC Scanner ! Ce guide vous aidera à démarrer avec le développement.

Configuration de l'environnement de développement

Prérequis

Prérequis

• Rust : chaîne d'outils stable (dernière version recommandée)
• Git : pour le contrôle de version
• IDE : VS Code avec l'extension rust-analyzer (recommandé)

Cloner le dépôt

git clone https://github.com/duokey/dke-scanner-agent.git
cd dke-scanner-agent

Installer les dépendances

# Install Rust if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update Rust to latest stable
rustup update stable

# Install development tools
rustup component add rustfmt clippy

# Install cargo-watch for development
cargo install cargo-watch

# Install cargo-audit for security checks
cargo install cargo-audit

Compiler le projet

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- agent

Structure du projet

À un niveau global, le projet est organisé selon les domaines fonctionnels suivants :

Domaine	Contenu
CLI	Interface en ligne de commande et répartition des commandes
Core	Logique d'analyse principale -- détection cryptographique, notation du risque, opérations X.509 et base de données des algorithmes
Scanners	Les modes d'analyse -- agent, système de fichiers, domaine et réseau
Analyseurs	Analyseurs de formats pour les formats de certificats et de magasins de clés pris en charge
Sortie	Formateurs de sortie pour les formats de rapport pris en charge
Utilitaires	Aides partagées telles que la journalisation et la gestion des erreurs
Tests	Tests d'intégration
Benchmarks	Tests de performance
Exemples	Exemples d'utilisation

Flux de travail de développement

1

Créer une branche de fonctionnalité

git checkout -b feature/my-new-feature

2

Apporter des modifications

# Edit code in your preferred editor

# Format code
cargo fmt

# Run clippy for lints
cargo clippy -- -D warnings

# Run tests
cargo test

# Run specific test
cargo test test_rsa_detection

3

Tester localement

# Run all tests
cargo test --all

# Run integration tests
cargo test --test '*'

# Run with coverage (requires cargo-tarpaulin)
cargo install cargo-tarpaulin
cargo tarpaulin --out Html

# Run benchmarks
cargo bench

4

Valider les modifications

git add .
git commit -m "feat: add new feature"

5

Pousser et créer une PR

git push origin feature/my-new-feature
# Create pull request on GitHub

Normes de codage

Guide de style Rust

Suivez les directives d'API Rust. Privilégiez des noms descriptifs et explicites pour les fonctions et les types, et documentez chaque élément public avec un commentaire de documentation qui explique son objectif. Évitez les noms abrégés et cryptiques ainsi que les API publiques non documentées.

Formatage du code

Utilisez rustfmt avec les paramètres par défaut :

cargo fmt

Le fichier rustfmt.toml du projet fixe l'édition 2021, définit une largeur de ligne maximale de 100 caractères et utilise le paramètre small-heuristics par défaut.

Analyse statique (linting)

Utilisez clippy pour l'analyse statique :

cargo clippy -- -D warnings

Documentation

Documentez toutes les API publiques avec des commentaires de documentation. Un bon commentaire de documentation résume ce que fait l'élément et inclut les sections standard le cas échéant : Arguments, Returns, Errors et Examples. Par exemple, une fonction d'analyse de système de fichiers devrait décrire le chemin de répertoire et l'indicateur de récursivité qu'elle accepte, les constats qu'elle renvoie, les conditions d'erreur (comme un chemin manquant ou des permissions insuffisantes) et un court exemple d'utilisation.

Tests

Placez les tests unitaires à côté du code qu'ils couvrent, dans un module de test au sein du même fichier. Chaque test devrait exercer un seul comportement et vérifier un résultat spécifique -- par exemple, vérifier qu'une clé RSA de 2048 bits reçoit le score de risque quantique attendu, ou que l'analyse d'un certificat invalide renvoie une erreur plutôt que de provoquer une panique.

Performance

Sécurité

Important

Exécutez un audit de sécurité avant chaque release pour vous assurer qu'aucune vulnérabilité connue n'est présente dans les dépendances.

Audit de sécurité

cargo audit

# Fix vulnerabilities
cargo audit fix

Code non sûr (unsafe)

Avertissement

Évitez le code unsafe sauf si c'est absolument nécessaire. Si nécessaire, documentez pourquoi il est requis, fournissez une preuve de sûreté, ajoutez des tests exhaustifs et demandez une revue par plusieurs mainteneurs.

Lorsque unsafe est inévitable, chaque bloc de ce type doit comporter une section de documentation # Safety qui explique exactement pourquoi l'opération est saine.

Gestion des erreurs

Utilisez anyhow pour les erreurs applicatives et thiserror pour les erreurs de bibliothèque. Définissez des variantes d'erreur explicites et typées pour la bibliothèque (par exemple, les échecs d'analyse de certificat, les erreurs d'E/S et les erreurs d'algorithme invalide), et associez un contexte descriptif à chaque opération faillible afin que les échecs soient faciles à retracer jusqu'à leur source.

Journalisation

Utilisez tracing pour la journalisation structurée. Émettez un message de niveau info lorsqu'une opération majeure commence (comme le démarrage d'une analyse de répertoire), un avertissement lorsqu'un problème récupérable survient (comme une entrée de répertoire inaccessible) et des messages de niveau debug pour les détails de progression plus fins.

Convention de messages de commit

Suivez les Conventional Commits :

<type>(<scope>): <subject>

<body>

<footer>

Type	Description
feat	Nouvelle fonctionnalité
fix	Correction de bogue
docs	Modifications de la documentation
style	Modifications de style du code (formatage)
refactor	Refactorisation du code
perf	Améliorations de performance
test	Ajout de tests
chore	Tâches de maintenance

Processus de pull request

1

Créer une PR

Créez une PR avec un titre et une description clairs.

2

Lier les problèmes associés

Utilisez "Closes #123" pour lier les problèmes associés.

3

Vérifier que les tests passent

Toutes les vérifications CI doivent être au vert.

4

Demander une revue

Mentionnez les mainteneurs concernés pour la revue de code.

5

Traiter les retours

Apportez les modifications demandées rapidement.

6

Regrouper les commits (squash)

Avant la fusion, si les mainteneurs le demandent.

Processus de release

1

Mettre à jour la version

Mettez à jour la version du projet dans le manifeste du paquet.

2

Mettre à jour le journal des modifications

Mettez à jour CHANGELOG.md avec les notes de version.

3

Créer le tag de release

git tag v1.0.0

4

Pousser le tag

git push --tags

5

Compiler la release

cargo build --release

6

Publier

cargo publish

Communauté

GitHub Canaux de communication

• GitHub Issues : rapports de bogues et demandes de fonctionnalités
• GitHub Discussions : questions générales et discussions
• Discord : chat en temps réel (lien dans le README)

Code Code de conduite

Nous suivons le code de conduite Rust. Soyez respectueux, inclusif et constructif dans toutes les interactions.

Licence

En contribuant, vous acceptez que vos contributions soient publiées sous la même licence que le projet (voir le fichier LICENSE).

Des questions ?

Si vous avez des questions :

1. Consultez la documentation existante
2. Recherchez dans les problèmes GitHub
3. Posez la question dans GitHub Discussions
4. Contactez les mainteneurs

Astuce

Merci de contribuer au PQC Scanner ! Chaque contribution, aussi petite soit-elle, aide à améliorer le projet.