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