initial-commit

2026-05-12 17:06:43 +02:00
commit 051a080dfa
110 changed files with 26377 additions and 0 deletions
@@ -0,0 +1,297 @@
+# Charybdis Demo
+
+See the full flow in action: register a service via one gRPC call and watch DefectDojo auto-provision a product — no YAML files, no manual steps. Optionally, see how Backstage can consume entities from Charybdis in real-time via the YAML adapter.
+
+## Prerequisites
+
+- Docker & Docker Compose
+- 8GB RAM recommended
+- Ports available: 5432, 8080, 8081, 50051 (and 3000 if using Backstage)
+
+## Quick Start (5 minutes)
+
+### 1. Start the demo stack
+
+```bash
+./demo.sh
+```
+
+This will start:
+- ✅ Charybdis (gRPC on :50051, YAML adapter on :8081)
+- ✅ DefectDojo (UI on :8080)
+- ✅ PostgreSQL instances for each service
+- ℹ️ Backstage (UI on :3000) — optional, see [Backstage Integration](#optional-backstage-integration) below
+
+### 2. Create your first service
+
+Using grpcurl (if installed):
+
+```bash
+grpcurl -plaintext -d '{
+  "entity": {
+    "kind": "Component",
+    "component_metadata": {
+      "name": "payment-api",
+      "description": "Payment processing service",
+      "labels": {
+        "team": "payments",
+        "env": "production"
+      },
+      "tags": ["api", "critical"]
+    },
+    "component_spec": {
+      "type": "service",
+      "lifecycle": "production",
+      "owner": "team-payments"
+    }
+  }
+}' localhost:50051 charybdis.entities.EntityService/CreateEntity
+```
+
+Or using the included grpcurl container:
+
+```bash
+docker-compose -f docker-compose.demo.yml run --rm 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
+```
+
+### 3. See the magic happen! ✨
+
+**In DefectDojo** (http://localhost:8080):
+- Login: `admin` / `admin`
+- Go to "Products"
+- You'll see "payment-api" automatically created! 🎉
+
+**In Charybdis** (via gRPC):
+- Query the entity back — it now has annotations:
+  - `defectdojo.com/product-id`
+  - `defectdojo.com/engagement-id` (if auto-create enabled)
+
+**In the YAML adapter** (http://localhost:8081):
+- Visit `http://localhost:8081/yaml/locations` — entities are served in Backstage-compatible YAML format
+- Any Backstage instance pointed at this URL will pick up entities automatically
+
+## What just happened?
+
+```
+1. You created a Component entity in Charybdis (gRPC API)
+2. Charybdis stored it in PostgreSQL
+3. Event published: EntityCreated(Component)
+4. DefectDojo plugin received the event
+5. Plugin created a Product in DefectDojo via API
+6. Plugin stored the product_id in entity annotations
+7. Entity is now queryable via gRPC and available via YAML adapter
+```
+
+**30 seconds instead of 30 minutes of manual provisioning — no YAML files, no manual tool setup.**
+
+## Try more operations
+
+### List all entities
+
+```bash
+grpcurl -plaintext -d '{}' localhost:50051 \
+  charybdis.entities.EntityService/ListEntities
+```
+
+### Get a specific entity
+
+```bash
+grpcurl -plaintext -d '{"id": "YOUR_ENTITY_ID"}' localhost:50051 \
+  charybdis.entities.EntityService/GetEntity
+```
+
+### Update an entity
+
+```bash
+grpcurl -plaintext -d '{
+  "id": "YOUR_ENTITY_ID",
+  "entity": {
+    "kind": "Component",
+    "component_metadata": {
+      "name": "payment-api",
+      "description": "Updated description"
+    }
+  }
+}' localhost:50051 charybdis.entities.EntityService/UpdateEntity
+```
+
+→ Check DefectDojo: Product description updated automatically!
+
+### Delete an entity
+
+```bash
+grpcurl -plaintext -d '{"id": "YOUR_ENTITY_ID"}' localhost:50051 \
+  charybdis.entities.EntityService/DeleteEntity
+```
+
+→ Check DefectDojo: Product deleted automatically!
+
+## Explore the stack
+
+### Check Charybdis logs
+
+```bash
+docker-compose -f docker-compose.demo.yml logs -f charybdis
+```
+
+You'll see:
+- Entity CRUD operations
+- Event dispatching
+- Plugin execution
+- DefectDojo API calls
+
+### Check DefectDojo
+
+Open http://localhost:8080
+- Login: `admin` / `admin`
+- Products: See auto-created products
+- Engagements: See auto-created CI/CD engagements
+
+### Check the YAML Adapter
+
+```bash
+# List all entity locations (Backstage-compatible format)
+curl http://localhost:8081/yaml/locations
+```
+
+This endpoint serves entities as Backstage-compatible YAML — useful for Backstage integration or any tool that consumes this format.
+
+### Access databases
+
+**Charybdis database:**
+```bash
+docker-compose -f docker-compose.demo.yml exec postgres-charybdis \
+  psql -U charybdis -d charybdis
+```
+
+**Query entities:**
+```sql
+SELECT id, kind, annotations FROM entities;
+```
+
+## Troubleshooting
+
+### Services not starting
+
+Check logs:
+```bash
+docker-compose -f docker-compose.demo.yml logs
+```
+
+### DefectDojo API token issue
+
+Manually get a token:
+1. Open http://localhost:8080
+2. Login: `admin` / `admin`
+3. Go to Settings → API Key
+4. Copy the token
+5. Update `.env`: `DEFECTDOJO_API_TOKEN=your-token`
+6. Restart: `docker-compose -f docker-compose.demo.yml restart charybdis`
+
+### Port conflicts
+
+If ports are already in use, edit `docker-compose.demo.yml` to change:
+- `3000:3000` → `3001:3000` (Backstage)
+- `8080:8080` → `8082:8080` (DefectDojo)
+- etc.
+
+## Clean up
+
+### Stop services
+
+```bash
+docker-compose -f docker-compose.demo.yml down
+```
+
+### Remove all data
+
+```bash
+docker-compose -f docker-compose.demo.yml down -v
+```
+
+## Optional: Backstage Integration
+
+If you use Backstage, point it at the Charybdis YAML adapter to replace static `catalog-info.yaml` files:
+
+```yaml
+# backstage app-config.yaml
+catalog:
+  locations:
+    - type: url
+      target: http://charybdis:8081/yaml/locations
+      rules:
+        - allow: [Component, System, Service, API, User, Group]
+```
+
+Backstage will discover all entities from Charybdis automatically. See the `docker-compose.demo.yml` file for the commented-out Backstage service if you want to run it as part of the demo stack.
+
+## Next Steps
+
+1. **Read the docs**: [Getting Started](../docs/getting-started.md)
+2. **Understand the architecture**: [Architecture](../docs/architecture.md)
+3. **Create your own plugin**: [Plugin Guide](../plugins/README.md)
+
+## Demo Architecture
+
+```
+┌─────────────┐
+│   Client    │ (grpcurl / CI/CD)
+│  (gRPC)     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────────┐
+│          Charybdis                  │
+│  ┌─────────────┐  ┌──────────────┐ │
+│  │ gRPC API    │  │ YAML Adapter │ │
+│  │  :50051     │  │   :8081      │ │
+│  └──────┬──────┘  └──────┬───────┘ │
+│         │                │          │
+│  ┌──────▼────────────────▼───────┐ │
+│  │     Entity Repository         │ │
+│  │      (PostgreSQL)              │ │
+│  └──────┬────────────────────────┘ │
+│         │                           │
+│  ┌──────▼────────┐                 │
+│  │  Event Bus    │                 │
+│  └──────┬────────┘                 │
+│         │                           │
+│  ┌──────▼────────────────┐         │
+│  │  Plugin Dispatcher    │         │
+│  │  ┌─────────────────┐  │         │
+│  │  │ DefectDojo      │  │         │
+│  │  │ Plugin          │  │         │
+│  │  └─────────────────┘  │         │
+│  └───────────────────────┘         │
+└──────┬──────────────┬───────────────┘
+       │              │
+       ▼              ▼ (YAML Adapter)
+┌──────────────┐  ┌────────────────────┐
+│  DefectDojo  │  │  Backstage / Any   │
+│    :8080     │  │  compatible UI     │
+└──────────────┘  └────────────────────┘
+```
+
+## Support
+
+- GitHub Issues: [github.com/charybdis-catalog/charybdis/issues](https://github.com/charybdis-catalog/charybdis/issues)
+- Documentation: [docs/](docs/)
+- Discord: [Join our community](https://discord.gg/...)
+
+---
+
+**🎉 Welcome to automated DevSecOps orchestration with Charybdis!**