Documentation

Add the plugin

Apply the plugin and add the library to your application module:

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("pro.paphitis.appguard") version "0.1.0"
}

dependencies {
    implementation("pro.paphitis.appguard:android-app-guard:0.1.0")
}

The plugin and the AAR carry the same version, and must stay in step. The plugin writes check names into BuildConfig that the library parses back, and the library rejects a name it does not recognise rather than silently skipping the check.

Add your licence key

A licence key names one base application ID, the environment suffixes it covers, and an expiry. The plugin verifies it during configuration — offline, with no call home — and fails the build if the variant's application ID is not covered. Request one here.

Per application ID, VAT included. There is no grace period — the plugin verifies offline, so an expired licence fails the build the moment it lapses. Renew before the expiry date in your key.

The plugin looks in four places, first match wins:

Which environments a licence covers:

Licensed base ID : com.example.app
Suffixes         : (production), .qa, .uat, .test

Builds that pass : com.example.app
                   com.example.app.qa
                   com.example.app.uat
                   com.example.app.test

Builds that fail : com.example.app.internal   ← not on the licence

The check runs per variant against the resolved application ID, so product flavours and applicationIdSuffix are both accounted for. Request every environment you ship to — adding one later means a new key.

Choose a policy per check

Each check is independently ALLOWED, WARNING or ENFORCED, set per build type. Both blocks are optional; anything you leave out takes the default in the reference table below.

appGuard {
    licenseKey = "AG1.…"
    allowedSigningCertificates = listOf("A1:B2:…")

    debug {
        // Normal on a development machine — running these would mean a
        // finding on every single launch.
        signature = SecurityPolicy.ALLOWED
        installer = SecurityPolicy.ALLOWED
        debugger  = SecurityPolicy.ALLOWED
        emulator  = SecurityPolicy.ALLOWED

        // Something genuinely wrong with the device, not the build.
        root      = SecurityPolicy.WARNING
        hooking   = SecurityPolicy.WARNING
    }

    release {
        signature = SecurityPolicy.ENFORCED
        debugger  = SecurityPolicy.ENFORCED
        emulator  = SecurityPolicy.ENFORCED
        root      = SecurityPolicy.ENFORCED
        hooking   = SecurityPolicy.ENFORCED
        installer = SecurityPolicy.ALLOWED   // opt in when you ship store-only
    }
}

Build types other than debug use the release block. A build type nobody configured is more likely to ship than to be a development build, and guessing wrong in that direction is the expensive mistake.

Wire up your Application

Extend SecureApplication and hand it the values the plugin put in BuildConfig. That is the whole integration — the base class runs the checks on startup and on a randomised foreground schedule.

class MyApp : SecureApplication() {

    override val securityPolicies =
        SecurityPolicies.parse(BuildConfig.APPGUARD_POLICIES)

    override val allowedSigningCertificates =
        BuildConfig.ALLOWED_SIGNING_CERTIFICATES
            .split(",")
            .filter { it.isNotBlank() }
}

Register it in your manifest:

<application android:name=".MyApp" … >

Not using the plugin? SecurityPolicies has a normal constructor — SecurityPolicies(signature = SecurityPolicy.ENFORCED, …) — and defaults to everything enforced except the installer check, so forgetting to configure it fails closed.

Handle security events

Every detection is published to securityEvents, keyed by check. Events are emitted for WARNING and ENFORCED — an enforced finding is published before the exception is thrown, so you see the reason rather than only the crash.

lifecycleScope.launch {
    (application as SecureApplication).securityEvents
        .filter { it.check == SecurityCheck.ROOT }
        .collect { event ->
            Log.w("AppGuard", "${event.policy}: ${event.message}")
            if (event.isFatal) disableSensitiveFeatures()
        }
}

isDeviceSecure() gives the aggregate — false once an ENFORCED check has failed. Warnings do not change it.