charybdis/README.md

Charybdis

A security-native platform engineering tool.

One Rust binary for your software catalog. Event-driven, gRPC-native, no YAML to maintain. Designed to grow into a unified catalog + vulnerability management + compliance platform.

What Works Today

• Software catalog — gRPC API for entity CRUD (Component, System, API, User, Group, Domain, Resource, Finding). Real-time event bus on every change.
• Vulnerability ingestion — gRPC IngestionService ingests SARIF reports. Findings are deduplicated, reconciled against existing state (new / unchanged / resolved / reopened), and dry-runnable for MR-level diffs.
• Backstage YAML adapter — HTTP endpoint exposing entities as Backstage-compatible Location YAML, for migration or coexistence.
• mTLS + RBAC — Certificate-based auth with fine-grained, OU-mapped roles.
• OpenTelemetry — Traces, metrics, and logs out of the box (console + OTLP).
• Plugin system — Event-driven (DefectDojo) and sync (Keycloak) plugins. Compile-time integrated.
• PostgreSQL storage — Zero-migration: entities stored as protobuf blobs in a fixed schema. New plugins add oneof variants, never columns.

For everything else (assessment workflows, security gates, license policies, compliance frameworks, more parsers, more plugins), see VISION.md and TODO.md.

Quick Start

# 1. Start PostgreSQL
docker run -d -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 postgres:15

# 2. Configure
cp config.toml.example config.toml
echo 'DATABASE_URL=postgresql://postgres:mysecretpassword@localhost:5432/postgres' > .env

# 3. Run
cargo run

# 4. Register your first service
grpcurl -plaintext -d '{
  "entity": {
    "kind": "Component",
    "component_metadata": {
      "name": "payment-api",
      "description": "Payment processing service",
      "tags": ["api", "critical"]
    },
    "component_spec": {
      "type": "service",
      "lifecycle": "production",
      "owner": "team-payments"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/CreateEntity

Detailed walkthrough: docs/getting-started.md.

How It Works

CI/CD Pipeline ──gRPC──> Charybdis
Scanner output ────────>   ├── Catalogs the entity
                           ├── Reconciles vulnerabilities (SARIF)
                           └── Fires events to plugins (DefectDojo, ...)

See docs/architecture.md for the full design (protobuf schema, storage model, event bus, plugin lifecycle).

Entity Kinds

Kind	Purpose
Component	Services, libraries, applications
System	Collections of components
API	Interfaces exposed by components
User, Group	People and teams
Domain	Business domains
Resource	Infrastructure resources
Finding	Security findings ingested from scanners

Conceptual details: docs/core-concepts.md.

Plugins

Two plugin types, both compile-time integrated:

• Event-driven — React to entity lifecycle events. Shipped: DefectDojo (auto-create products, engagements, member assignment).
• Sync — Pull data from external systems on a schedule. Shipped: Keycloak (users + groups).

Plugin model, configuration, and writing your own: plugins/README.md.

Documentation

• Getting Started — installation and first entity
• Core Concepts — entities, events, annotations
• Architecture — protobuf schema, storage, event bus
• Security — mTLS and RBAC configuration
• Plugins — DefectDojo, Keycloak, building your own
• Demo — full stack demo with DefectDojo
• Vision & Roadmap — where Charybdis is going

Technology Stack

Language	Rust
API	gRPC + Protocol Buffers
Database	PostgreSQL 14+ (protobuf + JSONB, zero-migration)
TLS	rustls (no OpenSSL dependency)
Observability	OpenTelemetry (traces, metrics, logs)

Contributing

See CONTRIBUTING.md.

License

Apache-2.0