Health Analyzer Module

Comprehensive health analysis for computers managed by Jamf Pro.

Grading and Scoring

Basic Python enumeration classes for health grade and health status.

Health Grade

class HealthGrade(*values)

Bases: str, Enum

Health grade enumeration.

A = 'A'

B = 'B'

C = 'C'

D = 'D'

F = 'F'

Health Status

class HealthStatus(*values)

Bases: str, Enum

Health status enumeration.

EXCELLENT = 'Excellent'

GOOD = 'Good'

FAIR = 'Fair'

POOR = 'Poor'

CRITICAL = 'Critical'

Health Analyzer Data Models

Pydantic data model configurations for Health Analyzer functionality.

Health Score

Individual category score with details.

class HealthScore(*, category: str, score: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], max_score: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], weight: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], factors: list[str] = <factory>, recommendations: list[str] = <factory>)

Bases: BaseModel

Individual health metric score with details.

Parameters:

• category (str)

• score (float)

• max_score (float)

• weight (float)

• factors (list[str])

• recommendations (list[str])

field category: str [Required]

The health category being scored

field score: float [Required]

Score from 0-100

Constraints:

• ge = 0

• le = 100

field max_score: float [Required]

Maximum possible score

Constraints:

• ge = 0

• le = 100

field weight: float [Required]

Weight in overall calculation

Constraints:

• ge = 0

• le = 1

field factors: list[str] [Optional]

Factors affecting this score

field recommendations: list[str] [Optional]

Improvement recommendations

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Health Scorecard

The complete health assessment result.

class HealthScorecard(*, overall_score: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], grade: ~jamfmcp.health_analyzer.HealthGrade, status: ~jamfmcp.health_analyzer.HealthStatus, security_score: ~jamfmcp.health_analyzer.HealthScore, system_health_score: ~jamfmcp.health_analyzer.HealthScore, compliance_score: ~jamfmcp.health_analyzer.HealthScore, maintenance_score: ~jamfmcp.health_analyzer.HealthScore, device_info: dict[str, ~typing.Any] = <factory>, assessment_timestamp: ~datetime.datetime = <factory>, critical_issues: list[str] = <factory>, recommendations: list[str] = <factory>)

Bases: BaseModel

Complete computer health scorecard.

Parameters:

• overall_score (float)

• grade (HealthGrade)

• status (HealthStatus)

• security_score (HealthScore)

• system_health_score (HealthScore)

• compliance_score (HealthScore)

• maintenance_score (HealthScore)

• device_info (dict[str, Any])

• assessment_timestamp (datetime)

• critical_issues (list[str])

• recommendations (list[str])

field overall_score: float [Required]

Overall health percentage

Constraints:

• ge = 0

• le = 100

field grade: HealthGrade [Required]

Letter grade (A, B, C, D, F)

field status: HealthStatus [Required]

Health status description

field security_score: HealthScore [Required]

field system_health_score: HealthScore [Required]

field compliance_score: HealthScore [Required]

field maintenance_score: HealthScore [Required]

field device_info: dict[str, Any] [Optional]

field assessment_timestamp: datetime [Optional]

field critical_issues: list[str] [Optional]

field recommendations: list[str] [Optional]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Core Classes

HealthAnalyzer

The main analyzer class that processes computer data and generates health scorecards.

class HealthAnalyzer(diagnostic_data: dict[str, Any] | None = None, computer_history: dict[str, Any] | None = None, computer_inventory: dict[str, Any] | None = None, sofa_feed: SOFAFeed | None = None)

Bases: object

Analyzes computer health from Jamf Pro diagnostic data.

This class processes comprehensive diagnostic information from Jamf Pro to generate detailed health scorecards with actionable recommendations.

Parameters:

• diagnostic_data (dict[str, Any]) – Parsed diagnostic data from Jamf Pro

• computer_history (dict[str, Any] | None) – Computer history data containing usage and policy logs

• computer_inventory (dict[str, Any] | None) – Full computer inventory data

• sofa_feed (SOFAFeed | None)

Example:

>>> analyzer = HealthAnalyzer(diag_data, history_data, inventory_data)
>>> scorecard = analyzer.generate_health_scorecard()
>>> print(f"Overall Health: {scorecard.overall_score}%")

__init__(diagnostic_data: dict[str, Any] | None = None, computer_history: dict[str, Any] | None = None, computer_inventory: dict[str, Any] | None = None, sofa_feed: SOFAFeed | None = None) → None

Initialize the health analyzer with optional diagnostic data and SOFA feed.

If diagnostic_data is not provided but computer_inventory is available, the diagnostic data will be automatically parsed from the inventory.

Parameters:

• diagnostic_data (dict[str, Any] | None) – Parsed diagnostic data from Jamf Pro (optional)

• computer_history (dict[str, Any] | None) – Computer history data containing usage and policy logs

• computer_inventory (dict[str, Any] | None) – Full computer inventory data

• sofa_feed (SOFAFeed | None) – SOFA feed for CVE and OS currency analysis (optional)

Return type:

None

generate_health_scorecard() → HealthScorecard

Generate comprehensive health scorecard.

Analyzes all health categories and produces a detailed scorecard with overall health percentage, individual category scores, and actionable recommendations.

Returns:

Complete HealthScorecard with scores and recommendations

Return type:

HealthScorecard

parse_diags(payload: dict[str, Any]) → dict[str, str]

Parse comprehensive device diagnostics information from Jamf Pro payload.

Leverages the Computer model for structured data parsing and validation. Compiles a complete diagnostic report including general device information, hardware details, security status, user assignment, and security tool status.

Parameters:

payload (dict[str, Any]) – The Jamf API response payload containing device information

Returns:

Complete device diagnostics dictionary with formatted values

Return type:

dict[str, str]

Raises:

Exception – If payload parsing fails with detailed error information

CATEGORY_WEIGHTS = {'compliance': 0.25, 'maintenance': 0.15, 'security': 0.35, 'system_health': 0.25}

RECENT_CHECKIN_THRESHOLD = 24

RECENT_ACTIVITY_THRESHOLD = 72

ACCEPTABLE_UPTIME_MAX = 336

async static load_sofa_feed() → SOFAFeed | None

Load the latest SOFA feed data for CVE and OS analysis.

Returns:

Parsed SOFA feed or None if loading fails

Return type:

SOFAFeed | None

get_cve_analysis(include_detailed_cves: bool = False) → dict[str, Any] | None

Analyze CVE vulnerabilities affecting the current OS version.

Parameters:

include_detailed_cves (bool) – Include detailed CVE information in the analysis

Returns:

CVE analysis dictionary with vulnerability counts and risk assessment, or None if analysis unavailable

Return type:

dict[str, Any] | None

generate_health_scorecard() → HealthScorecard

Generate comprehensive health scorecard.

Analyzes all health categories and produces a detailed scorecard with overall health percentage, individual category scores, and actionable recommendations.

Returns:

Complete HealthScorecard with scores and recommendations

Return type:

HealthScorecard

parse_diags(payload: dict[str, Any]) → dict[str, str]

Parse comprehensive device diagnostics information from Jamf Pro payload.

Leverages the Computer model for structured data parsing and validation. Compiles a complete diagnostic report including general device information, hardware details, security status, user assignment, and security tool status.

Parameters:

payload (dict[str, Any]) – The Jamf API response payload containing device information

Returns:

Complete device diagnostics dictionary with formatted values

Return type:

dict[str, str]

Raises:

Exception – If payload parsing fails with detailed error information

Helper Functions

fmt_tmz(time_input: str | datetime) → str

Format timestamp string or datetime object to human-readable format.

Converts ISO 8601 timestamp string with timezone information or datetime object to a formatted string in “Month DD YYYY HH:MM AM/PM” format.

Parameters:

time_input (str | datetime) – ISO 8601 timestamp string with timezone or datetime object

Returns:

Formatted timestamp string

Return type:

str

Health Scoring System

Category Weights

The analyzer evaluates computers across four weighted categories:

CATEGORY_WEIGHTS = {
    "security": 0.35,      # 35% - Security is critical
    "system_health": 0.25, # 25% - System performance and hardware
    "compliance": 0.25,    # 25% - Policy and management compliance
    "maintenance": 0.15,   # 15% - Regular maintenance and updates
}

Security Score Components

Component	Weight	Description
FileVault	25%	Disk encryption status
SIP	20%	System Integrity Protection
Gatekeeper	15%	App security verification
Firewall	15%	Network protection
CVEs	25%	Known vulnerabilities

System Health Components

Component	Weight	Description
Storage	30%	Available disk space
Battery	25%	Battery health (laptops)
Uptime	20%	System stability
Hardware	25%	Component status

Compliance Components

Component	Weight	Description
Check-in	40%	Recent communication
Policies	30%	Policy execution status
Profiles	30%	Configuration compliance

Maintenance Components

Component	Weight	Description
OS Updates	50%	Operating system currency
App Updates	30%	Application versions
Certificates	20%	Certificate validity

Recommendation Engine

The analyzer generates actionable recommendations based on findings:

Security Recommendations

• Enable FileVault encryption

• Enable System Integrity Protection

• Turn on Firewall

• Update to patch CVEs

System Health Recommendations

• Free up disk space

• Replace aging battery

• Restart to clear uptime

• Address hardware issues

Compliance Recommendations

• Configure regular check-ins

• Fix failing policies

• Deploy missing profiles

Maintenance Recommendations

• Install OS updates

• Update applications

• Renew certificates