Public Access
113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# 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](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
|
|
|
|
# 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](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](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](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](plugins/README.md).
|
|
|
|
## Documentation
|
|
|
|
- [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
|
|
- [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) |
|
|
| TLS | rustls (no OpenSSL dependency) |
|
|
| Observability | OpenTelemetry (traces, metrics, logs) |
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## License
|
|
|
|
[Apache-2.0](LICENSE.md)
|