initial-commit

2026-05-12 17:06:43 +02:00
commit 051a080dfa
110 changed files with 26377 additions and 0 deletions
@@ -0,0 +1,102 @@
+# 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
+
+```bash
+# Clone the repo
+git clone https://github.com/YOUR-ORG/charybdis.git
+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
+
+```rust
+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)