# crashappsec/chalk architecture

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

- Interactive diagram: https://gitdiagram.com/crashappsec/chalk
- Repository: https://github.com/crashappsec/chalk

## Overview

##### Project type and purpose
- Chalk is an open-source, CLI-driven tool (written in Nim) for capturing build-time metadata (“chalk marks”) on artifacts and extracting runtime metadata.
- It supports use cases around SBOM generation, build provenance (SLSA compliance), runtime exec reports, and can wrap/invoke Docker builds transparently.

##### File structure
- Top-level:
- Dockerfile, docker-compose.yml, docker-bake.hcl → container packaging
- configs/ & src/configs/ → C4M configuration modules driving behavior
- src/… → core Nim code, organized into functional areas:
– commands/ (subcommand implementations)
– docker/ (Docker wrapper, image build/inspect/push)
– attestation/ (embed/get metadata at build time)
– object_store/ (presign, upload artifacts)
– plugin_api & plugins/ (extension points, dynamic modules for CI providers, codecs, sinks)
– reporting, sinks, util, auth, config loading, run_management, etc.
- tests/functional & tests/unit → Python-based integration tests and Nim unit tests

##### README for additional insights
- Emphasizes CLI operations (“insert”, “extract”, “exec”), Docker wrapping, SBOM, SLSA compliance.

a. Main components:
- CLI Frontend: `chalk` binary (commands.nim → dispatcher)
- Config Loader: reads C4M files via `confload.nim` → builds in-memory config graph
- Command Modules: each subcommand (insert, extract, docker wrap, exec)
- Docker Engine Adapter: docker/ modules for build, inspect, wrap, scan
- Attestation Engine: embed/get metadata
- Object Store Layer: presign & upload (S3, HTTP, file)
- Plugin Framework: plugin_api + dynamically loaded plugins (CI, codecs, sinks)
- Reporting & Sinks: outputs (terminal, file, HTTP, rotating log)
- External Services: Docker daemon, S3/HTTP endpoints, CI systems, semgrep/SAST engines

b. Relationships & interactions:
1. User invokes `chalk <subcommand> [flags]`
2. CLI dispatcher loads config via Config Loader
3. Depending on command:
– “insert”/“embed”: calls Attestation Engine → Docker Engine Adapter to build/wrap images
– “extract”: uses Attestation Engine to pull metadata, then Object Store Layer or sinks
– “exec”: wraps process exec to collect runtime environment data
4. Plugin Framework hooks into commands/configs to extend support for new codecs, CI backends, sinks
5. Reporting & Sinks consume outputs and push to terminal, files, remote endpoints
6. Tests invoke CLI or modules directly

c. Architectural patterns & principles:
- Modular command pattern: each CLI subcommand lives in its own module
- Plugin-based extensibility: plugin_api defines interfaces; plugins/ implements them
- Config-driven behavior: C4M files describe workflows; core loads and composes them
- Separation of concerns: attestation vs. docker interaction vs. object storage vs. reporting

d. Key technologies/frameworks:
- Nim compiler & runtime
- C4M configuration language
- Docker Engine API
- Python/pytest for functional tests
- GitHub Actions for CI

##### Detail
- Config files feeding into the Config Loader
- Plugin_api interfaces and plugin implementations under plugins/
- How tests span across modules (optional layer at bottom)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Invocation
    CLI["CLI Frontend\nsrc/chalk.nim\nsrc/commands.nim"]:::core
    autocomplete["Autocomplete Support\nsrc/autocomplete.nim\nsrc/autocomplete/default.bash"]:::core

    %% Configuration
    subgraph "Configuration Modules"  
        config_files["Configs\nconfigs/*.c4m\nsrc/configs/*.c4m"]:::config
    end
    subgraph "Config Loader"  
        confload["confload.nim"]:::core
        config_model["config.nim\nconfig_version.nim\ncon4mfuncs.nim"]:::core
    end

    %% Command Modules
    subgraph "Command Modules"  
        cmd_insert["insert\ncmd_insert.nim"]:::core
        cmd_extract["extract\ncmd_extract.nim"]:::core
        cmd_exec["exec\ncmd_exec.nim"]:::core
        cmd_docker["docker wrap\ncmd_docker.nim"]:::core
        cmd_help["help\ncmd_help.nim"]:::core
        cmd_version["version\ncmd_version.nim"]:::core
        cmd_dump["dump\ncmd_dump.nim"]:::core
        cmd_env["env\ncmd_env.nim"]:::core
        cmd_load["load\ncmd_load.nim"]:::core
        cmd_setup["setup\ncmd_setup.nim"]:::core
        cmd_delete["delete\ncmd_delete.nim"]:::core
        cmd_internal["internal\ncmd_internal.nim"]:::core
    end

    %% Core Utilities
    subgraph "Core Utilities & Helpers"
        utils["util.nim"]:::core
        runmgmt["run_management.nim"]:::core
        auth["auth.nim"]:::core
        gitmod["git.nim"]:::core
        normalize["normalize.nim"]:::core
        semver["semver.nim"]:::core
    end

    %% Docker Adapter
    subgraph "Docker Engine Adapter"  
        docker_build["build.nim"]:::core
        docker_inspect["inspect.nim"]:::core
        docker_push["push.nim"]:::core
        docker_wrap["wrap.nim"]:::core
        dockerfile["dockerfile.nim"]:::core
        registry["registry.nim"]:::core
        scan["scan.nim"]:::core
        docker_util["util.nim"]:::core
    end

    %% Attestation
    subgraph "Attestation Engine"
        attest_embed["embed.nim"]:::core
        attest_get["get.nim"]:::core
        attest_utils["utils.nim"]:::core
        attest_api["attestation_api.nim"]:::core
    end

    %% Object Store
    subgraph "Object Store Layer"
        obj_api["api.nim"]:::core
        obj_presign["presign.nim"]:::core
    end

    %% Plugin Framework
    subgraph "Plugin Framework"
        plugin_api["plugin_api.nim"]:::plugin
        plugin_load["plugin_load.nim"]:::plugin
        plugin_impl["plugins/*.nim"]:::plugin
    end

    %% Reporting & Sinks
    subgraph "Reporting & Sinks"
        reporting["reporting.nim"]:::core
        sinks["sinks.nim"]:::core
        reportcache["reportcache.nim"]:::core
    end

    %% External Services
    subgraph "External Services"
        docker_daemon["Docker Daemon"]:::external
        object_store_svc["S3/HTTP Endpoints"]:::external
        ci_systems["CI Systems"]:::external
        sast_engines["SAST/Semgrep"]:::external
        terminal_out["Terminal/File/HTTP"]:::external
    end

    %% Flows
    CLI -->|"loads config"| confload
    autocomplete --> CLI
    config_files --> confload
    confload --> config_model
    config_model --> cmd_insert
    config_model --> cmd_extract
    config_model --> cmd_exec
    config_model --> cmd_docker
    CLI --> cmd_help
    CLI --> cmd_version
    CLI --> cmd_dump
    CLI --> cmd_env
    CLI --> cmd_load
    CLI --> cmd_setup
    CLI --> cmd_delete
    CLI --> cmd_internal

    cmd_insert --> attest_embed
    cmd_insert --> docker_wrap
    cmd_extract --> attest_get
    cmd_extract --> obj_api
    cmd_exec --> attest_embed
    cmd_docker --> docker_build

    attest_embed --> docker_daemon
    docker_wrap --> docker_daemon
    docker_build --> docker_daemon
    docker_inspect --> docker_daemon
    docker_push --> docker_daemon
    scan --> docker_daemon

    obj_presign --> object_store_svc
    obj_api --> obj_presign

    plugin_api --> plugin_impl
    plugin_load --> plugin_impl
    cmd_insert --> plugin_api
    cmd_extract --> plugin_api
    cmd_exec --> plugin_api

    cmd_insert --> reporting
    cmd_extract --> reporting
    cmd_exec --> reporting
    reporting --> terminal_out
    sinks --> terminal_out
    reportcache --> terminal_out

    plugin_api --> ci_systems
    plugin_api --> sast_engines

    %% Click Events
    click CLI "https://github.com/crashappsec/chalk/blob/main/src/chalk.nim"
    click CLI "https://github.com/crashappsec/chalk/blob/main/src/commands.nim"
    click autocomplete "https://github.com/crashappsec/chalk/blob/main/src/autocomplete.nim"
    click autocomplete "https://github.com/crashappsec/chalk/blob/main/src/autocomplete/default.bash"
    click confload "https://github.com/crashappsec/chalk/blob/main/src/confload.nim"
    click config_model "https://github.com/crashappsec/chalk/blob/main/src/config.nim"
    click config_model "https://github.com/crashappsec/chalk/blob/main/src/config_version.nim"
    click config_model "https://github.com/crashappsec/chalk/blob/main/src/con4mfuncs.nim"
    click cmd_insert "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_insert.nim"
    click cmd_extract "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_extract.nim"
    click cmd_exec "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_exec.nim"
    click cmd_docker "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_docker.nim"
    click cmd_help "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_help.nim"
    click cmd_version "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_version.nim"
    click cmd_dump "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_dump.nim"
    click cmd_env "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_env.nim"
    click cmd_load "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_load.nim"
    click cmd_setup "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_setup.nim"
    click cmd_delete "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_delete.nim"
    click cmd_internal "https://github.com/crashappsec/chalk/blob/main/src/commands/cmd_internal.nim"
    click docker_build "https://github.com/crashappsec/chalk/blob/main/src/docker/build.nim"
    click docker_inspect "https://github.com/crashappsec/chalk/blob/main/src/docker/inspect.nim"
    click docker_push "https://github.com/crashappsec/chalk/blob/main/src/docker/push.nim"
    click docker_wrap "https://github.com/crashappsec/chalk/blob/main/src/docker/wrap.nim"
    click dockerfile "https://github.com/crashappsec/chalk/blob/main/src/docker/dockerfile.nim"
    click registry "https://github.com/crashappsec/chalk/blob/main/src/docker/registry.nim"
    click scan "https://github.com/crashappsec/chalk/blob/main/src/docker/scan.nim"
    click docker_util "https://github.com/crashappsec/chalk/blob/main/src/docker/util.nim"
    click attest_embed "https://github.com/crashappsec/chalk/blob/main/src/attestation/embed.nim"
    click attest_get "https://github.com/crashappsec/chalk/blob/main/src/attestation/get.nim"
    click attest_utils "https://github.com/crashappsec/chalk/blob/main/src/attestation/utils.nim"
    click attest_api "https://github.com/crashappsec/chalk/blob/main/src/attestation_api.nim"
    click obj_api "https://github.com/crashappsec/chalk/blob/main/src/object_store/api.nim"
    click obj_presign "https://github.com/crashappsec/chalk/blob/main/src/object_store/presign.nim"
    click plugin_api "https://github.com/crashappsec/chalk/blob/main/src/plugin_api.nim"
    click plugin_load "https://github.com/crashappsec/chalk/blob/main/src/plugin_load.nim"
    click plugin_impl "https://github.com/crashappsec/chalk/blob/main/src/plugins/ciGithub.nim"
    click plugin_impl "https://github.com/crashappsec/chalk/blob/main/src/plugins/codecDocker.nim"
    click plugin_impl "https://github.com/crashappsec/chalk/blob/main/src/plugins/awsLambda.nim"
    click reporting "https://github.com/crashappsec/chalk/blob/main/src/reporting.nim"
    click sinks "https://github.com/crashappsec/chalk/blob/main/src/sinks.nim"
    click reportcache "https://github.com/crashappsec/chalk/blob/main/src/reportcache.nim"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef plugin fill:#ABEBC6,stroke:#196F3D,color:#145A32
    classDef external fill:#D5DBDB,stroke:#566573,color:#1B2631
    classDef config fill:#F9E79F,stroke:#B9770E,color:#7D6608
```
