Documentation

Requirements

The native detection layer ships prebuilt inside the AAR for all four ABIs, so you do not need the NDK or CMake. Do not exclude libagcore.so through packaging options: on a supported ABI, a missing native layer is treated as tampering and the app exits at startup.

Set it up with an AI agent

Using Claude Code, Cursor, Copilot or another coding agent? AppGuard publishes a setup skill that takes the agent through everything on this page: dependencies, licence key, policy block, SecureApplication, activities and manifest. For anything only you can supply or decide, it asks you instead of guessing.

Claude Code: install the skill into your project, then ask Claude to “set up AppGuard”:

mkdir -p .claude/skills/appguard-setup && cd .claude/skills/appguard-setup && \
curl -fsSL --remote-name-all \
  https://appguard.paphitis.pro/skills/appguard-setup/SKILL.md \
  https://appguard.paphitis.pro/skills/appguard-setup/reference.md \
  https://appguard.paphitis.pro/skills/appguard-setup/troubleshooting.md

To make it available in every project, install it into ~/.claude/skills/ instead.

Any other agent: if it can read web pages, paste this prompt:

Set up the AppGuard Android SDK in this project. Follow
https://appguard.paphitis.pro/skills/appguard-setup/SKILL.md exactly, including the
reference.md and troubleshooting.md next to it, and ask me whenever it says to ask.

It will ask you for:

• your licence key and where to keep it;
• your release certificate's SHA-256 fingerprint, plus Google's if you use Play App Signing;
• whether to keep the QUERY_ALL_PACKAGES permission;
• which activities get screen protection;
• how you distribute the app.

It finishes with a report: what it changed, what's still yours to do before a release, and which defaults it chose for you to confirm.

Signed policy config (optional)

Everything on this page so far reaches the app through BuildConfig — plain constants in the compiled DEX, readable and editable with jadx or apktool in about a minute. Signed policy config doesn't hide that value — nothing shipped to a device is truly hidden from a determined attacker — it makes editing it pointless instead: the value is cryptographically signed, and the library verifies the signature before trusting it, so a patched policy is rejected — and the app terminated — rather than silently used.

What you get signed is the same information already in your appGuard { } block — the six checks, your certificate whitelist, the two window protections, and the runtime re-check interval — for one build type at a time, since debug and release routinely differ. Three steps, all required — the first two alone do nothing.

1. Save the file next to appguard.license, named for the build type it covers — same rule as the licence file: the module directory (the one with id("pro.paphitis.appguard") applied) or the root project directory, either works:

my-app/
  appguard.license
  appguard-config-debug.sig
  appguard-config-release.sig

Both files are safe to commit. Signed config is not secret — it can be read, but not forged or edited, the same reasoning that already applies to the licence key.

2. Add the override in SecureApplication, next to the overrides you already have — the plugin writes the file's contents into BuildConfig automatically, but nothing reads that field until you add this line yourself:

class MyApp : SecureApplication() {
    override val securityPolicies = SecurityPolicies.parse(BuildConfig.APPGUARD_POLICIES)
    override val signedPolicyConfig = BuildConfig.APPGUARD_SIGNED_POLICY_CONFIG
    // …
}

3. Rebuild — everything else is automatic from here. At every build, the plugin recomputes the same information from your current appGuard { } block and compares it, byte for byte, against what was signed. If they no longer match — you changed a policy and forgot to have it re-signed — a release build fails before anything compiles, with a message telling you which file is now stale. A debug build only warns and carries on: it leaves the signed config out, so the app runs your debug { } values as written while you iterate. Get the file re-signed before you build a release.

At runtime, the library verifies the signature (Ed25519, via Bouncy Castle) before trusting anything in it. A config that verifies takes precedence over the plain BuildConfig values automatically — nothing else to change. A config that was provisioned but fails to verify is treated as an active tampering signal: the app terminates on startup, unconditionally, regardless of what any individual check's policy says. A project that never requests a signed config, or never adds the signedPolicyConfig override above, sees no difference at all.

Screen protection

Extending SecureActivity is optional and separate from the checks. It applies FLAG_SECURE (blocking screenshots, screen recording and the recents thumbnail), filters touches that arrive while another window is overlaid — the mechanism behind tapjacking — and re-validates integrity at each lifecycle entry point.

class MainActivity : SecureActivity() {

    override fun onSecureCreate(savedInstanceState: Bundle?) {
        setContentView(R.layout.activity_main)
    }

    // Called when validation fails. Terminates the task by default.
    override fun onDeviceNotSecure() {
        showBlockedScreen()
    }
}

Both protections are on by default and are configured per build type in appGuard { }, alongside the check policy:

appGuard {
    debug {
        // FLAG_SECURE makes it impossible to take a screenshot for a bug
        // report, so it is usually off while developing.
        secureWindow = false
    }

    release {
        secureWindow   = true
        touchFiltering = true
    }
}

Your Application passes them on:

override val screenProtection = ScreenProtection(
    secureWindow   = BuildConfig.APPGUARD_SECURE_WINDOW,
    touchFiltering = BuildConfig.APPGUARD_TOUCH_FILTERING,
)

Note onSecureCreate rather than onCreate — the base class needs to apply window flags before your content view is inflated.

Play Integrity (optional)

Every check above runs entirely on-device with no network call — that is what lets a build work offline and keeps a portal outage from ever blocking a release. Google Play Integrity is deliberately kept outside that system: it is a different trust root — a hardware-attested verdict signed by Google and verified on your own backend, not another local check — offered as an addition, not a replacement.

Add the Play Integrity SDK yourself; AppGuard depends on it only as compileOnly, so nothing about it is pulled into your APK unless you ask for it:

// app/build.gradle.kts
dependencies {
    implementation("com.google.android.play:integrity:1.4.0")
}

val result = PlayIntegrityCheck.requestToken(
    context = this,
    cloudProjectNumber = 123456789L,   // Play Console → App integrity → Play Integrity API
    nonce = nonceFromYourBackend,      // fresh, unpredictable, base64url — never generated on-device
)

when (result) {
    is PlayIntegrityCheck.IntegrityResult.Token ->
        sendToYourBackendForVerification(result.token)
    is PlayIntegrityCheck.IntegrityResult.Failed ->
        logger.warn("Play Integrity request failed", result.cause)
}

Both trust roots are worth having together, not one instead of the other: the checks above inspect local, on-device state, which a sufficiently privileged attacker can eventually lie about; a Play Integrity verdict is attested by hardware and verified server-side, which defeating requires forging that attestation chain rather than hiding local artifacts from a scoped app.

Whitelist your signing certificate

The signature check compares the running APK's signing certificate against allowedSigningCertificates. Supply SHA-256 fingerprints as colon-hex or base64; both are accepted.

./gradlew :app:signingReport

The check requires every signer to be whitelisted, not just one, so an attacker cannot append their certificate to the signing block while keeping yours.

R8 and ProGuard

Nothing to add. The AAR ships its own consumer rules, which keep the JNI boundary intact — the native layer resolves its bridge class by name at load time, so that one class must survive shrinking.

Everything else is deliberately left obfuscatable. Every unobfuscated symbol in a security library is a signpost telling an attacker which method to hook, so do not add broad -keep rules for AppGuard classes.

Two options worth adding to your own app's proguard-rules.pro, if you are not already setting them: -optimizationpasses 5 (more inlining, so there is no single method to hook to disable a check) and -renamesourcefileattribute "" (keeps a stack trace from naming your package layout). Both are global R8 options, so the AAR cannot set them on your behalf the way it does for the JNI-boundary -keep rule — they have to be yours.

Policy reference

installer is off even in release because it produces false positives for sideloaded enterprise builds and during QA. Turn it on once you ship exclusively through a store.

Changed in 0.1.8: hooking controls the Kotlin side only. The native watchdog that detects Frida runs from the moment the library is loaded and can no longer be switched off — not by policy, and not on a debug build. If you attach Frida to a debug build, the process is terminated regardless of hooking = SecurityPolicy.WARNING. Previously a debug build could disable it. Use a build variant without AppGuard applied if you need to instrument your own app.

Window protection

Set in the same debug { } and release { } blocks, but booleans rather than policies — a window flag is either applied or it is not.

Both stay on by default in every build type, unlike the checks above. Most projects set debug { secureWindow = false } so screenshots work while developing.

Troubleshooting

“variant … is not licensed”

The variant's application ID is not covered. The message lists what the licence does cover; compare it against the applicationId and any applicationIdSuffix on that build type. If the suffix is new, you need a reissued licence.

“AppGuard requires a licence key”

Nothing supplied one. The message lists all four sources — the usual cause is a key set in ~/.gradle/gradle.properties on a developer machine but not in CI.

“The AppGuard licence expired on …”

Licences are time-limited and verified offline, so there is no grace period and no way to extend one without a new key. Quote the licence id from the message when you get in touch.

Signature check fails on a store build only

Almost always Play App Signing: the APK users receive is signed by Google's distribution certificate, not your upload certificate. Add both.

Findings on every debug launch

Expected if the debug policy is stricter than the defaults. A debug build is signed with the debug keystore, is sideloaded, is often on an emulator and frequently has a debugger attached — all four are findings unless set to ALLOWED.

The app dies at startup in release with no useful stack trace

An ENFORCED finding throws DeviceIntegrityException and then kills the process shortly afterwards, so an uncaught-exception handler cannot swallow it and keep a compromised app running. Collect securityEvents to see the reason — it is published before the throw.

Ready to start?