initial-commit

2026-05-12 17:06:43 +02:00
commit 051a080dfa
110 changed files with 26377 additions and 0 deletions
@@ -0,0 +1,125 @@
+# 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).