SecurityPatchState

Artifact: androidx.security:security-state

Added in 1.0.0

Kotlin |Java

public 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"]) public annotation SecurityPatchState.Component` Annotation for defining the component to use.
`public final class SecurityPatchState.DateBasedSecurityPatchLevel extends SecurityPatchState.SecurityPatchLevel` Implementation of `SecurityPatchLevel` for a date-based patch level.
`public final class SecurityPatchState.GenericStringSecurityPatchLevel extends SecurityPatchState.SecurityPatchLevel` Implementation of `SecurityPatchLevel` for a simple string patch level.
`public abstract class SecurityPatchState.SecurityPatchLevel implements Comparable` Abstract base class representing a security patch level.
`public enum SecurityPatchState.Severity extends Enum` Severity of reported security issues.
`public final class SecurityPatchState.VersionedSecurityPatchLevel extends SecurityPatchState.SecurityPatchLevel` Implementation of `SecurityPatchLevel` for a versioned patch level.

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

Public fields
`static final @NonNull List<@NonNull String>`	`DEFAULT_SYSTEM_MODULES` Default list of Android Mainline system modules.

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

Public methods
`final boolean`	`areCvesPatched(@NonNull List<@NonNull String> cveList)` Verifies if all specified CVEs have been patched in the system.
`final @NonNull SecurityPatchState.SecurityPatchLevel`	`fetchAvailableSecurityPatchLevel( @SecurityPatchState.Component @NonNull String component, long timeoutMillis )` Fetches the latest available security patch level for a specific component.
`final @NonNull ListenableFuture<@NonNull SecurityPatchState.SecurityPatchLevel>`	`fetchAvailableSecurityPatchLevelAsync( @SecurityPatchState.Component @NonNull String component, long timeoutMillis )` Fetches the latest available security patch level for a specific component.
`static final @NonNull SecurityPatchState.SecurityPatchLevel`	`getComponentSecurityPatchLevel( @SecurityPatchState.Component @NonNull String component, @NonNull String securityPatchLevel )` Retrieves the specific security patch level for a given component based on a security patch level string.
`@NonNull SecurityPatchState.SecurityPatchLevel`	`getDeviceSecurityPatchLevel( @SecurityPatchState.Component @NonNull String component )` Retrieves the current security patch level for a specified component.
`@NonNull Map<@NonNull SecurityPatchState.Severity, @NonNull Set<@NonNull String>>`	`getPatchedCves( @SecurityPatchState.Component @NonNull String component, @NonNull SecurityPatchState.SecurityPatchLevel spl )` 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.
`@NonNull List<@NonNull SecurityPatchState.SecurityPatchLevel>`	`getPublishedSecurityPatchLevel( @SecurityPatchState.Component @NonNull String component )` Retrieves the published security patch level for a specified component.
`static final @NonNull Uri`	`@RequiresApi(value = 26) getVulnerabilityReportUrl(@NonNull Uri serverUrl)` Constructs a URL for fetching vulnerability reports based on the device's Android version.
`final boolean`	`isDeviceFullyUpdated()` Checks if all components of the device have their security patch levels up to date with the published security patch levels.
`final void`	`@WorkerThread loadVulnerabilityReport(@NonNull String jsonString)` Parses a JSON string to extract vulnerability report data.
`final @NonNull List<@NonNull UpdateCheckResult>`	`queryAllAvailableUpdates(long timeoutMillis)` Queries for available security updates from all trusted update providers.
`final @NonNull ListenableFuture<@NonNull List<@NonNull UpdateCheckResult>>`	`queryAllAvailableUpdatesAsync(long timeoutMillis)` Queries for available security updates from all trusted update providers.

Constants

COMPONENT_KERNEL

public static final @NonNull String COMPONENT_KERNEL

Kernel component providing kernel version as VersionedSpl.

COMPONENT_SYSTEM

public static final @NonNull String COMPONENT_SYSTEM

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

COMPONENT_SYSTEM_MODULES

public static final @NonNull String COMPONENT_SYSTEM_MODULES

System modules component providing DateBasedSpl of system modules patch level.

DEFAULT_VULNERABILITY_REPORTS_URL

public static final @NonNull String DEFAULT_VULNERABILITY_REPORTS_URL

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

UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS

public static final long UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS = 5000

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 fields

DEFAULT_SYSTEM_MODULES

public static final @NonNull List<@NonNull String> DEFAULT_SYSTEM_MODULES

Default list of Android Mainline system modules.

Public constructors

SecurityPatchState

Added in 1.0.0

public SecurityPatchState(
    @NonNull Context context,
    @NonNull List<@NonNull String> systemModulePackageNames,
    SecurityStateManagerCompat customSecurityStateManagerCompat,
    String vulnerabilityReportJsonString
)

Creates an instance of SecurityPatchState.

Parameters
`@NonNull Context context`	Application context used for accessing shared preferences, resources, and other context-dependent features.
`@NonNull List<@NonNull String> systemModulePackageNames`	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.
`SecurityStateManagerCompat customSecurityStateManagerCompat`	An optional custom manager for obtaining security state information. If null, a default manager is instantiated.
`String vulnerabilityReportJsonString`	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 methods

areCvesPatched

Added in 1.0.0

public final boolean areCvesPatched(@NonNull List<@NonNull String> cveList)

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
`@NonNull List<@NonNull String> cveList`	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

public final @NonNull SecurityPatchState.SecurityPatchLevel fetchAvailableSecurityPatchLevel(
    @SecurityPatchState.Component @NonNull String component,
    long timeoutMillis
)

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 @NonNull String component`	The component to check (e.g., `COMPONENT_SYSTEM`, `COMPONENT_SYSTEM_MODULES`).
`long timeoutMillis`	The maximum time to wait for the query to complete, in milliseconds. Defaults to `UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS`.

Returns
`@NonNull 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.

fetchAvailableSecurityPatchLevelAsync

Added in 1.1.0-beta02

public final @NonNull ListenableFuture<@NonNull SecurityPatchState.SecurityPatchLevel> fetchAvailableSecurityPatchLevelAsync(
    @SecurityPatchState.Component @NonNull String component,
    long timeoutMillis
)

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

This is the Java-friendly variant of fetchAvailableSecurityPatchLevel returning a ListenableFuture.

Parameters
`@SecurityPatchState.Component @NonNull String component`	The component to check.
`long timeoutMillis`	The maximum time to wait for the query to complete, in milliseconds.

Returns
`@NonNull ListenableFuture<@NonNull SecurityPatchState.SecurityPatchLevel>`	A `ListenableFuture` containing the latest `SecurityPatchLevel`.

getComponentSecurityPatchLevel

Added in 1.0.0

public static final @NonNull SecurityPatchState.SecurityPatchLevel getComponentSecurityPatchLevel(
    @SecurityPatchState.Component @NonNull String component,
    @NonNull String 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 @NonNull String component`	The component indicating which type of component's patch level is being requested.
`@NonNull String securityPatchLevel`	The string representation of the security patch level, which could be a date or a version number.

Returns
`@NonNull 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.

getDeviceSecurityPatchLevel

Added in 1.0.0

public @NonNull SecurityPatchState.SecurityPatchLevel getDeviceSecurityPatchLevel(
    @SecurityPatchState.Component @NonNull String component
)

Retrieves the current security patch level for a specified component.

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

Returns
`@NonNull 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

public @NonNull Map<@NonNull SecurityPatchState.Severity, @NonNull Set<@NonNull String>> getPatchedCves(
    @SecurityPatchState.Component @NonNull String component,
    @NonNull SecurityPatchState.SecurityPatchLevel spl
)

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 @NonNull String component`	The component for which security fixes are listed.
`@NonNull SecurityPatchState.SecurityPatchLevel spl`	The security patch level for which fixes are retrieved.

Returns

Returns
`@NonNull Map<@NonNull SecurityPatchState.Severity, @NonNull Set<@NonNull 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.

@NonNull Map<@NonNull SecurityPatchState.Severity, @NonNull Set<@NonNull 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

public @NonNull List<@NonNull SecurityPatchState.SecurityPatchLevel> getPublishedSecurityPatchLevel(
    @SecurityPatchState.Component @NonNull String component
)

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

For System and System Modules (Mainline), this method employs a "Global Max" strategy: it returns the latest date found in the entire Vulnerability Report, regardless of whether that specific date included updates for the requested component. This ensures that the Published SPL aligns with the overall Android Security Bulletin date (e.g. 2026-01-05), preventing stale reporting during months where the Bulletin may only list patches for other components (e.g. Vendor-only updates) or is advisory-only under Risk Based Update System (RBUS) policies.

For Kernel and Vendor components, it returns the latest patch level specifically associated with those components in the report.

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

Returns

Returns
`@NonNull List<@NonNull SecurityPatchState.SecurityPatchLevel>`	A list of `SecurityPatchLevel` representing the published patch levels. The list contains a single element for most components. For KERNEL, 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.

@NonNull List<@NonNull SecurityPatchState.SecurityPatchLevel>

A list of SecurityPatchLevel representing the published patch levels. The list contains a single element for most components. For KERNEL, 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.

getVulnerabilityReportUrl

Added in 1.0.0

@RequiresApi(value = 26)
public static final @NonNull Uri getVulnerabilityReportUrl(@NonNull Uri serverUrl)

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

Parameters
`@NonNull Uri serverUrl`	The base URL of the server where vulnerability reports are stored.

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

isDeviceFullyUpdated

Added in 1.0.0

public final boolean isDeviceFullyUpdated()

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
public final void loadVulnerabilityReport(@NonNull String jsonString)

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
`@NonNull String jsonString`	The JSON string containing the vulnerability data.

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

queryAllAvailableUpdates

public final @NonNull List<@NonNull UpdateCheckResult> queryAllAvailableUpdates(long timeoutMillis)

Queries for available security updates from all trusted update providers.

This method performs a comprehensive check by:

Discovering all trusted services on the device that implement the UpdateInfoService protocol (e.g., System Updater, Google Play Store).
Querying each service concurrently to retrieve its status.
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 suspend while it performs a network fetch.

Parameters
`long timeoutMillis`	The maximum time to wait for each provider to respond, in milliseconds. Defaults to `UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS`.

Returns
`@NonNull List<@NonNull 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.

queryAllAvailableUpdatesAsync

Added in 1.1.0-beta02

public final @NonNull ListenableFuture<@NonNull List<@NonNull UpdateCheckResult>> queryAllAvailableUpdatesAsync(long timeoutMillis)

Queries for available security updates from all trusted update providers.

This is the Java-friendly variant of queryAllAvailableUpdates returning a ListenableFuture.

Parameters
`long timeoutMillis`	The maximum time to wait for each provider to respond, in milliseconds.

Returns
`@NonNull ListenableFuture<@NonNull List<@NonNull UpdateCheckResult>>`	A `ListenableFuture` containing a list of `UpdateCheckResult` objects.

SecurityPatchState

Summary

Nested types

Constants

Public fields

Public constructors

Public methods

Constants

COMPONENT_KERNEL

COMPONENT_SYSTEM

COMPONENT_SYSTEM_MODULES

DEFAULT_VULNERABILITY_REPORTS_URL

UPDATE_INFO_SERVICE_BINDING_TIMEOUT_MS

Public fields

DEFAULT_SYSTEM_MODULES

Public constructors

SecurityPatchState

Public methods

areCvesPatched

fetchAvailableSecurityPatchLevel

fetchAvailableSecurityPatchLevelAsync

getComponentSecurityPatchLevel

getDeviceSecurityPatchLevel

getPatchedCves

getPublishedSecurityPatchLevel

getVulnerabilityReportUrl

isDeviceFullyUpdated

loadVulnerabilityReport

queryAllAvailableUpdates

queryAllAvailableUpdatesAsync