# aquasecurity/kube-bench architecture

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

- Interactive diagram: https://gitdiagram.com/aquasecurity/kube-bench
- Repository: https://github.com/aquasecurity/kube-bench

## Overview

##### Project type and purpose
- kube‑bench is an open‑source, Go‑based CLI tool that implements the CIS Kubernetes Benchmark.
- Its purpose is to read YAML “control” definitions, run checks against a live or local Kubernetes installation (via host file system, process namespace, or API), and emit a pass/fail report (console, JSON, ASFF, etc.).

##### File structure
- Top‑level directories of interest:
- cmd/     → CLI entrypoints and flag parsing
- check/   → Core engine that loads controls, runs tests
- internal/findings → Formatting and publishing results
- cfg/     → YAML test definitions organized by platform & version
- docs/    → mkdocs‑based documentation
- Dockerfile & Dockerfile.* → Container image build
- .github/workflows → CI/CD pipelines
- Configuration files (cfg/*.yaml) drive test discovery; code in check/ and cmd/ operate on that data.
- CI/CD files automate builds, tests, releases, and Docker publishing.

##### README
- Confirms that kube‑bench auto‑selects the correct benchmark version based on the running Kubernetes version.
- Notes multiple execution modes: local binary or Kubernetes Job (job.yaml).

##### Key points
- Be very detailed: capture every major Go package and its responsibility.
- How configuration drives the engine.
- Both local and in‑cluster execution paths.
- Do not omit the CI/CD and container‑build aspects—they are vital for an open‑source delivery.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Functionality Pipeline
    subgraph "User / Job"
        User["User / Job Trigger"]:::external
    end

    subgraph "CLI Layer" 
        direction TB
        Root["root.go"]:::code
        Run["run.go"]:::code
        Version["version.go"]:::code
        SecurityHubCmd["securityHub.go"]:::code
    end

    subgraph "Configuration Loader"
        CFG["cfg/ <platform>-<version>"]:::data
    end

    subgraph "Check Engine"
        direction TB
        Controls["controls.go"]:::code
        CheckCore["check.go"]:::code
        TestFuncs["test.go"]:::code
    end

    subgraph "Findings Publisher"
        Publisher["publisher.go"]:::code
    end

    subgraph "Output Sink"
        Console["Console / Stdout"]:::external
        JSON["JSON / ASFF"]:::external
        SecurityHubAPI["Security Hub API"]:::external
    end

    %% External Dependencies
    subgraph "External Systems"
        HostFS["Host File System & Proc Namespace"]:::external
        KubeAPI["Kubernetes API"]:::external
    end

    %% Core Pipeline Connections
    User -->|"invokes CLI"| Root
    Root -->|parses flags| Run
    Run -->|"select mode"| CFG
    CFG -->|"YAML definitions"| Controls
    Controls -->|load controls| CheckCore
    CheckCore -->|"invoke tests"| TestFuncs
    TestFuncs -->|"raw results"| Publisher
    Publisher -->|"formatted report"| Console
    Publisher -->|"formatted report"| JSON
    Run -->|"security output"| SecurityHubCmd
    SecurityHubCmd -->|"send report"| SecurityHubAPI

    %% In-cluster execution dependencies
    Run -->|"in-cluster mode"| KubeAPI
    CheckCore -->|"access volumes"| HostFS
    CheckCore -->|"query api"| KubeAPI

    %% CI/CD and Delivery
    subgraph "CI/CD Pipeline" 
        BuildYML["build.yml"]:::external
        TestYML["publish.yml"]:::external
        ReleaseYML["release.yml"]:::external
        MkdocsDeploy["mkdocs-deploy.yaml"]:::external
    end

    subgraph "Container Image Build"
        DockerfileMain["Dockerfile"]:::code
        DockerfileFIPS["Dockerfile.fips.ubi"]:::code
        DockerfileUBI["Dockerfile.ubi"]:::code
        Entrypoint["entrypoint.sh"]:::code
    end

    subgraph "Documentation"
        DocsDir["docs/"]:::data
        MkdocsCfg["mkdocs.yml"]:::data
    end

    subgraph "Other Assets"
        IntegrationTests["integration/testdata/"]:::data
        HackManifests["hack/"]:::data
        JobManifests["job*.yaml"]:::data
        GoMod["go.mod & go.sum"]:::code
    end

    %% CI/CD flows
    BuildYML -->|build/test| DockerfileMain
    BuildYML --> DockerfileFIPS
    BuildYML --> DockerfileUBI
    BuildYML --> Entrypoint
    TestYML --> IntegrationTests
    ReleaseYML -->|release binaries| GoMod
    MkdocsDeploy -->|deploy docs| DocsDir

    %% Click Events
    click Root "https://github.com/aquasecurity/kube-bench/blob/main/cmd/root.go"
    click Run "https://github.com/aquasecurity/kube-bench/blob/main/cmd/run.go"
    click Version "https://github.com/aquasecurity/kube-bench/blob/main/cmd/version.go"
    click SecurityHubCmd "https://github.com/aquasecurity/kube-bench/blob/main/cmd/securityHub.go"
    click CFG "https://github.com/aquasecurity/kube-bench/tree/main/cfg/"
    click Controls "https://github.com/aquasecurity/kube-bench/blob/main/check/controls.go"
    click CheckCore "https://github.com/aquasecurity/kube-bench/blob/main/check/check.go"
    click TestFuncs "https://github.com/aquasecurity/kube-bench/blob/main/check/test.go"
    click Publisher "https://github.com/aquasecurity/kube-bench/blob/main/internal/findings/publisher.go"
    click BuildYML "https://github.com/aquasecurity/kube-bench/blob/main/.github/workflows/build.yml"
    click TestYML "https://github.com/aquasecurity/kube-bench/blob/main/.github/workflows/publish.yml"
    click ReleaseYML "https://github.com/aquasecurity/kube-bench/blob/main/.github/workflows/release.yml"
    click MkdocsDeploy "https://github.com/aquasecurity/kube-bench/blob/main/.github/workflows/mkdocs-deploy.yaml"
    click DockerfileMain "https://github.com/aquasecurity/kube-bench/tree/main/Dockerfile"
    click DockerfileFIPS "https://github.com/aquasecurity/kube-bench/blob/main/Dockerfile.fips.ubi"
    click DockerfileUBI "https://github.com/aquasecurity/kube-bench/blob/main/Dockerfile.ubi"
    click Entrypoint "https://github.com/aquasecurity/kube-bench/blob/main/entrypoint.sh"
    click DocsDir "https://github.com/aquasecurity/kube-bench/tree/main/docs/"
    click MkdocsCfg "https://github.com/aquasecurity/kube-bench/blob/main/mkdocs.yml"
    click IntegrationTests "https://github.com/aquasecurity/kube-bench/tree/main/integration/testdata"
    click HackManifests "https://github.com/aquasecurity/kube-bench/tree/main/hack/"
    click JobManifests "https://github.com/aquasecurity/kube-bench/blob/main/job.yaml"
    click GoMod "https://github.com/aquasecurity/kube-bench/blob/main/go.mod"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFF59D,stroke:#000,stroke-width:1px
```
