SecurityPatchState

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.

Summary

Nested types

Implementation of SecurityPatchLevel for a date-based patch level.

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.

Implementation of SecurityPatchLevel for a versioned patch level.

Constants
static final @NonNull String

Kernel component providing kernel version as VersionedSpl.
static final @NonNull String

System component providing ro.build.version.security_patch property value as DateBasedSpl.
static final @NonNull String

System modules component providing DateBasedSpl of system modules patch level.
static final @NonNull String

Vendor component providing ro.vendor.build.security_patch property value as DateBasedSpl.
static final @NonNull String

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

Public fields
static final @NonNull List<@NonNull String>

Public constructors
SecurityPatchState(
    @NonNull Context context,
    @NonNull List<@NonNull String> systemModules,
    SecurityStateManager customSecurityStateManager
)

Creates an instance of SecurityPatchState.

Public methods
final boolean

Verifies if all specified CVEs have been patched in the system.
@NonNull SecurityPatchState.SecurityPatchLevel
getAvailableSecurityPatchLevel(
    @NonNull String component,
    @NonNull List<@NonNull Uri> providers
)

Retrieves the available security patch level for a specified component for current device.
@NonNull SecurityPatchState.SecurityPatchLevel
getComponentSecurityPatchLevel(
    @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

Retrieves the current security patch level for a specified component.
@NonNull Map<@NonNull SecurityPatchState.Severity, @NonNull Set<@NonNull 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.
@NonNull List<@NonNull SecurityPatchState.SecurityPatchLevel>

Retrieves the published security patch level for a specified component.
final @NonNull Uri

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

Checks if all components of the device have their security patch levels up to date with the published security patch levels.
@NonNull List<@NonNull UpdateInfo>

Fetches available updates from specified update providers.
final void

Parses a JSON string to extract vulnerability report data.

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.

COMPONENT_VENDOR

public static final @NonNull String COMPONENT_VENDOR

Vendor component providing ro.vendor.build.security_patch property value as DateBasedSpl.

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.

Public fields

DEFAULT_SYSTEM_MODULES

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

Public constructors

SecurityPatchState

Added in 1.0.0-alpha04
public SecurityPatchState(
    @NonNull Context context,
    @NonNull List<@NonNull String> systemModules,
    SecurityStateManager customSecurityStateManager
)

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> systemModules

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.
SecurityStateManager customSecurityStateManager

An optional custom manager for obtaining security state information. If null, a default manager is instantiated.

Public methods

areCvesPatched

Added in 1.0.0-alpha04
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.

getAvailableSecurityPatchLevel

public @NonNull SecurityPatchState.SecurityPatchLevel getAvailableSecurityPatchLevel(
    @NonNull String component,
    @NonNull List<@NonNull Uri> providers
)

Retrieves the available security patch level for a specified component for current device. Available patch level comes from updates that were not downloaded or installed yet, but have been released by device manufacturer to the current device. If no updates are found, it returns the current device security patch level.

The information about updates is supplied by update clients through dedicated update information content providers. If no providers are specified, it defaults to predefined URIs, consisting of Google OTA and Play system components update clients.

Parameters
@NonNull String component

The component for which the available patch level is requested.
@NonNull List<@NonNull Uri> providers

Optional list of URIs representing update providers; if null, defaults are used. Contact authors of custom OTA update clients included on a tested device to obtain content provider URIs.
Returns
@NonNull SecurityPatchState.SecurityPatchLevel

A SecurityPatchLevel representing the available patch level for updates.

getComponentSecurityPatchLevel

Added in 1.0.0-alpha04
public @NonNull SecurityPatchState.SecurityPatchLevel getComponentSecurityPatchLevel(
    @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
@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
kotlin.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-alpha04
public @NonNull SecurityPatchState.SecurityPatchLevel getDeviceSecurityPatchLevel(@NonNull String component)

Retrieves the current security patch level for a specified component.

Parameters
@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
kotlin.IllegalStateException

if the patch level data is not available.
kotlin.IllegalArgumentException

if the component name is unrecognized.

getPatchedCves

Added in 1.0.0-alpha04
public @NonNull Map<@NonNull SecurityPatchState.Severity, @NonNull Set<@NonNull String>> getPatchedCves(
    @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
@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
@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-alpha04
public @NonNull List<@NonNull SecurityPatchState.SecurityPatchLevel> getPublishedSecurityPatchLevel(@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 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
@NonNull String component

The component for which the published patch level is requested.
Returns
@NonNull List<@NonNull 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.

getVulnerabilityReportUrl

Added in 1.0.0-alpha04
@RequiresApi(value = 26)
public 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.
Throws
kotlin.IllegalArgumentException

if the Android SDK version is unsupported.

isDeviceFullyUpdated

Added in 1.0.0-alpha04
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
kotlin.IllegalArgumentException

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

listAvailableUpdates

public @NonNull List<@NonNull UpdateInfo> listAvailableUpdates(List<@NonNull Uri> providers)

Fetches available updates from specified update providers. If no providers are specified, it defaults to predefined URIs. This method queries each provider URI and processes the response to gather update data relevant to the system's components.

Parameters
List<@NonNull Uri> providers

An optional list of Uri objects representing update providers. If null or empty, default providers are used.
Returns
@NonNull List<@NonNull UpdateInfo>

A list of UpdateInfo objects, each representing an available update.

loadVulnerabilityReport

Added in 1.0.0-alpha04
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.

The recommended pattern of usage:

  • create SecurityPatchState object

  • call getVulnerabilityReportUrl()

  • download JSON file containing vulnerability report data

  • call loadVulnerabilityReport()

  • call getPublishedSecurityPatchLevel() or other APIs

Parameters
@NonNull String jsonString

The JSON string containing the vulnerability data.
Throws
kotlin.IllegalArgumentException

if the JSON input is malformed or contains invalid data.