guillaume.grabe/charybdis
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: update and cleanup
CI / Check (push) Successful in 13m13s
Details
CI / Format (push) Successful in 48s
Details
CI / Clippy (push) Successful in 12m13s
Details
CI / Test (push) Successful in 12m45s
Details

Browse Source
This commit is contained in:
Guillaume GRABÉ
2026-06-09 11:26:47 +02:00
parent ab13af48e7
commit f1b1543f29
11 changed files with 1113 additions and 3376 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+48 -184
View File
@@ -1,41 +1,26 @@
# Charybdis
**The security-native platform engineering tool.**
**A security-native platform engineering tool.**
One platform for your software catalog, vulnerability management, and compliance posture. Event-driven. Single binary. No YAML files to maintain.
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.
## Why Charybdis?
## What Works Today
Platform engineers today run Backstage for the catalog, DefectDojo for vulnerabilities, Dependency-Track for SBOMs, a license scanner, and a compliance spreadsheet. Five tools, five sources of truth, none of them talking to each other.
- **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.
Charybdis unifies this:
- **Software Catalog** — Event-driven, gRPC-native. Services register from CI/CD or IaC. No static YAML, no polling, always accurate.
- **Vulnerability Management** — Ingest scan results natively (SARIF, CycloneDX, SPDX). Triage, assess, track. No external vuln tool needed.
- **Compliance & Licenses** — Security gates, license policies, compliance framework mappings. Built-in, not bolted on.
All of this in a **single Rust binary** that uses ~50MB of RAM.
## How It Works
```
CI/CD Pipeline ──gRPC──> Charybdis
Scanner results ───────> ├── Catalogs the service (event-driven)
IaC tools ─────────────> ├── Ingests vulnerabilities natively
├── Evaluates security gates
└── Fires events to plugins (Slack, Jira, ...)
```
**One platform. Your services are cataloged. Your vulns are tracked. Your compliance is visible. In real-time.**
For everything else (assessment workflows, security gates, license policies, compliance frameworks, more parsers, more plugins), see [VISION.md](VISION.md) and [TODO.md](TODO.md).
## Quick Start
```bash
# 1. Start PostgreSQL
docker run -d \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
postgres:15
docker run -d -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 postgres:15
# 2. Configure
cp config.toml.example config.toml
@@ -62,187 +47,66 @@ grpcurl -plaintext -d '{
}' localhost:50051 charybdis.entities.EntityService/CreateEntity
```
The entity is stored, events are fired, and plugins react automatically.
Detailed walkthrough: [docs/getting-started.md](docs/getting-started.md).
## Key Features
### Software Catalog
- **gRPC API** for programmatic entity management from CI/CD, scripts, or any tool
- **Event-driven plugins** auto-provision external tools when entities change
- **Zero-migration storage** — PostgreSQL with protobuf + JSONB. No schema changes, ever
- **Rich entity model** — Component, System, API, User, Group, Domain, Resource
- **Backstage compatible** — Built-in YAML adapter for migration or coexistence
### Security (Native — Phase 1)
Security is a first-class concept in Charybdis, not a plugin. These features are under active development:
- **Vulnerability ingestion** — Push scan results via gRPC (SARIF, CycloneDX, SPDX)
- **Assessment workflow** — Triage, accept risk, remediate, auto-assess via rules
- **Security gates** — Severity thresholds per product, block deployments on violations
- **License compliance** — Track licenses, enforce policies, flag violations
- **Compliance frameworks** — Map vulnerabilities to NIS2, SOC2, DORA requirements
### Platform
- **mTLS + RBAC** — Certificate-based auth with fine-grained permissions
- **OpenTelemetry** — Full observability (traces, metrics, logs) out of the box
- **Single binary** — Deploy one Rust binary + PostgreSQL. That's it.
- **Sub-millisecond latency** — Tested at 170k+ entities
## Architecture
```mermaid
graph TB
subgraph "Sources"
A1[CI/CD Pipelines]
A2[IaC Tools]
A3[Security Scanners]
end
subgraph "Charybdis Core"
B1[gRPC API]
B2[Software Catalog]
B3[Vuln Management]
B4[Security Gates]
B5[Event Bus]
end
subgraph "Integrations - Plugins"
C1[Slack / Teams]
C2[Jira / GitHub Issues]
C3[Custom Plugins]
end
subgraph "Frontend"
D2[Backstage - optional]
end
A1 -->|gRPC| B1
A2 -->|gRPC| B1
A3 -->|Scan Results| B1
B1 --> B2
B1 --> B3
B3 --> B4
B2 --> B5
B3 --> B5
B5 --> C1
B5 --> C2
B5 --> C3
B2 -.->|YAML Adapter| D2
```
## Entity Model
| Kind | Description | Example |
|------|-------------|---------|
| **Service** | Individual microservices or applications | `payment-api`, `auth-service` |
| **Component** | Reusable libraries, SDKs, modules | `auth-sdk`, `logging-lib` |
| **System** | Collections of components working together | `payment-system` |
| **API** | Interfaces exposed by components | `payments-rest-api` |
| **User** | Individual people | `john.doe` |
| **Group** | Teams and organizational units | `team-payments` |
| **Domain** | Business domains | `payments`, `shipping` |
| **Resource** | Infrastructure resources | `payments-db`, `cache-cluster` |
Each entity will carry its security posture natively once Phase 1 is complete: vulnerabilities, license status, compliance state, and assessment history.
## Plugin System
Core features (catalog, vulns, compliance) are **native**. Plugins handle **integrations** with external systems:
## How It Works
```
EntityCreated ──> Event Bus ──> DefectDojo Plugin ──> Creates product
──> Slack Plugin ──> Notifies channel (planned)
──> Custom Plugin ──> Your logic
CI/CD Pipeline ──gRPC──> Charybdis
Scanner output ────────> ├── Catalogs the entity
├── Reconciles vulnerabilities (SARIF)
└── Fires events to plugins (DefectDojo, ...)
```
Two plugin types:
- **Event-Driven** — React to entity/vulnerability events in real-time
- **Sync** — Pull data from external sources on a schedule (e.g., sync users from Keycloak)
See [docs/architecture.md](docs/architecture.md) for the full design (protobuf schema, storage model, event bus, plugin lifecycle).
**Current plugins:**
- DefectDojo — Auto-create products, engagements, and assign owners (Done)
- Keycloak — Sync users and groups with annotations (Done)
- Dependency-Track — Scaffolded
- Jira, Slack, GitHub — Planned
## Entity Kinds
Build your own with the `EventDrivenPlugin` or `SyncPlugin` traits.
| 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 |
## Backstage Compatibility
Conceptual details: [docs/core-concepts.md](docs/core-concepts.md).
Already using Backstage? Charybdis works as a **drop-in dynamic backend**. Point Backstage at Charybdis's YAML adapter and stop maintaining `catalog-info.yaml` files:
## Plugins
```yaml
# backstage app-config.yaml
catalog:
locations:
- type: url
target: http://charybdis:8080/yaml/locations
rules:
- allow: [Component, System, Service, API, User, Group]
```
Two plugin types, both compile-time integrated:
Or use Charybdis standalone via its gRPC API — no Backstage needed.
- **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).*
## vs. Alternatives
| | Charybdis | Backstage | Port / Cortex / OpsLevel |
|---|---|---|---|
| **Type** | Open source | Open source | Commercial SaaS |
| **Catalog** | Event-driven, real-time | Static YAML, polling | Varies |
| **Security** | Native (first-class) | Plugins (fragmented) | Limited / add-on |
| **Deployment** | Single binary + PG | Node.js cluster + PG + plugins | Hosted |
| **Performance** | ~50MB RAM, sub-ms | ~1GB+ RAM | N/A |
| **Compliance** | Native frameworks | Manual | Some |
| **Cost** | Free | Free (+ operational cost) | $$$$ |
## Project Status
| Module | Status | Phase |
|--------|--------|-------|
| Core gRPC API | Done | 0 |
| PostgreSQL storage | Done | 0 |
| Event bus system | Done | 0 |
| Plugin framework | Done | 0 |
| mTLS + RBAC | Done | 0 |
| OpenTelemetry | Done | 0 |
| Backstage YAML adapter | Done | 0 |
| DefectDojo plugin | Done | 0 |
| Keycloak plugin | Done | 0 |
| Vulnerability ingestion | Planned | 1 |
| SARIF / CycloneDX / SPDX parsers | Planned | 1 |
| Security gates & rules engine | Planned | 1 |
| Compliance frameworks | Planned | 3 |
See [VISION.md](VISION.md) for the full roadmap.
Plugin model, configuration, and writing your own: [plugins/README.md](plugins/README.md).
## Documentation
- [Vision & Roadmap](VISION.md) — Where Charybdis is going
- [Getting Started](docs/getting-started.md) — Installation and first steps
- [Core Concepts](docs/core-concepts.md) — Entities, events, and architecture
- [Getting Started](docs/getting-started.md) — installation and first entity
- [Core Concepts](docs/core-concepts.md) — entities, events, annotations
- [Architecture](docs/architecture.md) — protobuf schema, storage, event bus
- [Security](docs/security.md) — mTLS and RBAC configuration
- [Architecture](docs/architecture.md) — Deep dive into design decisions
- [Plugin Guide](plugins/README.md) — Building and using plugins
- [Demo](deploy/DEMO.md) — Full stack demo with DefectDojo
- [Plugins](plugins/README.md) — DefectDojo, Keycloak, building your own
- [Demo](deploy/DEMO.md) — full stack demo with DefectDojo
- [Vision & Roadmap](VISION.md) — where Charybdis is going
## Technology Stack
| | |
|---|---|
| **Language** | Rust |
| **API** | gRPC + Protocol Buffers |
| **Database** | PostgreSQL 14+ (protobuf + JSONB, zero-migration) |
| **Frontend** | Backstage YAML adapter (compatible) |
| **Security** | mTLS (rustls) + RBAC |
| **Observability** | OpenTelemetry (traces, metrics, logs) |
| Language | Rust |
| API | gRPC + Protocol Buffers |
| Database | PostgreSQL 14+ (protobuf + JSONB, zero-migration) |
| TLS | rustls (no OpenSSL dependency) |
| Observability | OpenTelemetry (traces, metrics, logs) |
## Contributing
Contributions are welcome! Whether it's a new plugin, a security parser, or documentation improvements — we'd love your help.
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
[Apache-2.0](LICENSE)
---
**One platform. Catalog. Security. Compliance. Built in Rust.**
[Apache-2.0](LICENSE.md)