charybdis/README.md

# Charybdis

**The 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.

## Why Charybdis?

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.

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.**

## 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
```

The entity is stored, events are fired, and plugins react automatically.

## 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:

```
EntityCreated ──> Event Bus ──> DefectDojo Plugin ──> Creates product
                            ──> Slack Plugin ──> Notifies channel (planned)
                            ──> Custom Plugin ──> Your logic
```

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)

**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

Build your own with the `EventDrivenPlugin` or `SyncPlugin` traits.

## Backstage Compatibility

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:

```yaml
# backstage app-config.yaml
catalog:
  locations:
    - type: url
      target: http://charybdis:8080/yaml/locations
      rules:
        - allow: [Component, System, Service, API, User, Group]
```

Or use Charybdis standalone via its gRPC API — no Backstage needed.

## 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.

## 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
- [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

## 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) |

## Contributing

Contributions are welcome! Whether it's a new plugin, a security parser, or documentation improvements — we'd love your help.

## License

[Apache-2.0](LICENSE)

---

**One platform. Catalog. Security. Compliance. Built in Rust.**