Once the command line is fully parsed, this will get the value of the selected command. If the command is ambiguous, fill it in with the value 'default_commmand'.

In that case, this field doesn't get set with a real value until after all your configuration files run. Instead, it will be an empty string.

Everything else will go to _ERR_INFO.

Generally, we recommend setting this to warn for docker, and error for everything else, as docker only reports errors when there is a problem where it had to restart the operation without chalk.

By default, virtual chalk marks will get appended to the file ./virtual-chalk.json, but you can use the output system to send them anywhere (this is setup in the default configuration file).

By default, it is hooked up to a file sink, the location of which is specified by the audit_location variable, and the max size of which is specified by the audit_file_size variable.

If you provide a file name only, the directories in log_search_path are tried in order. Failing that, it uses /tmp.

If you provide an absolute path, and the log file cannot be opened, then it falls back on the search path (keeping the file name portion).

Defaults to 'chalk-audit.json'

This path is also searched if there is a problem writing log files where an explicit path is given.

Note that if nothing in this path works, Chalk tries to create a temporary directory for log files, just for that invocation.

Generally, systems use /tmp for temporary files, and most modern API interfaces to using /tmp take mitigation against file-based race conditions, for instance, by leveraging per-app directories and randomness in selecting file names.

However, there are times when the system default isn't a good option for Chalk when it needs temporary space. Specifically, we've learned that, for those running Docker via Snap on Ubuntu systems, Snap's isolation of temporary files means that users will get an error if we try to use /tmp to, for instance, write out a temporary docker file that we want to use with a container.

Specifying a directory outside of /tmp addresses that problem, which can easily be done with the quite standard TMPDIR environment variable.

However, Chalk philosophically doesn't want to leave opportunity for people to "forget" to do things when deploying us. So this field allows you to pick a place for temporary files to use IF no value for TMPDIR is provided.

If neither is provided, you may very well end up with /tmp or /var/tmp, which should be great in most cases.

Even if this is false, Chalk will try to sign if either the chalking template or the reporting template have SIGNATURE set.

The password is NOT stored in the binary. You can choose to provide the password via the CHALK_PASSWORD environment variable, or you may escrow it in our secret manager.

If this is true, when you set up signing, the password will get encrypted by another randomly generated value, stored in your binary. The result will posted to our free service over TLS; the service will then be queried as it is needed.

If you do not select this when setting up signing, the password will be written to stdout a single time. Or, you can set the password manually via the CHALK_PASSWORD environment variable (if using the manager, the env variable is ignored during setup).

Once you have configured signing, Chalk will first try to read the password from the CHALK_PASSWORD environment variable. If the environment variable doesn't exist, what happens next is dependant on this variable.

If it's true, then we attempt to query the secret manager before giving up. If it's false, we immediately move on without signing.

Note that if you provide the environment variable, then the secret manager currently does not run. We may eventually make it a fallback.

This is only used for the chalk setup command; it dictates where to either find a key pair to load, or where to write a keypair being generated.

Chalk will also embed the keypairs internally, for future operations.

The 'extract' operation ignores this.

This is primarily meant to make it easier to test new configurations by disabling the embedded config and only running the external (candidate) config.

You can change that directory by setting the global variable SYFT_EXE_DIR with the := operator (it is not an attribute). The syft command line arguments used at invocation (minus the target location) can be set via the SYFT_ARGV global variable. It's default value is:

-o cyclonedx-json 2>/dev/null

Currently, the only available tool out of the box is semgrep, and will only work on machines that either already have semgrep installed, or have Python3 installed.

If this is not provided, or if the file is not found, chalk will search the PATH for the first instance of 'docker' that is not itself (We generally expect renaming chalk to docker and using this variable to point to the actual docker EXE will be the most seamless approach).

Note that, when chalk is invoked with 'docker' as its EXE name, the default IO configuration is to NOT anything chalk-specific on the console.

Currently, this is only fully respected for artifacts in ZIP format (e.g., JAR files)

When this is true, docker builds will chalk items in any local context directories. Remote contexts currently do not get chalked when this is true.

This is similar to the 'chalk config' command, except that it causes the same type of information to be added at the end of any operation.

This is useful when you have conditional logic in your configuration file, and want to see the results of config file evaluation for specific sets of command-line arguments.

The report cache will re-publish on subsequent runs by appending any unsent messages to the json report (this is why reports are an array). It does so on a sink-by-sink basis, based on the name of the sink. It will never publish to the same sink twice.

A few important notes:

1. This functionality applies both to the default 'report' topic, and for custom reports.

2. If the report cache successfully flushes all its contents, it will leave a zero-byte file (it does not remove the file). Still, it doesn't write the file for the first time until there is a failure.

3. If, for any reason, writing to the report cache fails, there will be a forced write to stderr, whether you've subscribed to it or not, in an attempt to prevent data loss.

4. There is currently not a way to specify a 'fallback' sink.

5. If this is off, there is no check for previously cached data.

Note that this field is set on the command line with --use-report-cache / --no-use-report-cache.

For cases when this happens, Chalk uses a file locking system. If another running process holds the lock, chalk will keep retrying once per second for the number of specified seconds, before giving up (stale lock files are ignored).

This variable then controls how many retries will be made, and thus the approximate maximum delay to the start of work.

If you're running tools via chalk that can take a while to run, then you probably want to bump this number up, or use multiple report caches, or somesuch.

If you have more typical build runs that complete quickly, then this number can stay pretty low.

Note that this is NOT checked if there is a report cache enabled; even if the report cache fails, then there will be console output.

If you have the value in an environment variable, you can pass it to chalk with something like:

if env_exists("AWS_IAM_ROLE") {
  aws_iam_role = env("AWS_IAM_ROLE")
}

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.

This is checked before the user config is loaded; it's only settable via command line flag.

However, if you want to disable it in your config file, you can just set:

custom_report_terminal_chalk_time.enabled: false
custom_report.terminal_other_op.enabled: false

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.

~/.local/share/bash_completion/completions/chalk.bash

If it's not present, chalk will attempt to install it.

To skip the pager on the command line, use the --no-pager flag.

Note that, by default, Chalk will use its own binary for the wrapping, unless it sees an arch flag and determines that this is the wrong binary.

In such a case, you should have a binary available for the architecture you are building for to copy in, which can be specified via the arch_binary_locations field.

Note that either we need to be able to copy the chalk binary into the context directory before invoking Docker, or you need to be on a version of Docker that accepts --build-context, otherwise the wrapping will fail (though just the wrapping).

The configuration of the chalk process inside the container will be inherited from the binary doing the chalking.

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 in the time of the wrapping.

If this field is set, it maps docker architecture strings to locations where the configured Chalk binary lives for the platform. Currently, this only accepts local file system paths, so the binary must be local.

If there isn't an architecture match, and no binary can be found per this field,

Keys are expected in "Os/Architecture/Variant" form, eg: "linux/arm64", "linux/amd64", "linux/arm/v7" etc.

Note that Chalk itself is only targeted for a subset of the platforms that officially support Docker, specifically Linux on arm64 and amd64 (no Windows yet). If an entrypoint wrapping is performed on any architecture not in this set (bravo for getting Chalk to build!), it will still refuse to copy itself in, except via this configuration field.

For instance, the HASH key cannot currently appear in docker chalks, because it is not available for chalk-time, so will not appear as a label. But, you can add METADATA_ID, CHALK_ID, etc. or anything else that is collectable before the build.

Note that failed chalk attempts get published to the 'fail' topic, and there are no default output sinks subscribed to this topic.

If you want to add chalk-time metadata, have the value be the chalk key, prefixed with an @. For instance:

{ "ARTIFACT_IDENTIFIER" : "@CHALK_ID" }

will add something to the dockerfile like:

ENV ARTIFACT_IDENTIFIER="X6VRPZ-C828-KDNS-QDXRT0"

You must set a value for this variable or pass the --exec-command-name flag to be able to use the 'exec' command.

When chalk is configured to be the parent after fork, it's important to give ourselves enough time for the exec() to occur, so that the child's process info doesn't look like Chalk.

When chalk isn't the parent, it's still not bad to allow some initialization time; it improves the data collection. However, in this scenario, short-lived containers could die and prevent us from reporting, so it may be best to keep this well under a second in general.

See get_heartbeat_rate for the subsequent sleep period.

Also, you can turn off use of PATH via exec.use_path, in which case this becomes the sole search path.

As a result, when this is set to true, during an 'exec' operation, Chalk forks and takes the parent role, and the child process execs. Chalk does its work, then calls waitpid() on the process, and returns whatever exit value the exec'd process returned.

This can be set at the command-line with --chalk-as-parent (aka --pg-13)

If command-line arguments are provided, you have three options:

1. Always send these arguments, and have any additional arguments be appended to these arguments. For these semantics, set append_command_line_args to true.
2. Have the command line arguments REPLACE these arguments. For these semantics, set override_ok to true. This is chalk's default behavior, absent of any other configuration.
3. Disallow any command-line argument passing. For this behavior, set both of the above variables to 'false'.

Setting both to 'true' at the same time is not semantically valid, and will give you an error message; nothing will run.

If it is NOT true, set exec.searchpath to provide any locations Chalk should check for the executable to exec.

Note that, when Chalk is running in a container, the container may exit before any particular report completes, and can even kill one in the middle of it posting.

When running outside a container, or if inside a container, but running as a parent process, the heartbeat process will exit after a final report, if the monitored process has exited.

By default we skip unsigned images, because the process (necessarily) involves downloading the container image.

But if there's no signature, assuming `ignore_unsigned_images` is true, Chalk looks in the top layer of the file system.

When no Chalk can be found in either place, if this attribute is set to true, we'll look at the other layers in the image and report the `CHALK_ID` and `METADATA_ID` of the topmost layer with a mark, using the `_FOUND_BASE_MARK` key (the image itself is said to be unchalked; it's more about being able to use knowledge of a chalked base image).

Note that this does nothing unless `ignore_unsigned_images` is false.

This is useful in many scripting languages, as the main entry point is often made executable and given a shebang, whereas supporting files are not.

Currently, Chalk has no native support to try to determine which files the language is likely to deem an entry point. We do not attempt to understand any package/module system, etc.

If you'd like to do that, you can add a custom callback.

Extraction does not check this. It will attempt to extract from any file that appears to be valid utf when looking at the first 256 bytes, unless you provide a custom callback.

When this is true, Chalk will not attempt to mark source code unless the executable bit is set. However, the execute bit can get added later; it's a trade-off!

Extraction does not check this. It will attempt to extract from any file that appears to be valid utf when looking at the first 256 bytes, unless you provide a custom callback.

So for all operations, we assume the extensions in this list can never be source code.

Your callback will not supersede shebangs_when_no_extension_match and only_mark_when_execute_is_set. Your callback will only get run if those checks would lead to the file otherwise being marked.

The callback receives the following parameters:

1. The (resolved) file name for the file being considered.
2. The detected language (see below).
3. The file extension (so you don't have to carve it out of the file name).
4. A boolean indicating whether there was a shebang line (if only_mark_shebangs is on, this will always be true).
5. A boolean indicating whether the execute bit is set on the file system. This will always be true if only_mark_when_execute_set is true.

Language detection prefers the shebang line, if it's captured. The language name will be matched with the following rules:

• We look at the first item after the #!, which will either be a full path or an exe name (where the path is searched).
• Any directory component is stripped.
• If the value is the word env then we instead look at the first non-flag item (again, stripping any directory component, even though generally we wouldn't expect to see any).
• Any trailing sequence of numbers and dots are removed.

Therefore, all of these will normalize the same way:

#! python #! python3 #! /bin/env python #! /bin/env python3.3.1

If chalk does not recognize the language, and your logic says to mark, it will proceed to mark it, assuming that '#' is the comment character. Alternatively, you can add the language to our database.

If there was no shebang line, or we did not look at the shebang line, then we consult source_marks.extensions_to_languages_map.

If that turns up nothing, or if there is no extension, then we look at the executable bit. If it's set, then we check to see if the file seems to be valid utf-8, by looking at the first 256 bytes. If it is, then we assume sh as the language.

Otherwise, we will assume the file is not an executable.

This also means that we might use odd language names, like 'node', since it's the thing we're likely to see in a shebang line.