krampusctl

krampusctl is a script that lets you set up and update the rules and hostconfigs stored in Krampus.

Krampus' rules and hostconfigs contain all the keys expected and documented in the Santa rules / hostconfig (see preflight response in documentation). Additionally they include a row_id key, a targets key, and an optional exclusions key. The row_id can be used to edit a specific rule. If not provided, Krampus will create a row_id for your rule/hostconfig, which can be fetched with the --output_yaml command. The targets and exclusion keys are used together to determine which rules/hostconfigs target which machines. If these keys are not present, krampusctl sets the target to all.

krampusctl accepts several command line arguments, allowing you to update the Krampus database in several ways, including applying a specific set of data to the database, adding rows, editing rows and deleting rows. These command line arguments are described below. The data for these commands are given in a YAML-formatted configuration file, the configuration for which is described in the [configuration files](krampusctl#configuration-files} section.

Command Line Arguments

These command line arguments determine how krampusctl interacts with the Krampus database. krampusctl blocks syncs while it is updating the database, so that clients don't sync with a partially edited database.

Note that only one of the following commands can be used at a time: --apply, --add, --edit_fields, --edit_rows, --delete, --delete_multiple, --unblock.

Warning

If a command from krampusctl fails or encounters an error, it is possible that syncs remain blocked. This is intentional, so that an unknown database state is not synced to clients. The recommended way to unblock the sync is to use --apply, to apply the desired end state of the database. Successfully using this command will automatically unblock syncs. The syncs can also be manualy unblocked with --unblock.

Name	Alias	Type	Default Value	Description
--apply	'-a'	str	n/a	Path to configuration file containing rules and/or hostconfigs. For each top level key (which corresponds to one table/collection in the database), the data from this file will be applied so that the relevant table/collection in the database will contain data exactly matching this file. Can be used multiple times, in which case file content will be merged before being sent to the server.
--add	n/a	str	n/a	Path to configuration file containing rules and/or hostconfigs. All rules/hostconfigs from this file will be added to the database. Assumes no conflict for any given row_id. Can be used multiple times, in which case file content will be merged before being sent to the server.
--edit_fields	n/a	str	n/a	Path to configuration file containing (potentially incomplete) rules and/or hostconfigs. All given rules and hostconfigs must contain a row_id. Updates the given fields at that row_id. Can be used multiple times, in which case file content will be merged before being sent to the server.
--edit_rows	n/a	str	n/a	Path to configuration file containing rules and/or hostconfigs. All given rules and hostconfigs must contain a row_id. Updates the given row at the specified row_id. Can be used multiple times, in which case file content will be merged before being sent to the server.
--delete	-d	str	n/a	Path to configuration file containing (potentially incomplete) rules and/or hostconfigs. For each rules/hostconfigs, a match will be found and deleted from the database. Assumes only one match will be found per rules/hostconfigs. Can be used multiple times, in which case file content will be merged before being sent to the server.
--delete_multiple	n/a	str	n/a	Path to configuration file containing (potentially incomplete) rules and/or hostconfigs. For each rules/hostconfigs, all matches will be found and deleted from the database. Can be used multiple times, in which case file content will be merged before being sent to the server.
--is_sync_blocked	b	bool	n/a	After any other commands are processed, checks whether the sync is currently blocked.
--limit	'-l'	int	50	Determines the max batch size when reading from the Krampus database. Relevant for --apply and --output commands.
--output_yaml	'-o'	str	n/a	A path to write the contents of the rules and hostconfigs databases into. Will run after applying any other commands.
--server	-s	str	http://127.0.0.1:8000	Krampus server url.
--unblock	-u	bool	n/a	Manually unblocks the sync. Use this command with caution, if the database is blocked there was some error when trying to update the database, so it is recommended to check the database by using --output_yaml first, or to unblock the sync by --apply-ing your desired state to the database.

Environment Variables

Environment variables are mostly used by krampusctl for authentication purposes. Which environment variables are required depends on how Krampus is set up.

Name	Description
CTL_SECRET	If a CTL_SECRET has been set on the Krampus server-side in order to authenticate requests against the Krampus API, the same secret needs to be provided here. The value you provide for CTL_SECRET is added as the value for the Krampus-Auth header in every request krampusctl sends.
AUTH_HEADER_NAME	Specifies the name of a custom auth header to send with every krampusctl request. Used in conjunction with AUTH_HEADER_VALUE below. This can be useful if your Krampus instance is behind e.g. GCP Identity-Aware Proxy.
AUTH_HEADER_VALUE	Specifies the value of the custom auth header you've named with AUTH_HEADER_NAME to send with every krampusctl request.
JWT_USERNAME	If Krampus uses JWT for authentication, krampusctl needs to login to authenticate. This is the required username.
JWT_PASSWORD	If Krampus uses JWT for authentication, krampusctl needs to login to authenticate. This is the required password.
KRAMPUSCTL_SERVER_URL	Can be used instead of the --server CLI argument to specify the URL for the target Krampus server. If both are set, the value from the --server CLI argument is used.
KRAMPUSCTL_LOG_LEVEL	Allows you to specify the output logging level for krampusctl. If unset, the logging level defaults to INFO.

Configuration Files

Several of the command line arguments for krampusctl require data to add/edit/remove from Krampus' database in a YAML-formatted configuration file. These can be configured as follows:

Top Level Keys

Name	Type	Required	Description
rules	list	no	a list of rules
hostconfigs	list	no	a list of hostconfigs

rules and hostconfigs

Each rule and each hostconfig is a dictionary. It contains the key and value pairs of a Santa rule / hostconfig (see preflight response in documentation), with three additional optional keys.

Name	Type	Required	Description
any key from a santa rule/hostconfig	see santa documentation	see santa documentation	see santa documentation
row_id	varies based on database implementation	no	the row_id of the data in Krampus' database
targets	list of str	no	a list of targets for the rule/hostconfig. each string can be a machine_id, a primary_user, a group in primary_user_groups or "all". defaults to "all" if no target is set. applied before exclusions. only targeted machines will receive the rule/hostconfig, unless excluded.
exclusions	list of str	no	a list of exclusions for the rule/hostconfig. each string can be a machine_id, a primary_user, a primary_user_group or "all". applied after targets. excluded machines will not receive the rule/hostconfig, even if targeted.

Targets are applied before exclusions, so if a machine is targeted (e.g. because all computers are targeted) and also excluded (e.g. by machine_id), the rule/hostconfig will not be sent to this machine. Each machine can only receive one hostconfig per sync, so should only be targeted (and not excluded) once across all hostconfigs. If multiple hostconfigs apply, the hostconfig with the narrowest target will be chosen, looking first for a hostconfig targeting the machine_id, then primary_user, then one of the groups in primary_user_groups, then all.