# aslaf/vulnflask-secureci architecture

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

- Interactive diagram: https://gitdiagram.com/aslaf/vulnflask-secureci
- Repository: https://github.com/aslaf/vulnflask-secureci

## Overview

##### Project Type and Purpose
- This is a full‐stack application (a vulnerable Flask e-commerce demo) wrapped in a comprehensive DevSecOps pipeline.
- Purpose: showcase a secure-by-design CI/CD workflow that shifts left (code scans, threat modeling) and shifts right (DAST, IAST, runtime enforcement).

##### File Structure Analysis
- Top‐Level Directories:
- .github/workflows: CI/CD definitions for each security phase
- app/: Python/Flask web application + HTML templates + SQLite demo DB
- k8s/: Kubernetes manifests (Deployment, Service, OPA Gatekeeper policies)
- iac/: Terraform sample for cloud provisioning
- falco/: Falco runtime rule definitions
- observability/: (likely dashboards, metrics, future expansion)
- scripts/: helpers to aggregate reports and notify Slack
- threat_model/: STRIDE threat register + validator script
- tests/: pytest for basic Flask functionality
- Config & Reports: Dockerfile, requirements.txt, various SBOM and scanner JSON outputs under docs/ and root.

##### README Insights
- 10 security phases, each implemented as GitHub Actions workflows.
- Tools in pipeline: Bandit, Semgrep, pip-audit, Gitleaks, Syft, Trivy, Checkov, OWASP ZAP, custom IAST logger, Falco, OPA Gatekeeper.
- Deployment target: local k3d or AWS EKS, plus live demo on Render.

##### Diagramming the Architecture
a. Main Components
1. Developer Workstation (IDE + Git + Python env)
2. Source Repository (GitHub)
3. CI/CD Platform (GitHub Actions) with parallel/staged workflows:
- Threat Modeling Validator
- SAST/SCA/Secrets Scans
- Container SBOM & CVE Scans
- IaC Scans
- DAST (baseline & live)
- IAST Runtime Logging
- Runtime Policy Enforcement
4. Artifact Stores:
- Docker Image Registry (local k3d or cloud)
- GitHub Artifacts (JSON reports, HTML)
5. Infrastructure:
- Kubernetes Cluster (EKS/k3d) running Flask app
- Terraform‐provisioned cloud resources (S3, VPC, etc.)
6. Runtime Security:
- Falco DaemonSet + Rules
- OPA Gatekeeper + Constraint Templates
7. External/Dev Tools:
- OWASP ZAP container
- Slack/Webhook for notifications
b. Relationships & Data Flows
- Code push triggers GitHub Actions workflows in series/parallel.
- Scanning jobs read source, produce JSON/HTML artifacts.
- Container build pushes image to registry, scanned by Trivy/Syft.
- Deploy job applies Terraform (iac/) then kubectl apply k8s manifests.
- DAST live points to external LoadBalancer URL.
- IAST instrumentation in Flask container emits logs back to CI.
- Falco/OPA intercept syscalls/Pod creations in the cluster.
c. Architectural Patterns & Principles
- “Security as Code”: every control codified in pipelines & IaC
- Layered defense: code → container → infra → runtime
- GitOps for deployments, Immutable infra in Git
- Shift-Left (pre-merge) and Shift-Right (post-deploy) scans
d. Key Technologies & Frameworks
- Flask (app), SQLite (demo DB)
- GitHub Actions (CI/CD)
- Docker, Syft, Trivy (container/SBOM)
- Checkov, Terraform (IaC)
- Kubernetes (EKS/k3d), OPA Gatekeeper
- Falco (runtime)
- OWASP ZAP (DAST), custom IAST Python logger
- Python scripts for threat validation & report aggregation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer"
        Dev["Developer Workstation"]:::external
    end

    subgraph "CI/CD (GitHub Actions)"
        GH["GitHub Actions"]:::compute
        TM["Threat Modeling Validator"]:::security
        SAST["SAST/SCA/Secrets Scans"]:::security
        SBOM["Container SBOM & CVE Scans"]:::security
        IaCScan["IaC Scans"]:::security
        DAST["DAST (OWASP ZAP)"]:::security
        IAST["IAST Runtime Logging"]:::security
        RPE["Runtime Policy Enforcement"]:::security
        Artifacts["GitHub Artifacts"]:::external

        subgraph "Scripts"
            Agg["aggregate_insights.py"]:::compute
            Dash["build_dashboard.py"]:::compute
            Report["generate-report.py"]:::compute
            Notify["notify_slack.py"]:::compute
            Triage["triage_findings.py"]:::compute
        end

        subgraph "Threat Model"
            threats["threats.yml"]:::security
            val["validate_threats.py"]:::compute
        end

        subgraph "Tests"
            test1["test_basic.py"]:::compute
            conftest["conftest.py"]:::compute
        end

        subgraph "Codebase"
            Docker["Dockerfile"]:::infra
            Req["requirements.txt"]:::infra
        end
    end

    subgraph "Registry"
        Registry["Docker Image Registry"]:::infra
    end

    subgraph "Infrastructure"
        Terraform["Terraform IaC"]:::infra
        K8sMan["K8s Manifests"]:::infra
        Cluster["Kubernetes Cluster"]:::infra
    end

    subgraph "Runtime Security"
        AppPod["Flask App Pod"]:::compute
        Falco["Falco DaemonSet"]:::security
        OPA["OPA Gatekeeper"]:::security
        ZAP["OWASP ZAP Container"]:::security
        Slack["Slack Notifications"]:::external
        Obs["Observability Stack"]:::infra
    end

    Dev -->|"git push"| GH
    GH --> TM
    TM --> SAST
    SAST --> SBOM
    SBOM --> IaCScan
    IaCScan --> Registry
    Registry -->|"image"| K8sMan
    K8sMan --> Cluster
    Cluster --> AppPod

    GH --> DAST
    DAST -->|"HTTP attack"| AppPod

    AppPod --> IAST
    GH --> RPE
    RPE --> OPA

    Cluster --> Falco
    Cluster --> OPA
    Cluster --> Obs

    GH --> Artifacts
    Artifacts --> Dev

    GH --> Agg --> Artifacts
    GH --> Dash
    GH --> Report
    GH --> Notify
    GH --> Triage

    GH --> threats --> val --> Artifacts

    GH --> test1 --> Artifacts
    GH --> conftest

    GH --> Docker
    GH --> Req

    AppPod -->|"app logs"| Slack
    ZAP --> AppPod

    click GH "https://github.com/aslaf/vulnflask-secureci/tree/main/.github/workflows/"
    click Agg "https://github.com/aslaf/vulnflask-secureci/blob/main/scripts/aggregate_insights.py"
    click Dash "https://github.com/aslaf/vulnflask-secureci/blob/main/scripts/build_dashboard.py"
    click Report "https://github.com/aslaf/vulnflask-secureci/blob/main/scripts/generate-report.py"
    click Notify "https://github.com/aslaf/vulnflask-secureci/blob/main/scripts/notify_slack.py"
    click Triage "https://github.com/aslaf/vulnflask-secureci/blob/main/scripts/triage_findings.py"
    click threats "https://github.com/aslaf/vulnflask-secureci/blob/main/threat_model/threats.yml"
    click val "https://github.com/aslaf/vulnflask-secureci/blob/main/threat_model/validate_threats.py"
    click test1 "https://github.com/aslaf/vulnflask-secureci/blob/main/tests/test_basic.py"
    click conftest "https://github.com/aslaf/vulnflask-secureci/blob/main/tests/conftest.py"
    click Docker "https://github.com/aslaf/vulnflask-secureci/tree/main/Dockerfile"
    click Req "https://github.com/aslaf/vulnflask-secureci/blob/main/requirements.txt"
    click Terraform "https://github.com/aslaf/vulnflask-secureci/blob/main/iac/main.tf"
    click K8sMan "https://github.com/aslaf/vulnflask-secureci/blob/main/k8s/deployment.yml"
    click OPA "https://github.com/aslaf/vulnflask-secureci/blob/main/k8s/policies/constraint-template.yaml"
    click Falco "https://github.com/aslaf/vulnflask-secureci/blob/main/falco/rules.yaml"
    click Obs "https://github.com/aslaf/vulnflask-secureci/blob/main/observability/docker-compose.yml"
    click AppPod "https://github.com/aslaf/vulnflask-secureci/blob/main/app/app.py"

    classDef compute fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef security fill:#d9ead3,stroke:#333,stroke-width:1px
    classDef infra fill:#fce5cd,stroke:#333,stroke-width:1px
    classDef external fill:#d0e0e3,stroke:#333,stroke-width:1px
```
