charybdis/CONTRIBUTING.md

Contributing to Charybdis

Contributions are welcome! Whether it's a bug report, feature idea, documentation improvement, or code contribution.

Getting Started

Prerequisites

• Rust stable (1.79+)
• PostgreSQL 14+
• protoc (Protocol Buffers compiler)

Development Setup

# Clone the repo
git clone <your-charybdis-repo-url>
cd charybdis

# Copy config
cp config.toml.example config.toml
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Build
cargo build --workspace

# Run tests
cargo test -p charybdis

# Run the server
cargo run -p charybdis-server

Project Structure

src/              Core library (catalog, findings, scanners, security)
charybdis-server/ Deployable binary (links core + plugins)
plugins/          External integrations (DefectDojo, Keycloak, etc.)
proto/            Protocol Buffer definitions

How to Contribute

Reporting Bugs

Open an issue with:

• What you expected to happen
• What actually happened
• Steps to reproduce
• Rust version (rustc --version) and OS

Proposing Features

Open an issue describing:

• The problem you're trying to solve
• Your proposed approach
• Any alternatives you considered

Submitting Code

1. Fork the repo and create a branch from main
2. Make your changes
3. Ensure cargo fmt, cargo clippy, and cargo test pass
4. Write a clear commit message explaining the why
5. Open a PR against main

Adding a Scanner Parser

To add support for a new scan format:

1. Create src/scanners/your_format.rs
2. Implement the ScannerParser trait
3. Register it in ParserRegistry::with_builtins() (or via plugin contributed_parsers())
4. Add tests with sample data

pub struct YourFormatParser;

impl ScannerParser for YourFormatParser {
    fn format_id(&self) -> &str { "your-format" }
    fn description(&self) -> &str { "Description of the format" }
    fn parse(&self, data: &[u8]) -> Result<ParsedReport> {
        // Parse and normalize findings
    }
}

Code Style

• Run cargo fmt before committing
• Run cargo clippy and address warnings
• No comments unless the why is non-obvious
• Prefer exhaustive matches over wildcards for proto enums

Architecture Decisions

• Security features belong in src/ (core), not in plugins/
• Plugins are for external integrations (Slack, Jira, DefectDojo sync)
• All API is gRPC-first, other interfaces are adapters
• Database schema never changes (protobuf handles evolution)