# kesavanaswin/cspm architecture

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

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

## Overview

CSPM analyzes container configuration, vulnerability findings, and runtime telemetry, correlates them into risk assessments, then simulates admission decisions and alerts. The primary documented workflow is the modular CLI/Streamlit pipeline; the repository also contains a separate Flask-oriented scan workflow with config auditing, scanner/monitor integrations, and its own risk-scoring modules. The README documents the modular stages; source excerpts show key orchestration and implementation details. Other relationships are limited to imports recorded in the SOURCE INDEX.

Main entry points: [`app.py`](https://github.com/kesavanaswin/cspm/blob/main/app.py) (Flask API), [`main.py`](https://github.com/kesavanaswin/cspm/blob/main/main.py) (CLI runner), [`gui.py`](https://github.com/kesavanaswin/cspm/blob/main/gui.py) (Streamlit dashboard), [`engines/analysis_engine.py`](https://github.com/kesavanaswin/cspm/blob/main/engines/analysis_engine.py) (Policy and anomaly analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI runner<br/>[main.py]"]
  node_streamlit["Streamlit dashboard<br/>[gui.py]"]
  node_flask["Flask API<br/>[app.py]"]
end

subgraph group_pipeline["CSPM Pipeline"]
  node_ingestion["Input ingestion"]
  node_analysis["Policy and anomaly analysis<br/>[analysis_engine.py]"]
  node_risk["Unified risk scoring<br/>[risk_engine.py]"]
  node_mitigation["Admission and alerts"]
end

subgraph group_legacy["Flask Scan Workflow"]
  node_config_audit["Manifest config audit<br/>[config_audit.py]"]
  node_vuln_scan["Image vulnerability scan<br/>[vuln_scan.py]"]
  node_runtime_monitor["Runtime monitoring<br/>[runtime_monitor.py]"]
  node_legacy_risk["Legacy risk correlation<br/>[risk_engine.py]"]
  node_legacy_models["Scan records<br/>[models.py]"]
end

subgraph group_shared["Shared Infrastructure"]
  node_json_store[("JSON persistence<br/>[json_store.py]")]
  node_data_models["Pipeline data models<br/>[models.py]"]
  node_logger["Central logging<br/>[logger.py]"]
end

subgraph group_policy["Policy Inputs"]
  node_policy_yaml["Policy rules<br/>[policies.yaml]"]
  node_rego_policy["Rego policies"]
  node_legacy_config["Scanner and risk config<br/>[config.py]"]
end

node_operator(("Operator"))
node_cluster(("Docker/Kubernetes"))

node_operator -->|"runs analysis"| node_cli
node_operator -->|"views dashboard"| node_streamlit
node_operator -->|"submits scan"| node_flask
node_cluster -.->|"provides state"| node_ingestion
node_cli -->|"loads inputs"| node_ingestion
node_cli -->|"evaluates findings"| node_analysis
node_cli -->|"assesses risk"| node_risk
node_cli -->|"processes assessment"| node_mitigation
node_streamlit -->|"loads inputs"| node_ingestion
node_streamlit -->|"evaluates findings"| node_analysis
node_streamlit -->|"assesses risk"| node_risk
node_streamlit -->|"processes assessment"| node_mitigation
node_ingestion -->|"loads JSON"| node_json_store
node_ingestion -->|"constructs records"| node_data_models
node_analysis -->|"evaluates records"| node_data_models
node_analysis -->|"loads rules"| node_policy_yaml
node_analysis -->|"logs findings"| node_logger
node_risk -->|"scores assessments"| node_data_models
node_mitigation -->|"persists alerts"| node_json_store
node_mitigation -->|"builds alerts"| node_data_models
node_mitigation -->|"logs actions"| node_logger
node_flask -->|"audits manifest"| node_config_audit
node_flask -->|"scans image"| node_vuln_scan
node_flask -->|"checks events"| node_runtime_monitor
node_flask -->|"computes risk"| node_legacy_risk
node_flask -->|"records findings"| node_legacy_models
node_config_audit -->|"reads settings"| node_legacy_config
node_vuln_scan -->|"reads settings"| node_legacy_config
node_runtime_monitor -->|"reads settings"| node_legacy_config
node_legacy_risk -->|"uses weights"| node_legacy_config
node_config_audit -.->|"evaluates policies"| node_rego_policy

click node_cli "https://github.com/kesavanaswin/cspm/blob/main/main.py"
click node_streamlit "https://github.com/kesavanaswin/cspm/blob/main/gui.py"
click node_flask "https://github.com/kesavanaswin/cspm/blob/main/app.py"
click node_ingestion "https://github.com/kesavanaswin/cspm/blob/main/engines/ingestion_engine.py"
click node_analysis "https://github.com/kesavanaswin/cspm/blob/main/engines/analysis_engine.py"
click node_risk "https://github.com/kesavanaswin/cspm/blob/main/engines/risk_engine.py"
click node_mitigation "https://github.com/kesavanaswin/cspm/blob/main/engines/mitigation_engine.py"
click node_config_audit "https://github.com/kesavanaswin/cspm/blob/main/config_audit.py"
click node_vuln_scan "https://github.com/kesavanaswin/cspm/blob/main/vuln_scan.py"
click node_runtime_monitor "https://github.com/kesavanaswin/cspm/blob/main/runtime_monitor.py"
click node_legacy_risk "https://github.com/kesavanaswin/cspm/blob/main/risk_engine.py"
click node_legacy_models "https://github.com/kesavanaswin/cspm/blob/main/models.py"
click node_json_store "https://github.com/kesavanaswin/cspm/blob/main/storage/json_store.py"
click node_data_models "https://github.com/kesavanaswin/cspm/blob/main/utils/models.py"
click node_logger "https://github.com/kesavanaswin/cspm/blob/main/utils/logger.py"
click node_policy_yaml "https://github.com/kesavanaswin/cspm/blob/main/config/policies.yaml"
click node_rego_policy "https://github.com/kesavanaswin/cspm/blob/main/policies/container_security.rego"
click node_legacy_config "https://github.com/kesavanaswin/cspm/blob/main/config.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_cli,node_streamlit,node_flask toneBlue
class node_ingestion,node_analysis,node_risk,node_mitigation toneAmber
class node_config_audit,node_vuln_scan,node_runtime_monitor,node_legacy_risk,node_legacy_models toneMint
class node_json_store,node_data_models,node_logger toneRose
class node_policy_yaml,node_rego_policy,node_legacy_config,node_operator,node_cluster toneIndigo
```

## Components

### User Interfaces

- [CLI runner](https://github.com/kesavanaswin/cspm/blob/main/main.py): `main.py`
- [Streamlit dashboard](https://github.com/kesavanaswin/cspm/blob/main/gui.py): `gui.py`
- [Flask API](https://github.com/kesavanaswin/cspm/blob/main/app.py): `app.py`

### CSPM Pipeline

- [Input ingestion](https://github.com/kesavanaswin/cspm/blob/main/engines/ingestion_engine.py): `engines/ingestion_engine.py`
- [Policy and anomaly analysis](https://github.com/kesavanaswin/cspm/blob/main/engines/analysis_engine.py): `engines/analysis_engine.py`
- [Unified risk scoring](https://github.com/kesavanaswin/cspm/blob/main/engines/risk_engine.py): `engines/risk_engine.py`
- [Admission and alerts](https://github.com/kesavanaswin/cspm/blob/main/engines/mitigation_engine.py): `engines/mitigation_engine.py`

### Flask Scan Workflow

- [Manifest config audit](https://github.com/kesavanaswin/cspm/blob/main/config_audit.py): `config_audit.py`
- [Image vulnerability scan](https://github.com/kesavanaswin/cspm/blob/main/vuln_scan.py): `vuln_scan.py`
- [Runtime monitoring](https://github.com/kesavanaswin/cspm/blob/main/runtime_monitor.py): `runtime_monitor.py`
- [Legacy risk correlation](https://github.com/kesavanaswin/cspm/blob/main/risk_engine.py): `risk_engine.py`
- [Scan records](https://github.com/kesavanaswin/cspm/blob/main/models.py): `models.py`

### Shared Infrastructure

- [JSON persistence](https://github.com/kesavanaswin/cspm/blob/main/storage/json_store.py): `storage/json_store.py`
- [Pipeline data models](https://github.com/kesavanaswin/cspm/blob/main/utils/models.py): `utils/models.py`
- [Central logging](https://github.com/kesavanaswin/cspm/blob/main/utils/logger.py): `utils/logger.py`

### Policy Inputs

- [Policy rules](https://github.com/kesavanaswin/cspm/blob/main/config/policies.yaml): `config/policies.yaml`
- [Rego policies](https://github.com/kesavanaswin/cspm/blob/main/policies/container_security.rego): `policies/container_security.rego`
- [Scanner and risk config](https://github.com/kesavanaswin/cspm/blob/main/config.py): `config.py`

### Other components

- **Operator**
- **Docker/Kubernetes**

## Connections

- Operator → CLI runner: runs analysis (evidence: `README.md`)
- Operator → Streamlit dashboard: views dashboard (evidence: `README.md`)
- Operator → Flask API: submits scan (evidence: `app.py`)
- Docker/Kubernetes → Input ingestion: provides state
- CLI runner → Input ingestion: loads inputs (evidence: `main.py`)
- CLI runner → Policy and anomaly analysis: evaluates findings (evidence: `README.md`)
- CLI runner → Unified risk scoring: assesses risk (evidence: `main.py`)
- CLI runner → Admission and alerts: processes assessment (evidence: `main.py`)
- Streamlit dashboard → Input ingestion: loads inputs (evidence: `gui.py`)
- Streamlit dashboard → Policy and anomaly analysis: evaluates findings (evidence: `gui.py`)
- Streamlit dashboard → Unified risk scoring: assesses risk (evidence: `gui.py`)
- Streamlit dashboard → Admission and alerts: processes assessment (evidence: `gui.py`)
- Input ingestion → JSON persistence: loads JSON (evidence: `engines/ingestion_engine.py`)
- Input ingestion → Pipeline data models: constructs records (evidence: `engines/ingestion_engine.py`)
- Policy and anomaly analysis → Pipeline data models: evaluates records (evidence: `engines/analysis_engine.py`)
- Policy and anomaly analysis → Policy rules: loads rules (evidence: `README.md`)
- Policy and anomaly analysis → Central logging: logs findings (evidence: `engines/analysis_engine.py`)
- Unified risk scoring → Pipeline data models: scores assessments (evidence: `engines/risk_engine.py`)
- Admission and alerts → JSON persistence: persists alerts (evidence: `engines/mitigation_engine.py`)
- Admission and alerts → Pipeline data models: builds alerts (evidence: `engines/mitigation_engine.py`)
- Admission and alerts → Central logging: logs actions (evidence: `engines/mitigation_engine.py`)
- Flask API → Manifest config audit: audits manifest (evidence: `app.py`)
- Flask API → Image vulnerability scan: scans image (evidence: `app.py`)
- Flask API → Runtime monitoring: checks events (evidence: `app.py`)
- Flask API → Legacy risk correlation: computes risk (evidence: `app.py`)
- Flask API → Scan records: records findings (evidence: `app.py`)
- Manifest config audit → Scanner and risk config: reads settings (evidence: `config_audit.py`)
- Image vulnerability scan → Scanner and risk config: reads settings (evidence: `vuln_scan.py`)
- Runtime monitoring → Scanner and risk config: reads settings (evidence: `runtime_monitor.py`)
- Legacy risk correlation → Scanner and risk config: uses weights (evidence: `risk_engine.py`)
- Manifest config audit → Rego policies: evaluates policies
