哪些直接用，哪些需要额外接入

插件与 SDK 分开发包，目前工程仅配置本地 Maven 发布。以下插件依赖仅在需要自动生成签名／内容基准时添加，普通检测无需接入。

仅影响签名和内容两项。插件 ID 为 com.remax.riskcontrol.content-signature，配置块为 riskContentSignature；SDK 与插件需配套更新，并重新构建应用。在 settings.gradle.kts 文件开头的现有 pluginManagement.repositories 加入插件仓库：

pluginManagement {
    repositories {
        maven { url = uri("/实际路径/risk-control-maven") }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

在宿主 App 模块的 app/build.gradle.kts 中：

plugins {
    // 保留原有 Android / Kotlin 插件。
    id("com.remax.riskcontrol.content-signature") version "0.1.0"
}

riskContentSignature {
    contentEnabled.set(true) // 只开启内容基准，签名默认 false。
}

两个开关默认关闭，可独立开启

上方示例显式开启内容校验；只应用插件、不写配置块时，两项都关闭。Demo 为验证功能显式开启两项，不代表默认值。

表中自动扫描行为以业务未传显式基准为前提。插件只在构建机运行，不会在 App 内常驻运行；其他本地检测仍按所选项目执行。

扫描回调与直接调用的区别

• selected 是候选集合。关闭且没有显式基准的签名 / 内容项目不触发 onResult，也不出现在 onComplete 的结果 Map 中；不要固定等待 12 个结果。
• 所选项目全被跳过时，仍在工作线程调用一次 onComplete(emptyMap())。
• 通过 ScanConfig(signature = ..., content = ...) 提供显式基准，即使插件未开启也会执行对应检测。useGeneratedBaselines = false 时，这两项仅使用显式基准。
• 已开启但基准缺失、损坏或不可读时仍执行并返回 UNKNOWN，不会静默跳过。
• 直接调用 checkSignature / checkApkContent 仍返回结果：关闭且未传显式基准时返回 UNKNOWN/no_baseline，不打开基准文件。主动调用 loadGeneratedBaselines 仍会读取文件。

如需签名基准，另开 signatureEnabled，选择一种来源：

riskContentSignature {
    contentEnabled.set(true)
    signatureEnabled.set(true)
    certificateFiles.setFrom(rootProject.file("certificates/play-app-signing.der"))
}

证书在 Play Console 的 Play 应用签名页面下载“应用签名密钥证书”，不要选上传证书；放到 CI 可读的项目路径。下载指引。自行签名分发改用 signingMode.set("buildSigning")，不要配置外部证书。

CI 按当前变体的开关选择输出目录

至少开启一项：使用插件导出的最终产物。

app/build/outputs/risk-control/<变体名>/apk/*.apk
app/build/outputs/risk-control/<变体名>/bundle/*.aab

两项都关闭：使用 AGP 原生输出目录。APK 的子目录取决于 flavor / buildType 配置。

app/build/outputs/apk/
app/build/outputs/bundle/<变体名>/*.aab

// 无 flavor 的 debug APK 示例：
app/build/outputs/apk/debug/*.apk
// dev flavor 的 release APK 示例：
app/build/outputs/apk/dev/release/*.apk

从开启切换为关闭无需 clean，新原生产物不会携带旧生成基准。双关闭后不会刷新旧的 outputs/risk-control 目录，CI 不要继续从旧导出目录取包。

内容开启时复用现有签名配置重新签署；.der 不替代上传密钥。只开签名时不执行 DEX 转换或额外重签。需要加固时先查看下方兼容说明。

旧插件 ID com.remax.riskcontrol.baseline 和配置块 riskBaseline 已被新名称替换，没有保留旧 ID 别名。插件实现坐标为 com.remax.riskcontrol:risk-control-content-signature-plugin:0.1.0。

riskContentSignature {
    onVariants {
        when (name) {
            "devDebug", "devRelease" -> {
                contentEnabled.set(true)
                signatureEnabled.set(true)
                signingMode.set("buildSigning")
                certificateFiles.setFrom(emptyList<Any>())
            }
            "prodRelease" -> {
                contentEnabled.set(true)
                signatureEnabled.set(true)
                signingMode.set("playAppSigning")
                certificateFiles.setFrom(rootProject.file("certificates/play-app-signing.der"))
            }
        }
    }
}

独立于内容与签名检测插件和本地扫描。Google 依赖已随 SDK 自动传递；业务提供项目编号、完成 Google 配置，并让后端解密验证凭证与请求绑定。

import com.remax.riskcontrol.sdk.integrity.PlayIntegrityClient

val client = PlayIntegrityClient(applicationContext, cloudProjectNumber)
client.requestPlayIntegrityToken()
    .addOnSuccessListener { result ->
        // 将 token 与 requestContext 等请求绑定信息交给业务后端验证。
        // 取得 token 不等于校验通过，SDK 不会自动请求业务后端。
    }
    .addOnFailureListener { error -> /* 本次未取得凭证 */ }

复用 client，可在主线程发起，默认 listener 在主线程回调。requestHash 由 SDK 自动生成，无需 Firebase JSON；不额外申请用户权限。

适用于 SDK 0.1.7；以下均为公开 API。常规检测无需额外初始化、危险权限或插件。签名 / 内容仅在需要基准时配置；Integrity 独立异步取凭证。使用 import com.remax.riskcontrol.sdk.*，Integrity 类型位于子包 .integrity。

DetectionSession(context: Context, rules: DetectionRules = DetectionRules())
RiskScanner(context: Context)

// RiskScanner 实例方法
fun scan(
    config: ScanConfig = ScanConfig(),
    selected: Set<CheckId> = CheckId.entries.toSet(),
    onResult: (CheckId, CheckResult) -> Unit,
    onComplete: (Map<CheckId, CheckResult>) -> Unit = {}
): Unit
fun close(): Unit

// 顶层函数
fun executeCheck(id: CheckId, session: DetectionSession,
    config: ScanConfig = ScanConfig()): CheckResult
fun defaultToolTargets(): List<ToolTarget>

import android.content.Context
import com.remax.riskcontrol.sdk.*

// 在后台线程执行；每轮新建 session。
fun customRootCheck(context: Context, extraSuPath: String): CheckResult {
    val defaults = DetectionRules()
    val config = ScanConfig(rules = defaults.copy(
        rootPaths = defaults.rootPaths + extraSuPath
    ))
    val session = DetectionSession(context, config.rules)
    return executeCheck(CheckId.ROOT, session, config)
}

SignatureBaseline(
    packageName: String,
    allowedSignerSets: List<Set<String>>,
    allowedRotationAncestors: Set<String> = emptySet()
)
ContentBaseline(
    packageName: String, versionCode: Long,
    files: List<ContentFile>, dexModules: List<DexModule> = emptyList()
)
ContentFile(apk: String = "base", entry: String, sha256: String)
DexModule(apk: String, files: Map<String, String>,
    required: Boolean = apk == "base", matchByDigest: Boolean = false)

import android.content.Context
import com.remax.riskcontrol.sdk.*

// 所有 expected / trusted 值由可信构建系统提供，不从当前安装包反向生成。
// 示例假设应用只有 base，且其完整 DEX 清单只有 classes.dex。
fun checkWithTrustedBaselines(
    context: Context, expectedPackage: String, expectedVersionCode: Long,
    trustedCertificateSha256: String, trustedDexSha256: String
): Pair<CheckResult, CheckResult> {
    val signature = SignatureBaseline(
        packageName = expectedPackage,
        allowedSignerSets = listOf(setOf(trustedCertificateSha256))
    )
    val content = ContentBaseline(
        packageName = expectedPackage,
        versionCode = expectedVersionCode,
        files = emptyList(),
        dexModules = listOf(DexModule(
            apk = "base", files = mapOf("classes.dex" to trustedDexSha256)
        ))
    )
    val session = DetectionSession(context)
    return checkSignature(session, signature) to checkApkContent(session, content)
}

PlayIntegrityClient(context: Context, cloudProjectNumber: Long)
fun requestPlayIntegrityToken(): Task<IntegrityTokenResult>

risk-control/environment/v1
{packageName}
{requestId}
{createdAtMillis}

import com.remax.riskcontrol.sdk.integrity.*
import java.util.concurrent.TimeoutException

// client 由宿主持有并复用；onToken 交给业务自己的后端调用层。
fun obtainIntegrityToken(
    client: PlayIntegrityClient,
    onToken: (IntegrityTokenResult) -> Unit,
    onFailure: (String) -> Unit
) {
    client.requestPlayIntegrityToken()
        .addOnSuccessListener { result ->
            // 同时传 token 与 requestContext，不只传 cloudProjectNumber。
            onToken(result)
        }
        .addOnFailureListener { error ->
            val description = when (error) {
                is IntegrityTokenException ->
                    "${error.stage}: ${error.reason}, code=${error.googleErrorCode}"
                is TimeoutException -> "本次取凭证超时"
                else -> "取凭证失败：${error.message}"
            }
            onFailure(description)
        }
}

// app/build.gradle.kts；先按上方说明应用插件。
riskContentSignature {
    // 默认保持关闭；仅为指定变体开启。
    onVariants { variant ->
        if (variant.name == "prodRelease") {
            variant.contentEnabled.set(true)
            variant.assetIncludes.set(listOf("config/**", "rules/*.json"))
            variant.assetExcludes.set(listOf("config/debug/**"))
            variant.signatureEnabled.set(true)
            variant.signingMode.set("playAppSigning")
            variant.certificateFiles.setFrom(
                rootProject.file("certificates/play-app-signing.der")
            )
        }
    }
}

所有本地函数返回 CheckResult；子项在 findings，原因在 finding.reason，事实在 facts。CONSISTENT 是与基准一致，INCONSISTENT 是不一致。UNKNOWN 不能当作通过；特征检出也不直接认定作弊。

每个检测函数返回一个 CheckResult，独立子项放在 result.findings: List<Finding> 中。子项不是另外一个需要执行的函数；先执行所属检测，再读取结果即可。

检测参数与结果查询参数不是一回事

正常检测无需业务填写 su 路径、传感器类型或 DEX 文件名。su 路径、传感器类型来自 SDK 默认规则；DEX 文件名来自插件生成或业务手动提供的可信基准。没有内容基准时返回未知，不会拿当前安装包自行生成可信基准。动态 ID 方法的参数只用于精确取结果，不能增加检查对象。

import com.remax.riskcontrol.sdk.*

// 后台线程调用。使用 SDK 默认规则，不传路径、传感器类型或 DEX 文件名。
val session = DetectionSession(applicationContext)
val root = checkRoot(session)
val suItems = root.findingsByPrefix(FindingIds.SU_ARTIFACT_PREFIX)

val hardware = checkDeviceCapabilities(session)
val sensors = hardware.findingsByPrefix(FindingIds.SENSOR_MISSING_PREFIX)

// 内容依赖可信基准：可选插件生成，或业务手动传入。
val content = checkApkContent(session)
val dexItems = content.findingsByPrefix(FindingIds.DEX_INVENTORY_PREFIX)
// 无基准时 content.status=UNKNOWN，dexItems 可能为空；不能当作校验通过。

统一入口：FindingIds + 结果查询方法

导入 com.remax.riskcontrol.sdk.* 后即可使用。固定 ID 提供常量，动态 ID 提供生成方法和前缀常量；SDK 产生结果时也使用同一套定义。底层 Finding.id 仍为字符串，方便 JSON / 日志输出，其值和检测行为不变。

finding 只取首条；没有结果返回 null，列表查询没有结果返回空列表，均不伪造 NOT_DETECTED。需要处理重复内容校验结果时用 findingsById。此封装只针对子项 ID；包名、路径等仍是业务入参，facts / evidence 的键仍按文档读取。

固定 ID：以“无卡且 Wi-Fi”为例

import com.remax.riskcontrol.sdk.*

// 在业务后台线程执行；若使用 scanner，直接在回调中读取 result。
val result = checkSimNetwork(DetectionSession(applicationContext))
val item = result.finding(FindingIds.NO_SIM_AND_WIFI)

// 缺少子项时按未知处理，不能当作 NOT_DETECTED。
val status = item?.status ?: Status.UNKNOWN
val reason = item?.reason ?: "finding_unavailable"

when (status) {
    Status.DETECTED -> { /* 已确认无卡，且当前默认网络是 Wi-Fi */ }
    Status.NOT_DETECTED -> { /* 必要信息已知，组合条件不成立 */ }
    Status.NOT_APPLICABLE -> { /* 设备无电话能力 */ }
    Status.UNKNOWN -> { /* 信息不足，查看 reason */ }
    else -> { /* 非该子项的预期状态，按未知处理 */ }
}
// result.status 是 PRESENT / ABSENT / UNKNOWN / NOT_APPLICABLE，
// 不要用它代替 no_sim_and_wifi 的状态。

例如：result.status=ABSENT，no_sim_and_wifi=UNKNOWN，表示已确认无卡，但网络信息不足。即便顶层有明确结论，也要看自己关心的子项，不能用顶层状态代替所有子项。

动态 ID：取全部相关子项

import com.remax.riskcontrol.sdk.*

// 在后台线程调用。rootPaths 可通过 DetectionRules 自定义。
val result = checkRoot(DetectionSession(applicationContext))
val suItems = result.findingsByPrefix(FindingIds.SU_ARTIFACT_PREFIX)
val suStatus = when {
    suItems.any { it.status == Status.DETECTED } -> Status.DETECTED
    suItems.isEmpty() || suItems.any { it.status != Status.NOT_DETECTED } -> Status.UNKNOWN
    else -> Status.NOT_DETECTED
}

// 固定包名可以精确读取；它是辅助子项，不决定 Root 顶层状态。
val manager = result.finding(FindingIds.managerInstalled("com.topjohnwu.magisk"))
val managerStatus = manager?.status ?: Status.UNKNOWN

表中 SDK 方法用于精确查询时才需要传具体参数；通常直接用对应 *_PREFIX 取整组即可。实际 ID 栏的 {path}、{type}、{className}、{index}、{packageName}、{apk}、{entry} 是 JSON / 日志占位说明，不要手动拼接。例如 sensor_missing:1、qemu_file:/dev/qemu_pipe、entry_mismatch:base:classes.dex。动态子项可能有多条；内容校验同一文件也可能出现在多个检查阶段，不要默认所有 ID 都唯一，重复 ID 用 findingsById，动态家族用 findingsByPrefix，并检查每条结果。

在并发扫描回调中直接读取

import com.remax.riskcontrol.sdk.*

// 由 Activity / ViewModel 持有，生命周期结束时 scanner.close()。
val scanner = RiskScanner(applicationContext)
scanner.scan(
    selected = setOf(CheckId.SIM_NETWORK, CheckId.SIGNATURE),
    onResult = { id, result ->
        when (id) {
            CheckId.SIM_NETWORK -> {
                val item = result.finding(FindingIds.NO_SIM_AND_WIFI)
                val status = item?.status ?: Status.UNKNOWN
                // 使用 status；更新 UI 时切回主线程。
            }
            CheckId.SIGNATURE -> {
                val item = result.finding(FindingIds.SIGNATURE_MISMATCH)
                when (item?.status ?: Status.UNKNOWN) {
                    Status.CONSISTENT -> { /* 签名符合基准；包名另看 package_name_mismatch */ }
                    Status.INCONSISTENT -> { /* 签名不符合基准 */ }
                    else -> { /* 无法判断；查看 item?.reason */ }
                }
            }
            else -> Unit
        }
    },
)

12 项检测的子项清单

“参与汇总”只说明是否影响该函数的顶层 status，不代表业务必须拦截。特征 DETECTED 也不自动等于作弊。子项因配置、执行分支或读取异常可能缺失，缺失不等于否定结果。

模拟器 · checkEmulator

设备能力 · checkDeviceCapabilities

Root · checkRoot

Hook · checkHook

调试器 · checkDebugger

无障碍 · checkAccessibility

工具安装 · checkInstalledTools

VPN / 代理 · checkVpnProxy

SIM / eSIM · checkSimNetwork

安装来源 · checkInstallSource

签名 · checkSignature

内容 · checkApkContent

仅在异常时出现的诊断子项

不要假设每次都有全部子项。使用 finding / findingsById / findingsByPrefix，缺失时保留未知；必要时遍历该结果的所有 UNKNOWN 子项排查。不要把 UNKNOWN、NOT_APPLICABLE 或空列表当作“正常”。线程中断等仍可能向调用方传播；SDK 无法运行时也无法保证返回结果。

排查原因与证据

// result 是任意检测的返回值；以下只读取结果，不会再次检测。
val diagnostics = result.findings
    .filter { it.status == Status.UNKNOWN }
    .map { "${it.id}: ${it.reason}" }

val changedFiles = result.findingsByPrefix(FindingIds.ENTRY_MISMATCH_PREFIX)
    .filter { it.status == Status.INCONSISTENT }
changedFiles.forEach { item ->
    val detail = item.evidence["reason"] // 如 entry_missing；也可能为空。
    val actualDigest = item.evidence["actualSha256"]
    // 按业务需要消费证据，不要根据 reason 是否为空判断一致性。
}

当前插件没有通用的加固后基准生成适配。加固不必然让两项检测同时失效。以下结果以 SDK 仍能正常运行、相关数据可读取为前提；SDK 不会自动区分“合法加固”与“恶意修改”。

CONSISTENT 仅表示本次可检查范围内未发现不一致，不等于全包安全。内容子项包括 entry_mismatch:...、dex_inventory:...；未知原因在 findings[].reason。生成基准加载错误可用后台调用 loadGeneratedBaselines(context) 查看。汇总优先级：INCONSISTENT > UNKNOWN > CONSISTENT。

加固项目如何接入

不能在用户手机上读取当前加固包，再把它自身的摘要当可信基准。仅把插件任务移动到加固任务之后也不保证兼容；需确认产物输入、基准写入、最终签名及 AAB 分包均匹配。即使完成适配，落盘的壳 / 加密文件校验也不等于运行时解密代码或内存校验。

// 后台线程直接调用：默认查 SDK 内置工具。
val tools = checkInstalledTools(DetectionSession(applicationContext))

// 自定义名单：自动追加到内置名单（先在宿主 Manifest 配好该包名的 queries）。
val config = ScanConfig(tools = listOf(ToolTarget("com.example.tool", visibilityDeclared = true)))
// 不传或传空列表都保留内置名单；相同包名只查一次。

内容校验开启后，默认覆盖 base assets 和最终 DEX，不覆盖所有编译资源、native library 或运行时内存。可用 assetIncludes / assetExcludes 缩小 assets 范围。当前 assets + DEX 最多 64 个文件，单文件 64 MiB、合计 128 MiB。插件启用时，多 APK 输出暂不支持；内容开启时，部分动态功能交付和特殊签名重签暂不支持，构建会明确报错。两项都关闭时不施加插件的多 APK 输出限制。

默认工具查询包名：com.topjohnwu.magisk、de.robv.android.xposed.installer、org.lsposed.manager、org.autojs.autojs、org.autojs.autojs6。这些具体包名是实现时补充的初始名单；原需求文档列举了相关工具名称，并未提供这份完整包名清单，也尚未全部覆盖原文提到的工具。自定义包名需宿主声明精确 queries，再传 ToolTarget(packageName, visibilityDeclared = true)；不可见且查不到返回未知。传入名单自动与内置名单合并，按包名去重；空列表仍查内置名单。同名包采用业务传入的 visibilityDeclared，便于宿主移除 queries 时显式设为 false。Root 默认管理工具名单与 tools 参数独立。