Leitfaden für Beiträge

Beiträge zum DuoKey PQC Scanner

Leitfaden für Beiträge zur Entwicklung des DuoKey PQC Scanners

Gilt für:

Rust-EntwicklungOpen SourceCommunity

Vielen Dank für Ihr Interesse an einem Beitrag zum DuoKey PQC Scanner! Dieser Leitfaden hilft Ihnen beim Einstieg in die Entwicklung.

Einrichtung der Entwicklungsumgebung

Voraussetzungen

Voraussetzungen

• Rust: stable-Toolchain (neueste Version empfohlen)
• Git: für Versionskontrolle
• IDE: VS Code mit der Erweiterung rust-analyzer (empfohlen)

Repository klonen

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

Abhängigkeiten installieren

# Rust installieren, falls noch nicht installiert
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Rust auf neuestes stable aktualisieren
rustup update stable

# Entwicklungswerkzeuge installieren
rustup component add rustfmt clippy

# cargo-watch für die Entwicklung installieren
cargo install cargo-watch

# cargo-audit für Sicherheitsprüfungen installieren
cargo install cargo-audit

Projekt bauen

# Debug-Build
cargo build

# Release-Build (optimiert)
cargo build --release

# Tests ausführen
cargo test

# Mit Logging ausführen
RUST_LOG=debug cargo run -- agent

Projektstruktur

Auf hoher Ebene ist das Projekt in die folgenden funktionalen Bereiche gegliedert:

Bereich	Inhalt
CLI	Befehlszeilenschnittstelle und Befehlsweiterleitung
Core	Kernlogik des Scannings – Krypto-Erkennung, Risikobewertung, X.509-Operationen und die Algorithmen-Datenbank
Scanner	Die Scan-Modi – Agent, Dateisystem, Domain und Netzwerk
Parser	Formatparser für die unterstützten Zertifikats- und Keystore-Formate
Ausgabe	Ausgabeformatierer für die unterstützten Report-Formate
Hilfsfunktionen	Gemeinsame Helfer wie Logging und Fehlerbehandlung
Tests	Integrationstests
Benchmarks	Leistungs-Benchmarks
Beispiele	Verwendungsbeispiele

Entwicklungs-Workflow

1

Feature-Branch erstellen

git checkout -b feature/my-new-feature

2

Änderungen vornehmen

# Code im bevorzugten Editor bearbeiten

# Code formatieren
cargo fmt

# clippy für Lints ausführen
cargo clippy -- -D warnings

# Tests ausführen
cargo test

# Bestimmten Test ausführen
cargo test test_rsa_detection

3

Lokal testen

# Alle Tests ausführen
cargo test --all

# Integrationstests ausführen
cargo test --test '*'

# Mit Coverage ausführen (erfordert cargo-tarpaulin)
cargo install cargo-tarpaulin
cargo tarpaulin --out Html

# Benchmarks ausführen
cargo bench

4

Änderungen committen

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

5

Pushen und PR erstellen

git push origin feature/my-new-feature
# Pull Request auf GitHub erstellen

Coding-Standards

Rust-Style-Guide

Befolgen Sie die Rust API Guidelines. Bevorzugen Sie aussagekräftige, selbsterklärende Namen für Funktionen und Typen und dokumentieren Sie jedes öffentliche Element mit einem Doc-Kommentar, der dessen Zweck erklärt. Vermeiden Sie abgekürzte, kryptische Namen und undokumentierte öffentliche APIs.

Code-Formatierung

Verwenden Sie rustfmt mit Standardeinstellungen:

cargo fmt

Die rustfmt.toml des Projekts legt die 2021-Edition fest, setzt eine maximale Zeilenbreite von 100 Zeichen und verwendet die Standardeinstellung für small-heuristics.

Linting

Verwenden Sie clippy für Lints:

cargo clippy -- -D warnings

Dokumentation

Dokumentieren Sie alle öffentlichen APIs mit Doc-Kommentaren. Ein guter Doc-Kommentar fasst zusammen, was das Element tut, und enthält gegebenenfalls die Standardabschnitte: Arguments, Returns, Errors und Examples. Eine Funktion für einen Dateisystem-Scan sollte beispielsweise den akzeptierten Verzeichnispfad und das Rekursions-Flag beschreiben, die zurückgegebenen Funde, die Fehlerbedingungen (etwa ein fehlender Pfad oder unzureichende Berechtigungen) sowie ein kurzes Verwendungsbeispiel.

Testen

Platzieren Sie Unit-Tests neben dem Code, den sie abdecken, in einem Testmodul innerhalb derselben Datei. Jeder Test sollte ein Verhalten prüfen und ein bestimmtes Ergebnis zusichern – zum Beispiel überprüfen, dass ein 2048-Bit-RSA-Schlüssel den erwarteten Quantenrisikowert erhält, oder dass die Analyse eines ungültigen Zertifikats einen Fehler zurückgibt, anstatt zu panicken.

Leistung

Sicherheit

Wichtig

Führen Sie vor jedem Release ein Sicherheitsaudit durch, um sicherzustellen, dass keine bekannten Schwachstellen in den Abhängigkeiten vorhanden sind.

Sicherheitsaudit

cargo audit

# Schwachstellen beheben
cargo audit fix

Unsafe-Code

Warnung

Vermeiden Sie unsafe-Code, sofern nicht absolut notwendig. Falls erforderlich, dokumentieren Sie, warum er benötigt wird, erbringen Sie einen Sicherheitsnachweis, fügen Sie umfangreiche Tests hinzu und fordern Sie eine Überprüfung durch mehrere Maintainer an.

Wenn unsafe unvermeidbar ist, muss jeder solche Block einen # Safety-Doc-Abschnitt enthalten, der genau erklärt, warum die Operation korrekt ist.

Fehlerbehandlung

Verwenden Sie anyhow für Anwendungsfehler und thiserror für Bibliotheksfehler. Definieren Sie explizite, typisierte Fehlervarianten für die Bibliothek (zum Beispiel Fehler beim Parsen von Zertifikaten, I/O-Fehler und Fehler bei ungültigen Algorithmen) und versehen Sie jede fehleranfällige Operation mit aussagekräftigem Kontext, damit sich Fehler leicht bis zu ihrer Quelle zurückverfolgen lassen.

Logging

Verwenden Sie tracing für strukturiertes Logging. Geben Sie eine Meldung auf Info-Ebene aus, wenn eine wichtige Operation beginnt (etwa der Start eines Verzeichnis-Scans), eine Warnung, wenn ein behebbares Problem auftritt (etwa ein Verzeichniseintrag, auf den nicht zugegriffen werden kann), und Meldungen auf Debug-Ebene für feinkörnigere Fortschrittsdetails.

Konvention für Commit-Nachrichten

Befolgen Sie Conventional Commits:

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

<body>

<footer>

Typ	Beschreibung
feat	Neue Funktion
fix	Fehlerbehebung
docs	Dokumentationsänderungen
style	Code-Stiländerungen (Formatierung)
refactor	Code-Refactoring
perf	Leistungsverbesserungen
test	Hinzufügen von Tests
chore	Wartungsaufgaben

Pull-Request-Prozess

1

PR erstellen

Erstellen Sie einen PR mit einem klaren Titel und einer klaren Beschreibung.

2

Zugehörige Issues verknüpfen

Verwenden Sie "Closes #123", um zugehörige Issues zu verknüpfen.

3

Bestehen der Tests sicherstellen

Alle CI-Prüfungen müssen grün sein.

4

Review anfordern

Markieren Sie die relevanten Maintainer für das Code-Review.

5

Feedback bearbeiten

Nehmen Sie angeforderte Änderungen zeitnah vor.

6

Commits squashen

Vor dem Merge, falls von den Maintainern angefordert.

Release-Prozess

1

Version aktualisieren

Aktualisieren Sie die Projektversion im Package-Manifest.

2

Changelog aktualisieren

Aktualisieren Sie CHANGELOG.md mit den Release-Notes.

3

Release-Tag erstellen

git tag v1.0.0

4

Tag pushen

git push --tags

5

Release bauen

cargo build --release

6

Veröffentlichen

cargo publish

Community

GitHub Kommunikationskanäle

• GitHub Issues: Fehlerberichte und Feature-Anfragen
• GitHub Discussions: Allgemeine Fragen und Diskussionen
• Discord: Echtzeit-Chat (Link im README)

Code Verhaltenskodex

Wir befolgen den Rust Code of Conduct. Seien Sie respektvoll, inklusiv und konstruktiv in allen Interaktionen.

Lizenz

Mit einem Beitrag stimmen Sie zu, dass Ihre Beiträge unter derselben Lizenz wie das Projekt lizenziert werden (siehe LICENSE-Datei).

Fragen?

Falls Sie Fragen haben:

1. Prüfen Sie die vorhandene Dokumentation
2. Durchsuchen Sie die GitHub Issues
3. Fragen Sie in den GitHub Discussions
4. Kontaktieren Sie die Maintainer

Tipp

Vielen Dank für Ihren Beitrag zum PQC Scanner! Jeder Beitrag, egal wie klein, hilft, das Projekt besser zu machen.