Supported Configuration Keys

You can configure the behaviour of nudge-auto-updater with a YAML-formatted configuration file. By default, nudge-auto-updater will look for a configuration file named configuration.yml in the current working directory.

Note

nudge-auto-updater only assesses the latest macOS version(s) (that satisifies your criteria) for suitability, and does not take into account your current target macOS version(s). This means that nudge-auto-updater will only apply rules on the CVEs patched in that latest release, not on the total list of CVEs patched between your current target version and that latest release.

Top-level keys

Name	Type	Required	Description
targets	list	yes	A list of Nudge osVersionRequirements rules to target. These rules are described in targets
cve_urgency_levels	list	no	A list of rules, defining macOS update enforcement cadences, and what CVE-related conditions are required to meet them. These rules are described in cve_urgency_levels
default_deadline_days	int	yes	Specifies the number of days after the macOS update release that will be set as Nudge's requiredInstallationDate, assuming that the release doesn't meet any of the rules defined in cve_urgency_levels (if any).

targets

Targets in your configuration files must match existing targets in your nudge configuration which you wish for nudge-auto-updater to update. Each target in the list is a dictionary.

Key	Type	Required	Description
target	string	yes	Specifies the targetedOSVersionsRule in Nudge.
update_to	string	yes	Specifies the macOS version this target should update to. This value can be "latest" if the requiredMinimumOSVersion should be the latest version of macOS. Otherwise this value can be a major version (e.g. 13), a minor version (e.g. 13.1) or a specific patch version (e.g. 13.1.1). In this case the requiredMinimumOSVersion will be set to the newest macOS version with a major version, minor version or patch version less than or equal to the specified value.

cve_urgency_levels

These levels are an ordered list of urgency levels, which are evaluated top-to-bottom. A macOs update is compared to a level of urgency based on that levels cve_urgency_conditions. These conditions themselves relate to the (public) CVEs patched by that macOS update. If your organisation has macOS update enforcement SLAs based on e.g. the number of critical CVEs in a macOS update, you can specify those here.

Key	Type	Required	Description
cve_urgency_conditions	dict	yes	A set of conditions to check the CVEs that a macOS update fixes against. Structure is documented in cve_urgency_conditions
deadline_days	int	yes	Specifies the number of days after the macOS update release that will be set as Nudge's requiredInstallationDate, if this rule is met.
name	string	no	A human-readable name for the cve_urgency_level. This will be used in the results output of both the Slack webhook and the Markdown file. If no name is set for a cve_urgency_level, it will be printed in results output as "level x", where x is the level's position in the cve_urgency_levels list (zero-indexed).
conjunction	bool	no	Defaults to False. Determines whether conditions are evaluated as a conjunction (logically ANDed together, all conditions must be true), or as a disjunction (logically ORed together, at least one condition must be true).

cve_urgency_conditions

These conditions can make reference to the scores provided by the NVD for a given vulnerability. For example, CVE-2023-42916 has a base score of 6.5, an exploitability score of 2.8, and an impact score of 3.6.

Warning

Due to delays enriching CVEs at NIST, recent CVEs may not have scores provided. If a score-based condition, formula-based condition, or match-n-CVEs condition is evaluated when no CVEs have scoring data, the condition will be considered to be "unmet". Note that you can set conditions based on the total count of CVEs, total count of actively exploited CVEs or the proportion of actively exploited CVEs patched in a release, as reported by Apple. Such conditions are unaffected by whether or not the relevant CVEs have been scored.

Key	Type	Description
max_baseScore	int/float	Defines the base score at which this condition will be considered true. Evaluates to "true" if the base score of any CVE patched in a release is greater than or equal to this value.
average_baseScore	int/float	Defines the average base score at which this condition will be considered true. Evaluates to "true" if the average base score of all CVEs patched in a release is greater than or equal to this value.
max_exploitabilityScore	int/float	Defines the exploitability score at which this condition will be considered true. Evaluates to "true" if the exploitability score of any CVE patched in a release is greater than or equal to this value.
average_exploitabilityScore	int/float	Defines the average exploitability score at which this condition will be considered true. Evaluates to "true" if the average exploitability score of all CVEs patched in a release is greater than or equal to this value.
max_impactScore	int/float	Defines the impact score at which this condition will be considered true. Evaluates to "true" if the impact score of any CVE patched in a release is greater than or equal to this value.
average_impactScore	int/float	Defines the average impact score at which this condition will be considered true. Evaluates to "true" if the average impact score of all CVEs patched in a release is greater than or equal to this value.
number_CVEs	int	Defines the number of CVEs that must be patched in a release, at which this condition will be considered true. Evaluates to "true" if the number of CVEs patched in a macOS release is greater than or equal to this value.
number_actively_exploited_CVEs	int	Defines the number of actively exploited CVEs that must be patched in a release, at which this condition will be considered true. Evaluates to "true" if the number of actively exploited CVEs patched in a macOS release is greater than or equal to this value.
fraction_actively_exploited_CVEs	float	Defines the proportion of CVEs patched in a release that are being actively exploited, at which this condition will be considered true. Evaluates to "true" if the proportion of CVEs patched in a release that are being actively exploited is greater than or equal to this value. The calculated proportion for a given release is calculated as number of actively exploited CVEs patched in a release ÷ number of CVEs patched in a release.
formulas	list	A list of formulas to use as rules. These rules are described in formulas
match_n_CVEs_conditions	list	A list of conditions that are assessed per-CVE. These conditions are described in match_n_CVEs_conditions

formulas

formulas are an advanced method of calculating conditions, to be used when you have a specific mathematical formula for determining the urgency of a macOS release. Note that formulas will only be evaluated for a given CVE if the CVE scores have been provided by NIST. For this reason we recommend using the number_actively_exploited_CVEs or fraction_actively_exploited_CVEs conditions when interested only in whether CVEs are actively exploited.

Key	Type	Required	Description
formula	string	No	An arithmetic formula that is calculated per-CVE patched in a macOS release. Available variables are: baseScore, exploitabilityScore, impactScore, and is_actively_exploited. is_actively_exploited is either 0 (for false), or 1 (for true), while the others are floats between 0.0 and 10.0.
comparison	string	No	The type of comparison performed between all evaluations of the above formula, and the threshold specified below. Can be one of either average (averages the results of the formula across each CVE patched in a release), max (gets the largest result of the formula across each CVE patched in a release), sum (gets the sum of all of the results of the formula across each CVE patched in a release), or n_above (determines whether there are n CVEs patched in a release for which the result of formula is above the threshold).
threshold	int	No	The threshold that the results from comparison and formula must be greater or equal to for this formula to be considered "true".
n	int	Only if comparison is set to n_above	Specifies the number of CVEs that must have the result of their formulas above the threshold for a formula block to be considered "true".

Example

Let's step through a simple example of the formulas block:

formulas:
  - comparison: "average"
    formula: "baseScore * exploitabilityScore * impactScore"
    threshold: 100
  - comparison: "max"
    formula: "baseScore * exploitabilityScore * impactScore * is_actively_exploited"
    threshold: 200
  - comparison: "sum"
    formula: "baseScore  * impactScore * is_actively_exploited"
    threshold: 300
  - comparison: "n_above"
    formula: "baseScore  * impactScore * is_actively_exploited"
    n: 2
    threshold: 150

The first entry in our list checks whether the average of baseScore * exploitabilityScore * impactScore for all CVEs patched in a release is greater than or equal to the threshold of 100.

The second entry in our list checks whether the max value of baseScore * exploitabilityScore * impactScore * is_actively_exploited for all CVEs patched in a release is greater than or equal to the threshold of 200.

The third entry in our list checks whether the sum of baseScore * impactScore * is_actively_exploited for all CVEs patched in a release is greater than or equal to the threshold of 300.

The fourth entry in our list checks whether the results of baseScore * impactScore * is_actively_exploited are greater than or equal to the threshold of 150 for n or more of the CVEs patched in a given macOS release.

match_n_CVEs_conditions

match_n_CVEs_conditions are useful if you want to check each CVE individually against multiple conditions. This match_n_CVEs_condition is met when at least a given number of CVEs (specified by n) meet all the conditions specified in the match_n_CVEs_condition. Note that these conditions will only be evaluated for a given CVE if the CVE has been analysed and given a CVSS scoring by NIST. For this reason we recommend using the number_actively_exploited_CVEs or fraction_actively_exploited_CVEs conditions when interested only in whether CVEs are actively exploited.

A match_n_CVEs_condition is defined by a dictionary with the following keys:

Key	Type	Required	Description
n	int	yes	The number of CVES that must meet all the conditions defined in the match_n_CVEs_condition
baseScore	int/float	no	The base score threshold that a CVE must meet for this condition to be true for that CVE.
exploitabilityScore	int/float	no	The exploitability score threshold that a CVE must meet for this condition to be true for that CVE.
impactScore	int/float	no	The impact score threshold that a CVE must meet for this condition to be true for that CVE.
is_actively_exploited	int/float	no	Whether or not a CVE must be actively exploited for this condition to be true for that CVE.
formulas	list	no	A list of formulas that a CVE must meet for this condition to be true for that CVE. These formulas also follow the structure set forward in formulas, but because they are evaluated per-CVE, the comparison key is not required and will not be respected.

Example

Here is an example match_n_CVEs_conditions block:

match_n_CVEs_conditions: 
  - n: 1
    baseScore: 8
    impactScore: 5
    exploitabilityScore: 9
    formulas:
      - formula: "baseScore + impactScore"
        threshold: 15

This condition will evaluate to true if at least one CVE was patched in a release where:

• The base score of that CVE was >= 8, and
• The impact score of that CVE was >= 5, and
• The exploitability score of that CVE was >= 9, and
• The result of the sum of the base score of that CVE and the impact score of that CVE is >= 15