Contributing Guide
Contributing to DuoKey PQC Scanner
Guide for contributing to DuoKey PQC Scanner development
Thank you for your interest in contributing to the DuoKey PQC Scanner! This guide will help you get started with development.
Development Setup
Prerequisites
Prerequisites
- Rust: stable toolchain (latest version recommended)
- Git: for version control
- IDE: VS Code with rust-analyzer extension (recommended)
Clone Repository
git clone https://github.com/duokey/dke-scanner-agent.git
cd dke-scanner-agent
Install Dependencies
# 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
Build Project
# Debug build
cargo build
# Release build (optimized)
cargo build --release
# Run tests
cargo test
# Run with logging
RUST_LOG=debug cargo run -- agent
Project Structure
At a high level, the project is organized into the following functional areas:
| Area | Contents |
|---|---|
| CLI | Command-line interface and command dispatch |
| Core | Core scanning logic -- crypto detection, risk scoring, X.509 operations, and the algorithms database |
| Scanners | The scanning modes -- agent, filesystem, domain, and network |
| Parsers | Format parsers for the supported certificate and keystore formats |
| Output | Output formatters for the supported report formats |
| Utilities | Shared helpers such as logging and error handling |
| Tests | Integration tests |
| Benchmarks | Performance benchmarks |
| Examples | Usage examples |
Development Workflow
Create Feature Branch
git checkout -b feature/my-new-feature
Make Changes
# 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
Test Locally
# 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
Commit Changes
git add .
git commit -m "feat: add new feature"
Push and Create PR
git push origin feature/my-new-feature
# Create pull request on GitHub
Coding Standards
Rust Style Guide
Follow the Rust API Guidelines. Favor descriptive, self-explanatory names for functions and types, and document every public item with a doc comment that explains its purpose. Avoid abbreviated, cryptic names and undocumented public APIs.
Code Formatting
Use rustfmt with default settings:
cargo fmt
The project's rustfmt.toml pins the 2021 edition, sets a maximum line width of 100 characters, and uses the default small-heuristics setting.
Linting
Use clippy for lints:
cargo clippy -- -D warnings
Documentation
Document all public APIs with doc comments. A good doc comment summarizes what the item does and includes the standard sections where relevant: Arguments, Returns, Errors, and Examples. For instance, a filesystem scan function should describe the directory path and recursion flag it accepts, the findings it returns, the error conditions (such as a missing path or insufficient permissions), and a short usage example.
Testing
Place unit tests alongside the code they cover, in a test module within the same file. Each test should exercise one behavior and assert a specific outcome -- for example, verifying that a 2048-bit RSA key receives the expected quantum-risk score, or that analyzing an invalid certificate returns an error rather than panicking.
Performance
Security
Run security audit before every release to ensure no known vulnerabilities are present in dependencies.
Security Audit
cargo audit
# Fix vulnerabilities
cargo audit fix
Unsafe Code
Avoid unsafe code unless absolutely necessary. If required, document why it is needed, provide safety proof, add extensive tests, and request review by multiple maintainers.
When unsafe is unavoidable, every such block must carry a # Safety doc section that explains exactly why the operation is sound.
Error Handling
Use anyhow for application errors and thiserror for library errors. Define explicit, typed error variants for the library (for example, certificate-parsing failures, I/O errors, and invalid-algorithm errors), and attach descriptive context to each fallible operation so failures are easy to trace back to their source.
Logging
Use tracing for structured logging. Emit an info-level message when a major operation begins (such as starting a directory scan), a warning when a recoverable problem occurs (such as a directory entry that cannot be accessed), and debug-level messages for finer-grained progress details.
Commit Message Convention
Follow Conventional Commits:
<type>(<scope>): <subject>
<body>
<footer>
| Type | Description |
|---|---|
| feat | New feature |
| fix | Bug fix |
| docs | Documentation changes |
| style | Code style changes (formatting) |
| refactor | Code refactoring |
| perf | Performance improvements |
| test | Adding tests |
| chore | Maintenance tasks |
Pull Request Process
Create PR
Create a PR with a clear title and description.
Link Related Issues
Use "Closes #123" to link related issues.
Ensure Tests Pass
All CI checks must be green.
Request Review
Tag relevant maintainers for code review.
Address Feedback
Make requested changes promptly.
Squash Commits
Before merge, if requested by maintainers.
Release Process
Update Version
Update the project version in the package manifest.
Update Changelog
Update CHANGELOG.md with release notes.
Create Release Tag
git tag v1.0.0
Push Tag
git push --tags
Build Release
cargo build --release
Publish
cargo publish
Community
Communication Channels
- GitHub Issues: Bug reports and feature requests
- GitHub Discussions: General questions and discussions
- Discord: Real-time chat (link in README)
Code of Conduct
We follow the Rust Code of Conduct. Be respectful, inclusive, and constructive in all interactions.
License
By contributing, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).
Questions?
If you have questions:
- Check existing documentation
- Search GitHub issues
- Ask in GitHub Discussions
- Contact maintainers
Thank you for contributing to PQC Scanner! Every contribution, no matter how small, helps make the project better.