# dashboardtobie/kubedeceive architecture

> Architecture diagram of the GitHub repository dashboardtobie/kubedeceive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dashboardtobie/kubedeceive
- Repository: https://github.com/dashboardtobie/kubedeceive

## Overview

KubeDeceive is a Kubernetes deception system. Its main loop detects Falco events, decides whether to respond, deploys a Cowrie honeypod, redirects production traffic, and restores the service after the honeypod TTL; Falcosidekick and Wazuh provide event routing and SOC visibility. The controller source is only partially excerpted, so internal actions are separated only where shown or explicitly documented. Other integrations and SOC capabilities follow the README’s architecture description.

Main entry points: [`chart/files/controller.py`](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py) (Event handler), [`soc/docker-compose.yml`](https://github.com/dashboardtobie/kubedeceive/blob/main/soc/docker-compose.yml) (Wazuh SOC), [`falco/values.yaml.tpl`](https://github.com/dashboardtobie/kubedeceive/blob/main/falco/values.yaml.tpl) (Falcosidekick), [`demo/ssh-prod.yaml`](https://github.com/dashboardtobie/kubedeceive/blob/main/demo/ssh-prod.yaml) (Production service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection and routing"]
  node_falco["Falco detection<br/>[values.yaml.tpl]"]
  node_sidekick["Falcosidekick<br/>[values.yaml.tpl]"]
end

subgraph group_response["Controller response"]
  node_controller["Event handler<br/>[controller.py]"]
  node_decision["Contextual decision<br/>[controller.py]"]
  node_dedup[("Deduplication state<br/>[controller.py]")]
  node_deploy["Honeypod deployment<br/>[controller.py]"]
  node_redirect["Traffic redirection<br/>[controller.py]"]
  node_restore["TTL restoration<br/>[controller.py]"]
end

subgraph group_cluster["Cluster resources"]
  node_production["Production service<br/>[ssh-prod.yaml]"]
  node_cowrie["Cowrie honeypod<br/>[values.yaml]"]
  node_endpoints[("EndpointSlice<br/>[controller.py]")]
  node_kubernetes["Kubernetes API"]
end

subgraph group_soc["Security operations"]
  node_wazuh["Wazuh SOC<br/>[docker-compose.yml]"]
  node_decoder["Event decoder<br/>[local_decoder.xml]"]
  node_rules["SOC rules<br/>[local_rules.xml]"]
  node_syslog["Syslog receiver<br/>[enable-syslog.sh]"]
end

node_attacker(("Attacker"))

node_attacker -->|"accesses"| node_production
node_production -->|"observed by"| node_falco
node_falco -->|"sends event"| node_sidekick
node_sidekick -->|"webhook"| node_controller
node_sidekick -->|"routes syslog"| node_syslog
node_syslog -->|"forwards events"| node_wazuh
node_controller -->|"evaluates event"| node_decision
node_decision -->|"checks recent"| node_dedup
node_controller -->|"creates pod"| node_deploy
node_deploy -->|"deploys"| node_cowrie
node_controller -->|"redirects traffic"| node_redirect
node_redirect -->|"creates slice"| node_endpoints
node_controller -->|"manages resources"| node_kubernetes
node_controller -->|"schedules TTL"| node_restore
node_restore -->|"restores service"| node_kubernetes
node_restore -->|"deletes slice"| node_endpoints
node_cowrie -.->|"feeds captured activity"| node_wazuh
node_wazuh -->|"uses decoder"| node_decoder
node_wazuh -->|"applies rules"| node_rules

click node_production "https://github.com/dashboardtobie/kubedeceive/blob/main/demo/ssh-prod.yaml"
click node_falco "https://github.com/dashboardtobie/kubedeceive/blob/main/falco/values.yaml.tpl"
click node_sidekick "https://github.com/dashboardtobie/kubedeceive/blob/main/falco/values.yaml.tpl"
click node_controller "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_decision "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_dedup "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_deploy "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_cowrie "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/values.yaml"
click node_redirect "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_endpoints "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_restore "https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py"
click node_wazuh "https://github.com/dashboardtobie/kubedeceive/blob/main/soc/docker-compose.yml"
click node_decoder "https://github.com/dashboardtobie/kubedeceive/blob/main/soc/decoders/local_decoder.xml"
click node_rules "https://github.com/dashboardtobie/kubedeceive/blob/main/soc/rules/local_rules.xml"
click node_syslog "https://github.com/dashboardtobie/kubedeceive/blob/main/soc/enable-syslog.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_falco,node_sidekick toneBlue
class node_controller,node_decision,node_dedup,node_deploy,node_redirect,node_restore toneAmber
class node_production,node_cowrie,node_endpoints,node_kubernetes toneMint
class node_wazuh,node_decoder,node_rules,node_syslog toneRose
class node_attacker toneIndigo
```

## Components

### Detection and routing

- [Falco detection](https://github.com/dashboardtobie/kubedeceive/blob/main/falco/values.yaml.tpl): `falco/values.yaml.tpl`
- [Falcosidekick](https://github.com/dashboardtobie/kubedeceive/blob/main/falco/values.yaml.tpl): `falco/values.yaml.tpl`

### Controller response

- [Event handler](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`
- [Contextual decision](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`
- [Deduplication state](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`
- [Honeypod deployment](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`
- [Traffic redirection](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`
- [TTL restoration](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`

### Cluster resources

- [Production service](https://github.com/dashboardtobie/kubedeceive/blob/main/demo/ssh-prod.yaml): `demo/ssh-prod.yaml`
- [Cowrie honeypod](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/values.yaml): `chart/values.yaml`
- [EndpointSlice](https://github.com/dashboardtobie/kubedeceive/blob/main/chart/files/controller.py): `chart/files/controller.py`
- **Kubernetes API**

### Security operations

- [Wazuh SOC](https://github.com/dashboardtobie/kubedeceive/blob/main/soc/docker-compose.yml): `soc/docker-compose.yml`
- [Event decoder](https://github.com/dashboardtobie/kubedeceive/blob/main/soc/decoders/local_decoder.xml): `soc/decoders/local_decoder.xml`
- [SOC rules](https://github.com/dashboardtobie/kubedeceive/blob/main/soc/rules/local_rules.xml): `soc/rules/local_rules.xml`
- [Syslog receiver](https://github.com/dashboardtobie/kubedeceive/blob/main/soc/enable-syslog.sh): `soc/enable-syslog.sh`

### Other components

- **Attacker**

## Connections

- Attacker → Production service: accesses (evidence: `README.md`)
- Production service → Falco detection: observed by (evidence: `README.md`)
- Falco detection → Falcosidekick: sends event (evidence: `README.md`)
- Falcosidekick → Event handler: webhook (evidence: `README.md`)
- Falcosidekick → Syslog receiver: routes syslog (evidence: `README.md`)
- Syslog receiver → Wazuh SOC: forwards events (evidence: `README.md`)
- Event handler → Contextual decision: evaluates event (evidence: `chart/files/controller.py`)
- Contextual decision → Deduplication state: checks recent (evidence: `chart/files/controller.py`)
- Event handler → Honeypod deployment: creates pod (evidence: `chart/files/controller.py`)
- Honeypod deployment → Cowrie honeypod: deploys (evidence: `README.md`)
- Event handler → Traffic redirection: redirects traffic (evidence: `README.md`)
- Traffic redirection → EndpointSlice: creates slice (evidence: `chart/files/controller.py`)
- Event handler → Kubernetes API: manages resources (evidence: `chart/files/controller.py`)
- Event handler → TTL restoration: schedules TTL (evidence: `chart/files/controller.py`)
- TTL restoration → Kubernetes API: restores service (evidence: `chart/files/controller.py`)
- TTL restoration → EndpointSlice: deletes slice (evidence: `chart/files/controller.py`)
- Cowrie honeypod → Wazuh SOC: feeds captured activity (evidence: `README.md`)
- Wazuh SOC → Event decoder: uses decoder (evidence: `README.md`)
- Wazuh SOC → SOC rules: applies rules (evidence: `README.md`)