Analyze#

Analyzes an exported patch report in Excel format and outputs analyzed results. The Analyzer class works in conjunction with DataManager objects to retrieve cached data and stored PatchTitle objects.

Parameters#

excel_file(str)

Path to the Excel file containing patch management data.

all_time(bool)

Allows for analyzation of patch report trends across all cached data instead of a single dataset. See TrendCriteria.

threshold(float)

Filters software titles that are below the specified completion percentage.

criteria(str)

Specifies the criteria for filtering patches. See FilterCriteria.

Additional criteria can be passed when using the --all-time flag. See TrendCriteria. Trend criteria options are:

  • patch_adoption: Calculates completion rates over time for different software titles.

  • release_frequency: Analyzes the release frequency of updates for software titles.

  • completion_trends: Evaluates the correlation between release dates and completion percentages.

top_n(int)

Number of top entries to display based on the criteria. Default is None, meaning all results will be returned.

summary(bool)

If passed, will generate a summary file in .html format in addition to showing results in stdout.

Note

The --summary option requires an output directory specified via --output-dir. Ensure the directory exists and has write permissions before running the command. Otherwise, the summary file will not be generated.

output_dir(Union[str | Path])

Directory to save generated summary if --summary flag is passed. HTML report will follow a similar naming scheme to exported reports (i.e., patch-analysis-<current-date>.html).

Criteria#

Two types of criteria can be specified when leveraging the analyze command, however they are used in different contexts.

Note

Both criteria classes automatically handle formatting arguments to the CLI. For example, when analyzing for most installed software titles, --criteria most-installed is automatically converted to most_installed at runtime.

Filter Criteria Options#

Criteria

Description

most-installed

Displays software titles with the highest number of total installations.

least-installed

Shows the top 5 least-installed software titles. Use --top-n to limit results.

oldest-least-complete

Returns the oldest patches with the least completion percent.

below-threshold

Filters software titles with completion percentage below specified threshold.

recent-release

Filters for patches released in the last week.

zero-completion

Displays software titles with 0% completion.

top-performers

Lists software titles with completion percentage above 90%.

high-missing

Filters software titles where missing patches are greater than 50% of total hosts.

installomator

Returns PatchTitles that have Installomator labels. Helpful to identify which software titles support automated patching.

Trend Criteria Options#

Criteria

Description

patch-adoption

Calculates completion rates over time for different software titles.

release-frequency

Analyzes the release frequency of updates for software titles.

completion-trends

Evaluates the correlation between release dates and completion percentages.

Usage#

Note

Providing an Excel file to the analyze command is optional. In the usage examples below, optional paths are indicated by square brackets.

Filter Criteria#

Analyze with Threshold
$ patcherctl analyze [/path/to/excel.xlsx] --criteria below-threshold --threshold 50.0
Analyze Most Installed
$ patcherctl analyze [/path/to/excel.xlsx] --criteria most-installed
Analyze Least Installed
$ patcherctl analyze [/path/to/excel.xlsx] --criteria least-installed --top-n 5
Analyze Recent Releases
$ patcherctl analyze [/path/to/excel.xlsx] --criteria recent-release

Tip

Additionally, option is particularly useful for organizations with Service Level Agreements (SLAs) or policies that mandate installing new patches within a specific time frame (e.g., within 7 days of release).

Analyze Zero Completion
$ patcherctl analyze [/path/to/excel.xlsx] --criteria zero-completion
Analyze High Missing
$ patcherctl analyze [/path/to/excel.xlsx] --criteria high-missing --top-n 10
Oldest Least Complete
$ patcherctl analyze [/path/to/excel.xlsx] --criteria oldest-least-complete
Top Performers
$ patcherctl analyze [/path/to/excel.xlsx] --criteria top-performers
Installomator
$ patcherctl analyze [/path/to/excel.xlsx] --criteria installomator

Trend Criteria#

Patch Adoption
$ patcherctl analyze --criteria patch-adoption
Release Frequency
$ patcherctl analyze --criteria release-frequency
Completion Trends
$ patcherctl analyze --criteria completion-trends