# cdk-team/cdk architecture

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

- Interactive diagram: https://gitdiagram.com/cdk-team/cdk
- Repository: https://github.com/cdk-team/cdk

## Overview

##### Project Type and Purpose
- The project is an open-source container penetration toolkit written in Go. Its purpose is to provide container exploitation, evaluation, and various network tools to help security testing in containerized environments (especially for Kubernetes).
- The README clearly outlines three main modules – Evaluate, Exploit, and Tool – each with its own commands and capabilities. It even demonstrates how users can run “cdk eva” for evaluation and “cdk run” for launching exploits.

##### Analyzing the File Structure
- Top-Level Directories:
- cmd: Contains command-line entry points. Notably, cmd/cdk/cdk.go is likely the main executable that initializes the application.
- conf: Holds configuration files and functions. It appears to contain various configuration logic (e.g., build, evaluate, exploit, scanner) used to manage settings for different modules.
- pkg: Contains the bulk of the code and is organized into several sub-packages:
◦ cli: Handles command-line banner presentation and argument parsing.
◦ evaluate: Implements information-gathering and vulnerability evaluation functionalities.
◦ exploit: Contains various subdirectories further subdivided by exploit types (e.g., privilege escalation, remote control, discovery, credential access, etc.).
◦ tool: Provides implementations of network tools (e.g., docker handling, netcat, netstat, kubectl wrappers, probe, etc.).
◦ util: Utility functions and helper libraries shared among the modules.
◦ task, plugin, errors: Implement auxiliary functionality, custom error handling, plugin interface, and task execution.
- test: Contains test scripts and deployments that simulate target scenarios like Kubernetes exploit tests.
- Other Files:
- GitHub workflow configurations, change logs, and script files support Continuous Integration/Continuous Delivery, and a “thanks.md” for contributor acknowledgments.

##### Architectural Modules and Their Interactions
- Main Components:
- CLI Layer (pkg/cli, cmd/): Serves as the user interface for invoking commands like evaluation, exploitation, and tool usage.
- Evaluate Module (pkg/evaluate): Encapsulates the logic for system assessment inside a container by running various information-gathering scripts.
- Exploit Module (pkg/exploit): Contains segregated sub-packages that provide different techniques to escape containers, exploit vulnerabilities, gain persistence, or allow remote control.
- Tool Module (pkg/tool): Provides support commands and network utilities that mimic traditional Linux/Unix tools (e.g., nc, ps, vi) as well as specialized tools for Kubernetes and Docker API interactions.
- Configuration (conf): Holds configuration definitions and evaluation/exploitation parameters. This module feeds settings into the main modules.
- Common Utilities (pkg/util): Offers helper functions (file I/O, HTTP requests, capability definitions, etc.) used by various other modules.
- Auxiliary Modules (pkg/task, pkg/plugin, pkg/errors): Support scheduling, extensibility of exploits, and error wrapping respectively.
- Relationships and Data Flow:
- The main command-line executable (from cmd/cdk) parses user input with pkg/cli and then directs execution flow to the appropriate module (evaluate, exploit, or tool).
- The Evaluate module calls various sub-functions (system info, mounts, namespaces, etc.) and uses configuration data from the conf package.
- Depending on the evaluation output, the exploit module might be triggered for exploitation via commands like “cdk run <exploit-name>”. The exploit modules are further subdivided by tactic (escaping, discovery, remote control, etc.) and may call common utilities.
- The Tool module inter-operates with helper libraries in pkg/util and performs network or system operations akin to standard Linux commands.
- There is also a testing framework (in test/) that emulates cluster deployments and container conditions to validate exploits.

##### Key Architectural Patterns and Design Principles
- Modularization: The separation of commands into Evaluate, Exploit, and Tool modules along with devoted configuration and utility sub-packages promotes high cohesion and low coupling.
- Layered architecture: The project can be visualized in layers starting from the CLI, moving into an application layer consisting of evaluation, exploitation logic and then further down into configuration and utilities.
- Extensibility: The existence of a plugin interface, separation of exploit tactics, and task modules imply a design that favors extendibility and ease of adding new exploits or tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI/Entry Point"
        A["cdk.go (cmd/cdk)"]:::cli
        B["banner.go (pkg/cli)"]:::cli
        C["parse.go (pkg/cli)"]:::cli
    end

    subgraph "Modules"
        D["Evaluate Module (pkg/evaluate)"]:::module
        E["Exploit Module (pkg/exploit)"]:::module
        F["Tool Module (pkg/tool)"]:::module
    end

    subgraph "Configuration & Utilities"
        G["Configuration Module (conf)"]:::config
        H["Common Utilities (pkg/util)"]:::util
        I["Task Module (pkg/task)"]:::aux
        J["Plugin Interface (pkg/plugin)"]:::aux
        K["Error Handling (pkg/errors)"]:::aux
    end

    subgraph "Testing & Deployment"
        L["Testing & Deployment (test)"]:::test
    end

    %% Relationships
    A -->|"initiates"| D
    A -->|"initiates"| E
    A -->|"initiates"| F
    B -->|"presents"| A
    C -->|"parses"| A

    D -->|"uses_config"| G
    D -->|"calls_utilities"| H

    E -->|"uses_config"| G
    E -->|"calls_utilities"| H
    E -->|"invokes_tasks"| I
    E -->|"invokes_plugins"| J
    E -->|"reports_errors"| K

    F -->|"calls_utilities"| H

    L -->|"tests_Evaluate"| D
    L -->|"tests_Exploit"| E

    %% Click Events
    click A "https://github.com/cdk-team/cdk/blob/main/cmd/cdk/cdk.go"
    click B "https://github.com/cdk-team/cdk/blob/main/pkg/cli/banner.go"
    click C "https://github.com/cdk-team/cdk/blob/main/pkg/cli/parse.go"
    click D "https://github.com/cdk-team/cdk/tree/main/pkg/evaluate"
    click E "https://github.com/cdk-team/cdk/tree/main/pkg/exploit"
    click F "https://github.com/cdk-team/cdk/tree/main/pkg/tool"
    click G "https://github.com/cdk-team/cdk/tree/main/conf"
    click H "https://github.com/cdk-team/cdk/tree/main/pkg/util"
    click I "https://github.com/cdk-team/cdk/tree/main/pkg/task"
    click J "https://github.com/cdk-team/cdk/tree/main/pkg/plugin"
    click K "https://github.com/cdk-team/cdk/tree/main/pkg/errors"
    click L "https://github.com/cdk-team/cdk/tree/main/test"

    %% Styles
    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef module fill:#bbf,stroke:#333,stroke-width:2px;
    classDef config fill:#afa,stroke:#333,stroke-width:2px;
    classDef util fill:#ff9,stroke:#333,stroke-width:2px;
    classDef aux fill:#fcc,stroke:#333,stroke-width:2px;
    classDef test fill:#cfc,stroke:#333,stroke-width:2px;
```
