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

Types of components whose security state can be accessed.

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

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: SecurityPatchState.Component,
    providers: List<Uri>?
)

Retrieves the available security patch level for a specified component for current device.
open SecurityPatchState.SecurityPatchLevel

Retrieves the current security patch level for a specified component.
open Map<SecurityPatchState.Severity, List<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.
open SecurityPatchState.SecurityPatchLevel
getSecurityPatchLevelString(
    component: SecurityPatchState.Component,
    securityPatchLevel: String
)

Retrieves the specific security patch level for a given component based on a security patch level string.
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

DEFAULT_VULNERABILITY_REPORTS_URL

const val DEFAULT_VULNERABILITY_REPORTS_URL: String

Public companion properties

DEFAULT_SYSTEM_MODULES

val DEFAULT_SYSTEM_MODULES: List<String>

Public constructors

SecurityPatchState

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

Creates an instance of SecurityPatchState.

Parameters
context: Context

Android 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-alpha01
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: SecurityPatchState.Component,
    providers: List<Uri>? = null
): 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: SecurityPatchState.Component

The component for which the available patch level is requested.
providers: List<Uri>? = null

Optional list of URIs representing update providers; if null, defaults are used. Check documentation of OTA update clients for content provider URIs.
Returns
SecurityPatchState.SecurityPatchLevel

A SecurityPatchLevel representing the available patch level for updates.

getDeviceSecurityPatchLevel

Added in 1.0.0-alpha01
open fun getDeviceSecurityPatchLevel(component: SecurityPatchState.Component): SecurityPatchState.SecurityPatchLevel

Retrieves the current security patch level for a specified component.

Parameters
component: SecurityPatchState.Component

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.

getPatchedCves

Added in 1.0.0-alpha01
open fun getPatchedCves(
    component: SecurityPatchState.Component,
    spl: SecurityPatchState.SecurityPatchLevel
): Map<SecurityPatchState.Severity, List<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: SecurityPatchState.Component

The component for which security fixes are listed.
spl: SecurityPatchState.SecurityPatchLevel

The security patch level for which fixes are retrieved.
Returns
Map<SecurityPatchState.Severity, List<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-alpha01
open fun getPublishedSecurityPatchLevel(component: SecurityPatchState.Component): 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: SecurityPatchState.Component

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.

getSecurityPatchLevelString

Added in 1.0.0-alpha01
open fun getSecurityPatchLevelString(
    component: SecurityPatchState.Component,
    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: SecurityPatchState.Component

The Component enum 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.

getVulnerabilityReportUrl

Added in 1.0.0-alpha01
fun getVulnerabilityReportUrl(serverUrl: String): Uri

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

Parameters
serverUrl: String

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-alpha01
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-alpha01
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 parseVulnerabilityReport()

  • 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.