Public Access
126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# Charybdis Documentation
|
|
|
|
**The security-native platform engineering tool.**
|
|
|
|
## What is Charybdis?
|
|
|
|
Charybdis is a platform engineering tool that unifies **software catalog**, **vulnerability management**, and **compliance posture** in a single event-driven platform. Built in Rust, deployed as a single binary.
|
|
|
|
Instead of running Backstage + DefectDojo + Dependency-Track + a license scanner + a compliance spreadsheet, you run Charybdis.
|
|
|
|
### The Problems It Solves
|
|
|
|
1. **Fragmented tooling** — Your software catalog, vulnerability data, license info, and compliance evidence live in 5 different tools that don't talk to each other. Charybdis unifies them.
|
|
|
|
2. **Static catalog data** — Traditional catalogs rely on YAML files that go stale within weeks. Charybdis is event-driven — CI/CD pipelines and IaC tools register and update entities via gRPC, so the catalog is always accurate.
|
|
|
|
3. **Security as an afterthought** — In Backstage, security is a plugin. In Charybdis, every entity carries its vulnerability posture, license status, and compliance state natively.
|
|
|
|
4. **Manual provisioning** — New service? Manually create entries in every tool. With Charybdis, one gRPC call catalogs the service and event-driven plugins handle the rest.
|
|
|
|
5. **Compliance evidence assembly** — Compliance reporting pulls from real vulnerability and license data, not spreadsheets.
|
|
|
|
## How It Works
|
|
|
|
```
|
|
CI/CD or Scanner ──gRPC──> Charybdis
|
|
├── Catalogs the service (event-driven) ← Done
|
|
├── Fires events to plugins (DefectDojo, ...) ← Done
|
|
├── Ingests scan results (SARIF, CycloneDX) ← Phase 1
|
|
├── Evaluates security gates & rules ← Phase 1
|
|
└── Exposes catalog via YAML adapter (Backstage) ← Done
|
|
```
|
|
|
|
**One platform. Your services are cataloged. Your vulns are tracked. Your compliance is visible. In real-time.**
|
|
|
|
## Key Concepts
|
|
|
|
| Concept | Description |
|
|
|---------|-------------|
|
|
| **Entity** | Anything in your software ecosystem: services, systems, components, APIs, users, groups, domains, resources |
|
|
| **Vulnerability** | *(Phase 1)* A security finding linked to an entity, ingested from scanner output (SARIF, CycloneDX) |
|
|
| **Assessment** | *(Phase 1)* The triage decision on a vulnerability: accept risk, remediate, auto-assessed by rules |
|
|
| **Security Gate** | *(Phase 1)* Severity thresholds per product — blocks deployments when violated |
|
|
| **Event Bus** | Publishes lifecycle events when entities or vulnerabilities change |
|
|
| **Plugin** | Reacts to events to integrate with external systems (Slack, Jira, GitHub, custom) |
|
|
| **Annotations** | Key-value metadata on entities for external references (e.g. `github.com/repo-slug`) |
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[CI/CD / Scanners] -->|gRPC| B[Charybdis]
|
|
B -->|Native| C[Software Catalog]
|
|
B -->|Native| D[Vuln Management]
|
|
B -->|Native| E[Compliance]
|
|
B -->|Events| F[Plugins: Slack / Jira / Custom]
|
|
B -->|YAML| G[Backstage - optional]
|
|
|
|
style B fill:#4A90E2,stroke:#2E5C8A,color:#fff
|
|
style D fill:#E24A4A,stroke:#8A2E2E,color:#fff
|
|
style E fill:#4AE28A,stroke:#2E8A5C,color:#fff
|
|
```
|
|
|
|
## Documentation
|
|
|
|
### Getting Started
|
|
- [Installation & Quick Start](getting-started.md) — Get Charybdis running and register your first entity
|
|
- [Demo Stack](../deploy/DEMO.md) — Full demo with DefectDojo
|
|
|
|
### Understanding Charybdis
|
|
- [Core Concepts](core-concepts.md) — Entities, vulnerabilities, events, and data model
|
|
- [Vision & Roadmap](../VISION.md) — Where Charybdis is going and why
|
|
- [Architecture](architecture.md) — Technical design decisions
|
|
|
|
### Configuration
|
|
- [Security](security.md) — mTLS authentication and RBAC authorization
|
|
- [Plugin Configuration](PLUGIN_CONFIGURATION_GUIDE.md) — Setting up and configuring plugins
|
|
|
|
### Extending Charybdis
|
|
- [Plugin Development](../plugins/README.md) — Build your own integration plugins
|
|
|
|
## Quick Example
|
|
|
|
Register a service from your CI/CD pipeline:
|
|
|
|
```bash
|
|
grpcurl -plaintext -d '{
|
|
"entity": {
|
|
"kind": "Component",
|
|
"component_metadata": {
|
|
"name": "payment-api",
|
|
"description": "Payment processing service"
|
|
},
|
|
"component_spec": {
|
|
"type": "service",
|
|
"lifecycle": "production",
|
|
"owner": "team-payments"
|
|
}
|
|
}
|
|
}' charybdis:50051 charybdis.entities.EntityService/CreateEntity
|
|
```
|
|
|
|
**What happens next:**
|
|
- Entity stored in PostgreSQL with a UUID
|
|
- `EntityCreated` event published to the event bus
|
|
- Plugins react (e.g., DefectDojo creates a product automatically)
|
|
- Entity available via gRPC and YAML adapter
|
|
|
|
No YAML file to write. No PR to open. No manual provisioning.
|
|
|
|
## Backstage Migration
|
|
|
|
Already using Backstage? Charybdis provides a YAML adapter for gradual migration. Point Backstage at Charybdis as a catalog source — entities registered via gRPC are immediately available in Backstage.
|
|
|
|
```yaml
|
|
# backstage app-config.yaml
|
|
catalog:
|
|
locations:
|
|
- type: url
|
|
target: http://charybdis:8080/yaml/locations
|
|
```
|
|
|
|
---
|
|
|
|
**Ready to get started?** Head to the [Getting Started Guide](getting-started.md).
|