SecurityPatchState

Artifact: androidx.security:security-state

View Source

Added in 1.0.0

---

Kotlin |Java

open class SecurityPatchState

---

Provides methods to access and manage security state information for various components within a system. This class handles operations related to security patch levels, vulnerability reports, and update management.

Usage examples include:

• Fetching the current security patch level for specific system components.

• Retrieving published security patch levels to compare against current levels.

• Listing and applying security updates from designated update providers.

The class uses a combination of local data storage and external data fetching to maintain and update security states.

Recommended pattern of usage:

• call getVulnerabilityReportUrl and make a request to download the JSON file containing vulnerability report data

• create SecurityPatchState object, passing in the downloaded JSON as a String

• call getPublishedSecurityPatchLevel or other APIs

Summary

Nested types
@Retention(value = AnnotationRetention.SOURCE) @StringDef(open = true, value = ["SYSTEM", "SYSTEM_MODULES", "KERNEL", "VENDOR"]) annotation SecurityPatchState.Component Annotation for defining the component to use.
class SecurityPatchState.DateBasedSecurityPatchLevel : SecurityPatchState.SecurityPatchLevel Implementation of SecurityPatchLevel for a date-based patch level.
class SecurityPatchState.GenericStringSecurityPatchLevel : SecurityPatchState.SecurityPatchLevel Implementation of SecurityPatchLevel for a simple string patch level.
abstract class SecurityPatchState.SecurityPatchLevel : Comparable Abstract base class representing a security patch level.
enum SecurityPatchState.Severity : Enum Severity of reported security issues.
class SecurityPatchState.VersionedSecurityPatchLevel : SecurityPatchState.SecurityPatchLevel Implementation of SecurityPatchLevel for a versioned patch level.

Constants
const String	COMPONENT_KERNEL Kernel component providing kernel version as VersionedSpl.
const String	COMPONENT_SYSTEM System component providing ro.build.version.security_patch property value as DateBasedSpl.
const String	COMPONENT_SYSTEM_MODULES System modules component providing DateBasedSpl of system modules patch level.
const String	DEFAULT_VULNERABILITY_REPORTS_URL URL for the Google-provided data of vulnerabilities from Android Security Bulletin.
const Long	UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS = 5000 Timeout in milliseconds to wait for an IUpdateInfoService implementation to bind.

Public companion functions
SecurityPatchState.SecurityPatchLevel	getComponentSecurityPatchLevel(     @SecurityPatchState.Component component: String,     securityPatchLevel: String ) Retrieves the specific security patch level for a given component based on a security patch level string.
Uri	@RequiresApi(value = 26) getVulnerabilityReportUrl(serverUrl: Uri) Constructs a URL for fetching vulnerability reports based on the device's Android version.

Public companion properties
List<String>	DEFAULT_SYSTEM_MODULES Default list of Android Mainline system modules.

Public constructors
SecurityPatchState(     context: Context,     systemModulePackageNames: List<String>,     customSecurityStateManagerCompat: SecurityStateManagerCompat?,     vulnerabilityReportJsonString: String? ) Creates an instance of SecurityPatchState.

Public functions
Boolean	areCvesPatched(cveList: List<String>) Verifies if all specified CVEs have been patched in the system.
suspend SecurityPatchState.SecurityPatchLevel	fetchAvailableSecurityPatchLevel(     @SecurityPatchState.Component component: String,     timeoutMillis: Long ) Fetches the latest available security patch level for a specific component.
open SecurityPatchState.SecurityPatchLevel	getDeviceSecurityPatchLevel(     @SecurityPatchState.Component component: String ) Retrieves the current security patch level for a specified component.
open Map<SecurityPatchState.Severity, Set<String>>	getPatchedCves(     @SecurityPatchState.Component component: String,     spl: SecurityPatchState.SecurityPatchLevel ) Lists all security fixes applied on the current device since the baseline Android release of the current system image, filtered for a specified component and patch level, categorized by severity.
open List<SecurityPatchState.SecurityPatchLevel>	getPublishedSecurityPatchLevel(     @SecurityPatchState.Component component: String ) Retrieves the published security patch level for a specified component.
Boolean	isDeviceFullyUpdated() Checks if all components of the device have their security patch levels up to date with the published security patch levels.
Unit	@WorkerThread loadVulnerabilityReport(jsonString: String) Parses a JSON string to extract vulnerability report data.
suspend List<UpdateCheckResult>	queryAllAvailableUpdates(timeoutMillis: Long) Queries for available security updates from all trusted update providers.

Constants

COMPONENT_KERNEL

const val COMPONENT_KERNEL: String

Kernel component providing kernel version as VersionedSpl.

COMPONENT_SYSTEM

const val COMPONENT_SYSTEM: String

System component providing ro.build.version.security_patch property value as DateBasedSpl.

COMPONENT_SYSTEM_MODULES

const val COMPONENT_SYSTEM_MODULES: String

System modules component providing DateBasedSpl of system modules patch level.

DEFAULT_VULNERABILITY_REPORTS_URL

const val DEFAULT_VULNERABILITY_REPORTS_URL: String

URL for the Google-provided data of vulnerabilities from Android Security Bulletin.

UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS

const val UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS = 5000: Long

Timeout in milliseconds to wait for an IUpdateInfoService implementation to bind.

A 5-second timeout is standard for Android service binding to handle cases where the target service process hangs or fails to attach, preventing this API from suspending indefinitely.

Public companion functions

getComponentSecurityPatchLevel

Added in 1.0.0

fun getComponentSecurityPatchLevel(
    @SecurityPatchState.Component component: String,
    securityPatchLevel: String
): SecurityPatchState.SecurityPatchLevel

Retrieves the specific security patch level for a given component based on a security patch level string. This method determines the type of SecurityPatchLevel to construct based on the component type, interpreting the string as a date for date-based components or as a version number for versioned components.

Parameters
@SecurityPatchState.Component component: String	The component indicating which type of component's patch level is being requested.
securityPatchLevel: String	The string representation of the security patch level, which could be a date or a version number.

Returns
SecurityPatchState.SecurityPatchLevel	A SecurityPatchLevel instance corresponding to the specified component and patch level string.

Throws
IllegalArgumentException	If the input string is not in a valid format for the specified component type, or if the component requires a specific format that the string does not meet.

getVulnerabilityReportUrl

Added in 1.0.0

@RequiresApi(value = 26)
fun getVulnerabilityReportUrl(
    serverUrl: Uri = Uri.parse(DEFAULT_VULNERABILITY_REPORTS_URL)
): Uri

Constructs a URL for fetching vulnerability reports based on the device's Android version.

Parameters
serverUrl: Uri = Uri.parse(DEFAULT_VULNERABILITY_REPORTS_URL)	The base URL of the server where vulnerability reports are stored.

Returns
Uri	A fully constructed URL pointing to the specific vulnerability report for this device.

Public companion properties

DEFAULT_SYSTEM_MODULES

val DEFAULT_SYSTEM_MODULES: List<String>

Default list of Android Mainline system modules.

Public constructors

SecurityPatchState

Added in 1.0.0

SecurityPatchState(
    context: Context,
    systemModulePackageNames: List<String> = DEFAULT_SYSTEM_MODULES,
    customSecurityStateManagerCompat: SecurityStateManagerCompat? = null,
    vulnerabilityReportJsonString: String? = null
)

Creates an instance of SecurityPatchState.

Parameters
context: Context	Application context used for accessing shared preferences, resources, and other context-dependent features.
systemModulePackageNames: List<String> = DEFAULT_SYSTEM_MODULES	A list of system module package names, defaults to Google provided system modules if none are provided. The first module on the list must be the system modules metadata provider package.
customSecurityStateManagerCompat: SecurityStateManagerCompat? = null	An optional custom manager for obtaining security state information. If null, a default manager is instantiated.
vulnerabilityReportJsonString: String? = null	A JSON string containing vulnerability data to initialize a VulnerabilityReport object. If you only care about the Device SPL, this parameter is optional. If you need access to Published SPL and Available SPL, you must provide this JSON string, either here in the constructor, or later using loadVulnerabilityReport.

Public functions

areCvesPatched

Added in 1.0.0

fun areCvesPatched(cveList: List<String>): Boolean

Verifies if all specified CVEs have been patched in the system. This method aggregates the CVEs patched across specified system components and checks if the list includes all CVEs provided.

Parameters
cveList: List<String>	A list of CVE identifiers as strings in the form "CVE-YYYY-NNNNN", where YYYY denotes year, and NNNNN is a number with 3 to 5 digits.

Returns
Boolean	true if all provided CVEs are patched, false otherwise.

fetchAvailableSecurityPatchLevel

suspend fun fetchAvailableSecurityPatchLevel(
    @SecurityPatchState.Component component: String,
    timeoutMillis: Long = UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS
): SecurityPatchState.SecurityPatchLevel

Fetches the latest available security patch level for a specific component.

This is a convenience method that determines the effective security state by aggregating results from all trusted providers and comparing them against the device's current state.

Performance: This method performs IPC (Inter-Process Communication) to query trusted services. While the providers themselves may return cached data without triggering a network call, the service binding process is asynchronous and significantly heavier than local memory lookups.

Aggregation Logic: If multiple providers report updates for the same component (e.g., both an OEM updater and GOTA report a "SYSTEM" update), this method conservatively selects the newest (highest version/date) patch level among them.

Note: This value is based on the server-side state known to the update clients. It may not represent a real-time check if the update client has restricted background syncs (e.g., due to rate limiting or battery saver).

Parameters
@SecurityPatchState.Component component: String	The component to check (e.g., COMPONENT_SYSTEM, COMPONENT_SYSTEM_MODULES).
timeoutMillis: Long = UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS	The maximum time to wait for the query to complete, in milliseconds. Defaults to UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS.

Returns
SecurityPatchState.SecurityPatchLevel	The latest SecurityPatchLevel found. If no updates are available, or if the available updates are older than or equal to the current device state, this returns the current Device SPL.

getDeviceSecurityPatchLevel

Added in 1.0.0

open fun getDeviceSecurityPatchLevel(
    @SecurityPatchState.Component component: String
): SecurityPatchState.SecurityPatchLevel

Retrieves the current security patch level for a specified component.

Parameters
@SecurityPatchState.Component component: String	The component for which the security patch level is requested.

Returns
SecurityPatchState.SecurityPatchLevel	A SecurityPatchLevel representing the current patch level of the component.

Throws
IllegalStateException	if the patch level data is not available.
IllegalArgumentException	if the component name is unrecognized.

getPatchedCves

Added in 1.0.0

open fun getPatchedCves(
    @SecurityPatchState.Component component: String,
    spl: SecurityPatchState.SecurityPatchLevel
): Map<SecurityPatchState.Severity, Set<String>>

Lists all security fixes applied on the current device since the baseline Android release of the current system image, filtered for a specified component and patch level, categorized by severity.

Parameters
@SecurityPatchState.Component component: String	The component for which security fixes are listed.
spl: SecurityPatchState.SecurityPatchLevel	The security patch level for which fixes are retrieved.

Returns

Map<SecurityPatchState.Severity, Set<String>>

A map categorizing CVE identifiers by their severity for the specified patch level. For example: `` { Severity.CRITICAL: ["CVE-2023-1234", "CVE-2023-5678"], Severity.HIGH: ["CVE-2023-9012"], Severity.MODERATE: ["CVE-2023-3456"] } `` @throws IllegalArgumentException if the specified component is not valid for fetching security fixes. @throws IllegalStateException if the vulnerability report is not loaded.

getPublishedSecurityPatchLevel

Added in 1.0.0

open fun getPublishedSecurityPatchLevel(
    @SecurityPatchState.Component component: String
): List<SecurityPatchState.SecurityPatchLevel>

Retrieves the published security patch level for a specified component. This patch level is based on the most recent vulnerability reports, which is a machine-readable data from Android and other security bulletins.

The published security patch level is the most recent value published in a bulletin.

Parameters
@SecurityPatchState.Component component: String	The component for which the published patch level is requested.

Returns

List<SecurityPatchState.SecurityPatchLevel>

A list of SecurityPatchLevel representing the published patch levels. The list contains single element for all components, except for KERNEL, where it lists kernel LTS version numbers for all supported major kernel versions. For example: `` [ "4.19.314", "5.15.159", "6.1.91" ] `` @throws IllegalStateException if the vulnerability report is not loaded or if patch level data is unavailable. @throws IllegalArgumentException if the component name is unrecognized.

isDeviceFullyUpdated

Added in 1.0.0

fun isDeviceFullyUpdated(): Boolean

Checks if all components of the device have their security patch levels up to date with the published security patch levels. This method compares the device's current security patch level against the latest published levels for each component.

Returns
Boolean	true if all components are fully updated, false otherwise.

Throws
IllegalArgumentException	if device or published security patch level for a component cannot be accessed.

loadVulnerabilityReport

Added in 1.0.0

@WorkerThread
fun loadVulnerabilityReport(jsonString: String): Unit

Parses a JSON string to extract vulnerability report data. This method validates the format of the input JSON and constructs a VulnerabilityReport object, preparing the class to provide published and available security state information.

Parameters
jsonString: String	The JSON string containing the vulnerability data.

Throws
IllegalArgumentException	if the JSON input is malformed or contains invalid data.

queryAllAvailableUpdates

suspend fun queryAllAvailableUpdates(
    timeoutMillis: Long = UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS
): List<UpdateCheckResult>

Queries for available security updates from all trusted update providers.

This method performs a comprehensive check by:

1. Discovering all trusted services on the device that implement the UpdateInfoService protocol (e.g., c, Google Play Store).

2. Querying each service concurrently to retrieve its status.

3. Collecting the results into a list.

Freshness & Caching: The freshness of the returned data depends on the internal policies of the individual update providers. Providers are expected to maintain a reasonably fresh cache (typically refreshing at least once per hour). If a provider determines its cache is stale, this call may block while it performs a network fetch.

Parameters
timeoutMillis: Long = UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS	The maximum time to wait for each provider to respond, in milliseconds. Defaults to UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS.

Returns
List<UpdateCheckResult>	A list of UpdateCheckResult objects. Each element represents the status reported by a distinct update provider, containing its list of updates and the timestamp of its last successful synchronization.