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