# kesavanaswin/cspmr architecture

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

- Interactive diagram: https://gitdiagram.com/kesavanaswin/cspmr
- Repository: https://github.com/kesavanaswin/cspmr

## Overview

CSPMR is a container security posture monitoring tool. Its main runtime discovers Docker containers, scans their images, and combines policy findings with Falco runtime events to assess risk, write a report, and raise alerts. A separate Kubernetes admission webhook evaluates Pods before admission; a realtime dashboard is also present in the tree. The README provides no capability details, and the dashboard and several runtime modules were not excerpted, so their internal behavior and connections are not inferred.

Main entry points: [`realtime_cspm.py`](https://github.com/kesavanaswin/cspmr/blob/main/realtime_cspm.py) (Realtime runner), [`utils/models.py`](https://github.com/kesavanaswin/cspmr/blob/main/utils/models.py) (CSPM data models), [`integrations/trivy_adapter.py`](https://github.com/kesavanaswin/cspmr/blob/main/integrations/trivy_adapter.py) (Trivy adapter), [`admission_webhook.py`](https://github.com/kesavanaswin/cspmr/blob/main/admission_webhook.py) (Admission webhook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Runtime collection"]
  node_runner["Realtime runner<br/>[realtime_cspm.py]"]
  node_docker["Docker collector<br/>[docker_events.py]"]
  node_falco["Falco stream<br/>[falco_stream.py]"]
  node_trivy_adapter["Trivy adapter<br/>[trivy_adapter.py]"]
  node_vuln_scan["Image scanner<br/>[vuln_scan.py]"]
end

subgraph group_analysis["Posture analysis"]
  node_policy["Policy engine<br/>[analysis_engine.py]"]
  node_anomaly["Anomaly detector<br/>[analysis_engine.py]"]
  node_risk["Risk engine<br/>[risk_engine.py]"]
end

subgraph group_response["Reporting and response"]
  node_mitigation["Mitigation engine"]
  node_notifier["Webhook notifier<br/>[notifications.py]"]
  node_report["Risk report<br/>[risk_report.json]"]
  node_dashboard["Realtime dashboard"]
  node_admission["Admission webhook"]
end

subgraph group_shared["Shared data"]
  node_policies["Policy configuration<br/>[policies.yaml]"]
  node_models["CSPM data models<br/>[models.py]"]
end

node_operator(("Operator"))

node_operator -.->|"starts"| node_runner
node_runner -->|"collects state"| node_docker
node_runner -->|"reads events"| node_falco
node_runner -->|"scans containers"| node_trivy_adapter
node_trivy_adapter -->|"scans image"| node_vuln_scan
node_runner -->|"evaluates posture"| node_policy
node_runner -->|"scores events"| node_anomaly
node_runner -->|"assesses risk"| node_risk
node_runner -->|"creates alerts"| node_mitigation
node_runner -->|"sends alerts"| node_notifier
node_runner -->|"writes report"| node_report
node_runner -->|"sets policy path"| node_policies
node_admission -->|"evaluates Pod"| node_policy
node_admission -->|"assesses Pod"| node_risk
node_docker -->|"creates config"| node_models
node_falco -->|"creates events"| node_models
node_trivy_adapter -->|"creates findings"| node_models
node_mitigation -->|"creates alerts"| node_models

click node_runner "https://github.com/kesavanaswin/cspmr/blob/main/realtime_cspm.py"
click node_docker "https://github.com/kesavanaswin/cspmr/blob/main/integrations/docker_events.py"
click node_falco "https://github.com/kesavanaswin/cspmr/blob/main/integrations/falco_stream.py"
click node_trivy_adapter "https://github.com/kesavanaswin/cspmr/blob/main/integrations/trivy_adapter.py"
click node_vuln_scan "https://github.com/kesavanaswin/cspmr/blob/main/vuln_scan.py"
click node_policy "https://github.com/kesavanaswin/cspmr/blob/main/engines/analysis_engine.py"
click node_anomaly "https://github.com/kesavanaswin/cspmr/blob/main/engines/analysis_engine.py"
click node_risk "https://github.com/kesavanaswin/cspmr/blob/main/engines/risk_engine.py"
click node_mitigation "https://github.com/kesavanaswin/cspmr/blob/main/engines/mitigation_engine.py"
click node_notifier "https://github.com/kesavanaswin/cspmr/blob/main/integrations/notifications.py"
click node_report "https://github.com/kesavanaswin/cspmr/blob/main/output/risk_report.json"
click node_dashboard "https://github.com/kesavanaswin/cspmr/blob/main/dashboard_realtime.py"
click node_admission "https://github.com/kesavanaswin/cspmr/blob/main/admission_webhook.py"
click node_policies "https://github.com/kesavanaswin/cspmr/blob/main/config/policies.yaml"
click node_models "https://github.com/kesavanaswin/cspmr/blob/main/utils/models.py"

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_runner,node_docker,node_falco,node_trivy_adapter,node_vuln_scan toneBlue
class node_policy,node_anomaly,node_risk toneAmber
class node_mitigation,node_notifier,node_report,node_dashboard,node_admission toneMint
class node_policies,node_models toneRose
class node_operator toneIndigo
```

## Components

### Runtime collection

- [Realtime runner](https://github.com/kesavanaswin/cspmr/blob/main/realtime_cspm.py): `realtime_cspm.py`
- [Docker collector](https://github.com/kesavanaswin/cspmr/blob/main/integrations/docker_events.py): `integrations/docker_events.py`
- [Falco stream](https://github.com/kesavanaswin/cspmr/blob/main/integrations/falco_stream.py): `integrations/falco_stream.py`
- [Trivy adapter](https://github.com/kesavanaswin/cspmr/blob/main/integrations/trivy_adapter.py): `integrations/trivy_adapter.py`
- [Image scanner](https://github.com/kesavanaswin/cspmr/blob/main/vuln_scan.py): `vuln_scan.py`

### Posture analysis

- [Policy engine](https://github.com/kesavanaswin/cspmr/blob/main/engines/analysis_engine.py): `engines/analysis_engine.py`
- [Anomaly detector](https://github.com/kesavanaswin/cspmr/blob/main/engines/analysis_engine.py): `engines/analysis_engine.py`
- [Risk engine](https://github.com/kesavanaswin/cspmr/blob/main/engines/risk_engine.py): `engines/risk_engine.py`

### Reporting and response

- [Mitigation engine](https://github.com/kesavanaswin/cspmr/blob/main/engines/mitigation_engine.py): `engines/mitigation_engine.py`
- [Webhook notifier](https://github.com/kesavanaswin/cspmr/blob/main/integrations/notifications.py): `integrations/notifications.py`
- [Risk report](https://github.com/kesavanaswin/cspmr/blob/main/output/risk_report.json): `output/risk_report.json`
- [Realtime dashboard](https://github.com/kesavanaswin/cspmr/blob/main/dashboard_realtime.py): `dashboard_realtime.py`
- [Admission webhook](https://github.com/kesavanaswin/cspmr/blob/main/admission_webhook.py): `admission_webhook.py`

### Shared data

- [Policy configuration](https://github.com/kesavanaswin/cspmr/blob/main/config/policies.yaml): `config/policies.yaml`
- [CSPM data models](https://github.com/kesavanaswin/cspmr/blob/main/utils/models.py): `utils/models.py`

### Other components

- **Operator**

## Connections

- Operator → Realtime runner: starts
- Realtime runner → Docker collector: collects state (evidence: `realtime_cspm.py`)
- Realtime runner → Falco stream: reads events (evidence: `realtime_cspm.py`)
- Realtime runner → Trivy adapter: scans containers (evidence: `realtime_cspm.py`)
- Trivy adapter → Image scanner: scans image (evidence: `integrations/trivy_adapter.py`)
- Realtime runner → Policy engine: evaluates posture (evidence: `realtime_cspm.py`)
- Realtime runner → Anomaly detector: scores events (evidence: `realtime_cspm.py`)
- Realtime runner → Risk engine: assesses risk (evidence: `realtime_cspm.py`)
- Realtime runner → Mitigation engine: creates alerts (evidence: `realtime_cspm.py`)
- Realtime runner → Webhook notifier: sends alerts (evidence: `realtime_cspm.py`)
- Realtime runner → Risk report: writes report (evidence: `realtime_cspm.py`)
- Realtime runner → Policy configuration: sets policy path (evidence: `realtime_cspm.py`)
- Admission webhook → Policy engine: evaluates Pod (evidence: `admission_webhook.py`)
- Admission webhook → Risk engine: assesses Pod (evidence: `admission_webhook.py`)
- Docker collector → CSPM data models: creates config (evidence: `integrations/docker_events.py`)
- Falco stream → CSPM data models: creates events (evidence: `integrations/falco_stream.py`)
- Trivy adapter → CSPM data models: creates findings (evidence: `integrations/trivy_adapter.py`)
- Mitigation engine → CSPM data models: creates alerts (evidence: `engines/mitigation_engine.py`)
