SecurityPatchState

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.

Summary

Nested types

Implementation of SecurityPatchLevel for a date-based patch level.

Implementation of SecurityPatchLevel for a simple string patch level.

Abstract base class representing a security patch level.

Severity of reported security issues.

Implementation of SecurityPatchLevel for a versioned patch level.

Constants
const String

Kernel component providing kernel version as VersionedSpl.
const String

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

System modules component providing DateBasedSpl of system modules patch level.
const String

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

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

Public companion properties
List<String>

Public constructors
SecurityPatchState(
    context: Context,
    systemModules: List<String>,
    customSecurityStateManager: SecurityStateManager?
)

Creates an instance of SecurityPatchState.

Public functions
Boolean

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

Retrieves the available security patch level for a specified component for current device.
open SecurityPatchState.SecurityPatchLevel
getComponentSecurityPatchLevel(
    component: String,
    securityPatchLevel: String
)

Retrieves the specific security patch level for a given component based on a security patch level string.
open SecurityPatchState.SecurityPatchLevel

Retrieves the current security patch level for a specified component.
open 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.
open List<SecurityPatchState.SecurityPatchLevel>

Retrieves the published security patch level for a specified component.
Uri
@RequiresApi(value = 26)
getVulnerabilityReportUrl(serverUrl: Uri)

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

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

Fetches available updates from specified update providers.
Unit

Parses a JSON string to extract vulnerability report data.

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.

COMPONENT_VENDOR

const val COMPONENT_VENDOR: String

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

DEFAULT_VULNERABILITY_REPORTS_URL

const val DEFAULT_VULNERABILITY_REPORTS_URL: String

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

Public companion properties

DEFAULT_SYSTEM_MODULES

val DEFAULT_SYSTEM_MODULES: List<String>

Public constructors

SecurityPatchState

Added in 1.0.0-alpha04
SecurityPatchState(
    context: Context,
    systemModules: List<String> = listOf(),
    customSecurityStateManager: SecurityStateManager? = null
)

Creates an instance of SecurityPatchState.

Parameters
context: Context

Application context used for accessing shared preferences, resources, and other context-dependent features.
systemModules: List<String> = listOf()

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.
customSecurityStateManager: SecurityStateManager? = null

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

Public functions

areCvesPatched

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

getAvailableSecurityPatchLevel

open fun getAvailableSecurityPatchLevel(
    component: String,
    providers: List<Uri> = listOf()
): SecurityPatchState.SecurityPatchLevel

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
component: String

The component for which the available patch level is requested.
providers: List<Uri> = listOf()

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
SecurityPatchState.SecurityPatchLevel

A SecurityPatchLevel representing the available patch level for updates.

getComponentSecurityPatchLevel

Added in 1.0.0-alpha04
open fun getComponentSecurityPatchLevel(
    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
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
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
open fun getDeviceSecurityPatchLevel(component: String): SecurityPatchState.SecurityPatchLevel

Retrieves the current security patch level for a specified component.

Parameters
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
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
open fun getPatchedCves(
    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
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-alpha04
open fun getPublishedSecurityPatchLevel(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
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.

getVulnerabilityReportUrl

Added in 1.0.0-alpha04
@RequiresApi(value = 26)
fun getVulnerabilityReportUrl(serverUrl: Uri): Uri

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

Parameters
serverUrl: Uri

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.
Throws
kotlin.IllegalArgumentException

if the Android SDK version is unsupported.

isDeviceFullyUpdated

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

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

listAvailableUpdates

open fun listAvailableUpdates(providers: List<Uri>? = null): List<UpdateInfo>

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
providers: List<Uri>? = null

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

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

loadVulnerabilityReport

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

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
jsonString: String

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

if the JSON input is malformed or contains invalid data.