How crashappsec/chalk works
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)