[API] Correct iOS/iPadOS host vitals reference docs - #50343
Merged
Conversation
The merged reference docs for the 29 new iOS/iPadOS vitals describe several fields with a shape or value the API can't return. Diffed the documented example against the json tags on fleet.Host and its nested vitals structs: - accessibility_settings listed 8 keys without the _enabled suffix and omitted grayscale_enabled; there are 9, all suffixed - battery_level showed 82; it's a fraction between 0 and 1 - cellular_technology showed "LTE", which isn't one of the four values Apple defines - device_properties_attestation was an object with attestation status fields; it's an array of base64-encoded DER certificates - mdm_options listed two keys Fleet never returns and omitted prompt_user_to_allow_bootstrap_token_for_authentication - service_subscriptions omitted subscriber_carrier_network, and showed slot as "1" rather than the CoreTelephony constant devices actually report - supplemental_os_version_extra showed "a" rather than "(a)" Also documents the semantics an example can't convey — the cellular_technology values, the attestation chain ordering, the battery_level scale, and that a property the device doesn't report is omitted rather than nulled (with mdm_options as the exception) — and notes that accessibility_settings wasn't returned by manually-enrolled hosts in testing. Adds an iOS/iPadOS section to the host vitals architecture doc, which described collection as agent-only. Those hosts have no agent; their vitals come from the DeviceInformation MDM command, now linked to Apple's queries dictionary.
nulmete
marked this pull request as ready for review
July 31, 2026 20:09
nulmete
marked this pull request as draft
July 31, 2026 20:10
Drops two notes from the host response documentation: - battery_level: the corrected example already shows 0.82, so stating it's a fraction rather than a percentage only restates the example. It read as necessary while the example still said 82. - accessibility_settings: the observation that company-owned hosts returned it while manually-enrolled ones didn't came from a single round of testing, and supervision and enrollment method never varied independently in that sample, so it couldn't be attributed to either. Too provisional for reference docs. The remaining notes each carry something an all-populated example can't: that absent properties are omitted rather than nulled (with mdm_options as the exception), the full cellular_technology value set, and that the attestation array is an ordered DER certificate chain.
rachaelshaw
approved these changes
Aug 4, 2026
Leanngove
reviewed
Aug 4, 2026
| > - `signature_information` is only set for macOS (.app) applications. | ||
| > - Currently, the following are supported only for iOS/iPadOS: `accessibility_settings`, `app_analytics_enabled`, `awaiting_configuration`, `battery_level`, `bluetooth_mac`, `cellular_technology`, `data_roaming_enabled`, `device_properties_attestation`, `diagnostic_submission_enabled`, `eas_device_identifier`, `is_cloud_backup_enabled`, `is_device_locator_service_enabled`, `is_do_not_disturb_in_effect`, `is_mdm_lost_mode_enabled`, `is_network_tethered`, `itunes_store_account_hash`, `itunes_store_account_is_active`, `last_cloud_backup_date`, `mdm_options`, `model_number`, `modem_firmware_version`, `organization_info`, `personal_hotspot_enabled`, `push_token`, `service_subscriptions`, `supplemental_build_version`, `supplemental_os_version_extra`, `udid`, and `wifi_mac`. | ||
| > - These iOS/iPadOS vitals are collected via Apple's [`DeviceInformation`](https://developer.apple.com/documentation/devicemanagement/deviceinformationcommand/command-data.dictionary/queries-data.dictionary) MDM command. A property the device doesn't report is omitted from the response rather than returned as `null`. The exception is `mdm_options`, which is returned as an empty object when the device reports it with nothing set. | ||
| > - `cellular_technology` is one of `None`, `GSM`, `CDMA`, or `GSM and CDMA`. A value Apple adds in future that Fleet doesn't recognize is reported as `unknown`. |
Member
There was a problem hiding this comment.
Wording: "This will be unknown if Apple adds a value in the future that Fleet doesn't recognize." instead of "A value Apple adds in future that Fleet doesn't recognize is reported as unknown."
|
|
||
| ### iOS and iPadOS | ||
|
|
||
| iOS and iPadOS hosts don't run the agent, so the collection flow above doesn't apply to them. Their vitals come from the `DeviceInformation` MDM command instead, which Fleet sends on each refetch and whose response it parses and stores. |
Member
There was a problem hiding this comment.
Wording: "iOS and iPadOS hosts don't run the osquery agent" instead of "iOS and iPadOS hosts don't run the agent"
|
|
||
| > Note: Currently, the following are supported only for iOS/iPadOS: `accessibility_settings`, `app_analytics_enabled`, `awaiting_configuration`, `battery_level`, `bluetooth_mac`, `cellular_technology`, `data_roaming_enabled`, `device_properties_attestation`, `diagnostic_submission_enabled`, `eas_device_identifier`, `is_cloud_backup_enabled`, `is_device_locator_service_enabled`, `is_do_not_disturb_in_effect`, `is_mdm_lost_mode_enabled`, `is_network_tethered`, `itunes_store_account_hash`, `itunes_store_account_is_active`, `last_cloud_backup_date`, `mdm_options`, `model_number`, `modem_firmware_version`, `organization_info`, `personal_hotspot_enabled`, `push_token`, `service_subscriptions`, `supplemental_build_version`, `supplemental_os_version_extra`, `udid`, and `wifi_mac`. | ||
| > - These iOS/iPadOS vitals are collected via Apple's [`DeviceInformation`](https://developer.apple.com/documentation/devicemanagement/deviceinformationcommand/command-data.dictionary/queries-data.dictionary) MDM command. A property the device doesn't report is omitted from the response rather than returned as `null`. The exception is `mdm_options`, which is returned as an empty object when the device reports it with nothing set. | ||
| > - `cellular_technology` is one of `None`, `GSM`, `CDMA`, or `GSM and CDMA`. A value Apple adds in future that Fleet doesn't recognize is reported as `unknown`. |
Member
There was a problem hiding this comment.
Wording: "This will be unknown if Apple adds a value in the future that Fleet doesn't recognize." instead of "A value Apple adds in future that Fleet doesn't recognize is reported as unknown."
2 tasks
rachaelshaw
pushed a commit
that referenced
this pull request
Aug 4, 2026
<!-- Add the related story/sub-task/bug number, like Resolves #123, or remove if NA --> **Related issue:** NA — follow-up wording nits from review comments on #50343 # Checklist for submitter - [x] Changes file added for user-visible changes in `changes/`, `orbit/changes/` or `ee/fleetd-chrome/changes`. — NA, docs wording only, no changes file needed ## Testing - [x] QA'd all new/changed functionality manually — read-through of the rendered docs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related issue: Resolves #49987
The reference docs merged for the 29 new iOS/iPadOS host vitals in #48303 describe several fields with a shape or value the API can't actually return — notably
battery_levelas a percentage rather than a 0–1 fraction,device_properties_attestationas a status object rather than a certificate array, andcellular_technologyas"LTE", which isn't one of Apple's four values. An integration built against them would break.Testing