chalk

Chalk

Collect and report software and host metadata

aliases : none
arguments: none

Command Name	Description
insert	Add chalk marks to artifacts
extract	Find chalk marks in artifacts
delete	Delete chalk marks from software
env	Run a chalk report on the current environment
exec	Start a program, and report on it
config	Show configuration variables and settings
dump	Print the embedded configuration file
load	Load a new configuration into the chalk binary
version	Give version information
docker	Run a docker command, then chalk built or pushed containers
setup	Set up automatic code signing
help	Observability for the Software Development Lifecycle
logout	Logout of API
login	Start API login process
docgen	Generate technical documentation

Description

Chalk's core purpose is to map production software with its development, and to provide information about those artifacts in CI/CD and in production. Usually, metadata is produced at CI/CD time after software is built, and then collected from production. This command can both insert and extract, and send data off as appropriate. This tool is meant to be easy in CI/CD-- just drop it into the right place in the pipeline, and never think about it again. At the same time, it's very customizable. Administrators can easily produce stand-alone binaries that collect custom metadata. The chalk command's behavior is easily customized, primarily via a flexible configuration file. The options provided at the command line are reserved for items where there's an obvious utility in overriding without editing the config file. See the Chalk Users Guide for more information.

Flags

insert command

Add chalk marks to artifacts

aliases : inject
arguments: not required; any number okay

Description

Add chalk marks to artifacts found on the file system. See the docker command for adding marks to docker containers.

On chalking, what gets put into the chalk mark will be determined by the active chalk mark template after any user config file has loaded. Each command's output configuration can be specified using the 'outconf' section in the configuration file.

For instance, if you create a new mark template named 'my_chalk_mark', you can activate it for both regular and docker insertions with the following in your configuration file:

outconf.insert.chalk = "myconf"
outconf.docker.chalk = "myconf"

For information on mark templates on the command line, see: chalk help templates

Flags

Flag Name	Description
`--color` Aliases: `-c` Negated by: `-C`, `--no-color`	Enable colors (overriding any config file settings) Sets config field: `color`
`--time` Negated by: `--no-time`	Reports the total run time of the chalk executable in seconds. Sets config field: `report_total_time`
`--use_embedded_config` Negated by: `--no-use_embedded_config`	Ensure that embedded configuration runs. This flag should never be necessary, since there is no way to override the internal value before the embedded configuration runs. However, the negation flag can be used to keep the embedded configuration from running. This is most useful when testing configuration files via an external configuration file, to avoid conflicts that can arise when running both configurations. Sets config field: `load_embedded_config`
`--use_external_config` Negated by: `--no-use_external_config`	Turn on/off checking for (and running) any external configuration file. Sets config field: `load_external_config`
`--show_config` Aliases: `--config` Negated by: `--no-show_config`	This flag runs chalk, then, at the end, outputs state information specific to that invocation of chalk. This is similar to the `chalk config` command, except it shows state information specific to this particular invocation (whereas `chalk config` doesn't perform any action other than loading the configuration file). Sets config field: `show_config`
`--run_sbom_tools` Negated by: `--no-run_sbom_tools`	For insertion operations, this flag forces running any configured tools for SBOM collection. It does not guarantee reporting or chalking; that is up to the reporting configuration. In the default chalk configuration, these tools do not run at all. This flag is defined for all chalk commands, but currently is ignored for any command except "insert" or "docker". Sets config field: `run_sbom_tools`
`--run_sast_tools` Negated by: `--no-run_sast_tools`	For insertion operations, this flag forces running any configured tools for performing static analysis. It does not guarantee reporting or chalking; that is up to the reporting configuration. In the default chalk configuration, these tools do not run at all. This flag is defined for all chalk commands, but currently is ignored for any command except "insert" or "docker". Sets config field: `run_sast_tools`
`--use_report_cache` Negated by: `--no-use_report_cache`	Enables or disables the reporting cache. The reporting cache is a ring buffer stored locally, that contains reporting information that could not be delivered to its configured sources, due to some outage. When using the report cache, any time chalk does run reports, it will try to flush as much of the cache as it can. Sets config field: `use_report_cache`
`--virtual` Aliases: `-v`, `--dry-run` Negated by: `-V`, `--no-dry-run`, `--no-virtual`	When chalking, do NOT modify artifacts, overriding anything defined in the config file. This is completely ignored for operations that do not normally modify artifacts. Specifically, this flag only works with `chalk insert`, `chalk docker build`, and `chalk delete`. By default, this will write to "./virtual-chalk.json". Sets config field: `virtual_chalk`
`--debug` Negated by: `--no-debug`	Shows nim stack traces where appropriate, generally where exceptions were caught. Additionally, if temporary files might be useful to inspect, this causes them to not get deleted. Specifically, docker temporary files (most notably any docker file modifications) get left behind. Sets config field: `chalk_debug`
`--skip_command_report` Negated by: `--no-skip_command_report`	Skip publishing the command report (i.e., the PRIMARY report). NO output sinks will get it. For most commands, this defeats the purpose of Chalk, so use it sparingly. Note that this doesn't turn off any custom reports; you have to disable those separately. Sets config field: `skip_command_report`
`--skip_summary_report` Negated by: `--no-skip_summary_report`	Whether to skip the summary report to the terminal. Sets config field: `skip_summary_report`
`--wrap` Negated by: `--no-wrap`	When building a container via `chalk docker`, this will cause Chalk to automatically perform entry-point wrapping in such a way that built containers will do a chalk report when they launch. Note that the 'docker' command passes through ALL flags, so this flag needs to technically be part of the 'global' flags, even though nothing else uses it. If, when wrapping, your chalk binary is using an external configuration file, that file will NOT get used inside the container. The wrapped binary currently only uses the embedded configuration present in the binary at the time of the wrapping. Sets config field: `docker.wrap_entrypoint`
`--pager` Negated by: `--no-more`, `--no-less`, `--no-pager`	Sets whether to display documents in the system pager for output. At the moment, this is only honored for the `chalk help` command. Sets config field: `use_pager`
`--config_file` Aliases: `-f`	The location from which to read an external config file. When this flag is passed, chalk ignores its search path; the only file it attempts to load is this one. Flag requires an argument
`--report_cache_file`	This overrides the location of the report cache, if chalk is configured to use it. The reporting cache keeps a local copy of any reports made, to provide redundancy if there are network errors. Flag requires an argument
`--enable_report`	Explicitly enable a specific `custom_report` defined in the configuration file, even if it is not enabled in that configuration file. Flag can be a comma-separated list, or provided multiple times
`--disable_report`	Explicitly disable a specific `custom_report` defined in the configuration file. Flag can be a comma-separated list, or provided multiple times
`--log_level` Aliases: `-l`	Sets the console log-level to the specified value, controlling what logs are output to the terminal. Note that "verbose" and "trace" are aliases. Sets config field: `log_level` Per-choice alias flags: `--verbose` `--trace` `--info` `--warn` `--error` `--none` Value choices: verbose trace info warn error none Flag requires an argument (does not apply to per-choice aliases)
`--symlink_behavior` Aliases: `--symlink_behaviour`	Chalk never follows directory links. When running non-chalking operations, chalk will read the file on the other end of the link, and report using the file name of the link. For insertion operations, Chalk will, out of the box, warn on symbolic links, without processing them. This variable controls what happens in those cases: skip will not process files that are linked. clobber will read the artifact on the other end of the link, and, if writing, try to replace the file being linked to. copy will read the artifact on the other end of the link, and, if writing, will replace the link with a modified file, leaving the file on the other end of the link intact. Sets config field: `symlink_behavior` Per-choice alias flags: `--skip` `--clobber` `--copy` Value choices: skip clobber copy Flag requires an argument (does not apply to per-choice aliases)
`--help` Aliases: `-h`	Shows help for this command.

docker command

Run a docker command, then chalk built or pushed containers

aliases : none
arguments: not required; any number okay

Description

Chalk a container operation. This always transparently calls docker, as long as it is anywhere in your path (even if 'chalk' is named 'docker').

Currently, Chalk only collects metadata for 'docker' and 'push' commands.

All arguments appearing after the word 'docker' are passed to docker. No flags to chalk can appear after the command.

extract command

Find chalk marks in artifacts

aliases : none
arguments: not required; any number okay

Flag Name	Description
`--recursive` Aliases: `-r` Negated by: `-R`, `--no-recursive`	Determines whether a file scan will recursively walk paths to find artifacts. Sets config field: `recursive`
`--mark_template`	This changes which template to use to create any chalk marks for this run. The named Chalk mark template must already exist in your configuration. Sets config field: `outconf.insert.mark_template` Flag requires an argument
`--report_template`	This changes the reporting template to use for the default report. The named reporting template must already exist in your configuration. Sets config field: `outconf.insert.report_template` Flag requires an argument

Command Name	Description
images	Find marks in local docker images
containers	Find marks in running containers
all	Find all docker marks, plus filesystem marks

Description

This command looks for existing chalk marks in artifacts as specified by any command line arguments passed. The arguments can be files, directories, container identifiers, or container image identifiers.

Chalk will attempt to find all matching marks, and will report on what it finds, based on your reporting configuration.

Flags

extract.images subcommand

Find marks in local docker images

aliases : none
arguments: none

Description

This command will look at any docker images available locally, attempting to find chalk marks in them.

Note that this does not look through running containers; use `chalk extract containers` or `chalk extract all`.

extract.containers subcommand

Find marks in running containers

aliases : none
arguments: none

Description

This command will look at any docker containers available locally, attempting to find chalk marks in them.

extract.all subcommand

Find all docker marks, plus filesystem marks

aliases : none
arguments: not required; any number okay

Description

This command will attempt to extract chalk marks in all containers, container images for anything it can find on the local machine, AND will search the current working directory for chalk marks.

exec command

Start a program, and report on it

aliases : none
arguments: not required; any number okay

Description

Directly execs a specified process, and in parallel forks off to reports environmental information, without scanning for chalk. If a chalk ID or metadata ID is passed at the command line, then a chalk can be reported with just that metadata.

This is like the 'env' command, except for the exec'ing. The configuration for 'exec' is best put into the configuration file.

Flags

Flag Name	Description
`--recursive` Aliases: `-r` Negated by: `-R`, `--no-recursive`	Determines whether a file scan will recursively walk paths to find artifacts. Sets config field: `recursive`
`--search_layers` Negated by: `--no-search_layers`	When a mark in an image can't be found, should we try to report on overwritten marks? Sets config field: `extract.search_base_layers_for_marks`
`--report_template`	This changes the reporting template to use for the default report. The named reporting template must already exist in your configuration. Sets config field: `outconf.extract.report_template` Flag requires an argument

setup command

Set up automatic code signing

aliases : none
arguments: none

Flag Name	Description
`--chalk_as_parent` Aliases: `--pg13`, `--pg-13` Negated by: `--no-pg13`, `--no-pg-13`, `--no-chalk_as_parent`	When set to true, 'chalk exec' will leave chalk as the parent process (By default, the process to exec stays the parent, and chalk is forked off). This is most useful for short-lived processes, as it ensures chalk will complete any reporting. Sets config field: `exec.chalk_as_parent`
`--heartbeat` Negated by: `--no-heartbeat`	When set to true, causes periodic reports to be run, past the initial one. Sets config field: `exec.heartbeat`
`--exec_command_name`	When using the 'exec' command, this allows you to explicitly set the command to call at the command line. Arguments may be passed as arguments to 'chalk exec'. Sets config field: `exec.command_name` Flag requires an argument
`--report_template`	This changes the reporting template to use for the default report. The named reporting template must already exist in your configuration. Sets config field: `outconf.exec.report_template` Flag requires an argument

Command Name	Description
gen	Force generation of new signing key
load	Load existing signing key

Description

Set up code signing / attestation.

This is used to either generate or load a keypair for code signing.

Without a subcommand, chalk will first attempt to run as if the `load` subcommand were given, and if it doesn't find a keypair to load, then it will run the `gen` command to create one.

Flags

setup.gen subcommand

Force generation of new signing key

aliases : none
arguments: none

Description

Chalk will generate a new password and keypair. It will write the password to the terminal a single time, and will write the keypair to ./chalk.key (private key) and ./chalk.pub (public key).

The password is needed to load the keys into a different chalk binary, and is required for signing. By default, you must provide the password in an environment variable named `CHALK_PASSWORD`. Be careful to remove it from the environment after your chalk invocation, to avoid leakage.

Generally, that option is intended for running with a secrets manager. However, if you are going to hardcode the password and rely on operational security, you can hardcode the password directly into the Chalk binary with the `--store-password` option.

That will store the password inside the chalk mark, encrypted with a key that is chosen at `gen` time (on a Mac this is not possible; it's chosen when you compile the binary).

This approach will NOT thwart someone who has read access to the binary, so a proper secret manager is the recommended solution.

setup.load subcommand

Load existing signing key

aliases : none
arguments: none

Description

This looks for a keypair to import, by default in ./chalk.key (private key) and ./chalk.pub (public key). The key should have previously been generated by chalk, and encrypted with a password.

Pass `--store-password` to keep an encrypted copy of the password internally, per the `gen` command.

env command

Run a chalk report on the current environment

aliases : environment
arguments: none

Description

Reports environmental information, without scanning for chalk. If a chalk ID or metadata ID is passed at the command line, then a chalk can be reported with just that metadata. This is intended to be a lightweight version of 'extract' tied to a single artifact.

config command

Show configuration variables and settings

aliases : none
arguments: none

Description

Shows the results of evaluating the configuration, without actually doing any work with artifacts.

Even though they are related, there is a significant difference between the 'config' command and the --show-config flag. They both dump the configuration after evaluating any config file, but they may easily produce different results.

That's because chalk uses 'con4m' for configuration, which, while typically just looking like a regular config file, can have arbitrary code added, with conditionals, and so-on. The default configuration does, for instance, configure different output handlers, depending on the command given.

Running the 'defaults' command will therefore give you the information about the evaluation just when that command ran. Whereas, '--show-config extract' will dump the config as it resolves when you run the 'extract' command, which could be very similar, or very different.

Importantly though, running '--show-config extract' still runs the 'extract' command.

This command does not show the contents of the config file(s) used, just key results from executing those config files. And, generally there will be at least two 'stacked' configuration files. See 'help config' for more information on the configuration file and con4m.

dump command

Print the embedded configuration file

aliases : none
arguments: 0 to 1

Flag Name	Description
`--store_password` Negated by: `--no-store_password`	Sets whether to cache an encrypted copy of the password inside the chalk binary. This requires good operational security on the binary, so using a secret manager to set the password is ideal, but this option is better than hardcoding the password in a script that calls Chalk. Sets config field: `use_internal_password`
`--api_login` Negated by: `--no-api_login`	Enable/disable the use of the Crash Override API for secret management. Sets config field: `api_login`
`--key_file`	Sets the location of the signing key file on local disk. This should point to the private key file and end in `.key`. The public key file must be in the same base location, with the same file name, except with `.pub` as the file extension. Sets config field: `signing_key_location` Flag requires an argument

Command Name	Description
params	Output saved component parameters as JSON
cache	Output source for cached components

Description

Reads the embedded configuration file, and outputs it, based on your output configuration (see 'help output'). In the default configuration, if no argument is given, the config file is written to stdout; and if an argument is provided, it will try write the configuration to the file specified by the argument.

This behavior can be overridden by the configuration file, where you can specify different output configurations. See 'help config' for an overview of the configuration file format, and 'help output' for an overview of the output system.

load command

Load a new configuration into the chalk binary

aliases : none
arguments: 1 (exactly)

Description

Attempt to replaces the embedded configuration file, reading from the specified file name.

You can use the 'dump' command to dump the output first.

From the command line, See 'help config' for an overview of the configuration file format.

Flags

delete command

Delete chalk marks from software

aliases : none
arguments: not required; any number okay

Description

Deletes metadata from all artifacts specified in the search path.

Flags

Flag Name	Description
`--replace` Negated by: `--no-replace`	When on, the entire stored configuration file will be REPLACED with the provided argument. When off, it's used only as a component that's added to the config. Sets config field: `load.replace_conf`
`--update_arch_binaries` Negated by: `--no-update_arch_binaries`	When this is true, if you run a `chalk load` on this binary, it will try to (via docker) load the exact same configuration into any cross-architecture binaries listed in docker.arch_binary_locations. Note that, if you source config components from a local directory, you currently will need to update them manually, as those directories will not be mapped into the container. Sets config field: `load.update_arch_binaries`
`--params` Negated by: `--no-params`	When provided, parameters will be taken from stdin, as a json dictionary. Keys are the parameter name as specified in the 'parameter' block. If parameters that are needed aren't supplied, then defaults will be accepted. Sets config field: `load.params_via_stdin`
`--validation` Negated by: `--no-validation`	When on, validate config files before loading them, by doing a trial run. Sets config field: `load.validate_configs_on_load`
`--validation_warning` Negated by: `--no-validation_warning`	This verbose flag controls whether or not you get the verbose warning. It's much better turning this off in your embedded configuration :) Sets config field: `load.validation_warning`

version command

Give version information

aliases : none
arguments: none

Description

Outputs basic version information for the chalk binary.

Flag Name	Description
`--recursive` Aliases: `-r` Negated by: `-R`, `--no-recursive`	Determines whether a file scan will recursively walk paths to find artifacts. Sets config field: `recursive`
`--report_template`	This changes the reporting template to use for the default report. The named reporting template must already exist in your configuration. Sets config field: `outconf.delete.report_template` Flag requires an argument

Getting Started Config Overview