# AutoRepro Examples and Templates

This repository contains standalone examples and templates for creating Android Vulnerability Reward Program (VRP) submissions using the AutoRepro framework.

The goal of these projects is to help you write effective, automatically reproducible proofs-of-concept.

## Choosing a Starting Point

To get started, choose the project that best fits your proof-of-concept:

*   [`example/`](./example): A comprehensive project that demonstrates all major AutoRepro features working together, including multiple device-side apps and a native (NDK) test. This is a good resource to see how different parts can interact.

*   [`templates/`](./templates): A collection of minimal, use-case-specific projects. We recommend starting with one of these templates.

## The Two Goals of an AutoRepro Submission

An effective AutoRepro submission serves two primary purposes:

1.  **Clear Communication:** It must clearly communicate the vulnerability's severity and attributes to the engineers and reviewers who will analyze it. The test code, comments, and especially the final assertion message should act as a detailed, executable explanation of the bug. The logs generated by a failing test are a critical piece of this communication.

2.  **Automated Execution:** It must run reliably and non-interactively as part of an automated test suite. This means the test must handle its own setup and teardown, require no manual interaction (like button clicks), and produce consistent results on a device that meets the test's preconditions.

## Writing High-Impact PoCs: Proving the Vulnerability

A high-quality proof-of-concept (PoC) does more than just trigger a bug; it clearly demonstrates the security impact. To help us accurately assess your finding, your test should prove that a security boundary has been crossed.

A powerful pattern for this is a three-step process:

1.  **Setup:** Prepare the device and get it into a vulnerable state.
2.  **Prove the Boundary:** Before triggering the vulnerability, attempt to perform your target action and assert that it **fails**. This proves the security boundary is working correctly on a non-exploited system.
3.  **Trigger & Verify:** Trigger the vulnerability, then repeat the same action from Step 2 and assert that it now **succeeds**. This provides clear and undeniable proof that your exploit has crossed a security boundary.

This "fail-then-succeed" pattern is the most effective way to demonstrate the real impact of your vulnerability. When your verification step succeeds, the final test assertion message should include the captured artifact (e.g., the leaked data or successful return code) as proof.

## How AutoRepro Submissions Work

Each AutoRepro project's main purpose is to generate an `autorepro-submission.zip` file for your report.

You declare metadata about your test using the DSL blocks (e.g., `appTest {}`, `submission {}`) provided by the `com.android.security.autorepro.*` plugins in your `build.gradle.kts` files.

There are two key Gradle tasks:
1.  `./gradlew assembleSubmissionSources`: This task compiles the metadata from your DSL blocks into a `manifest.json` file, which it places in an intermediate `build/autorepro-submission/` directory along with your source code.
2.  `./gradlew assembleSubmissionZip`: This task packages the contents of that intermediate directory into the final `autorepro-submission.zip`.

Our internal systems parse the `autorepro-submission.zip` file, using the `manifest.json` inside it to reconstruct your test. Because the it's based on the generated manifest and not the Gradle files, any custom Gradle logic in your build files is not part of the final submission and will be ignored.

## What is the "AutoRepro Placeholder"?

Throughout the projects, you will find variants of the string `autorepro_placeholder` used in package names, resource files, and other identifiers.

When your submission is processed, our internal tooling performs a find-and-replace on this token to assign your test a unique name for translation into the Android build system.

Please do not modify the `autorepro_placeholder` string. Leave it as-is in all file names, package names, and resource paths.

For full documentation on writing an AutoRepro test, please see the [public documentation](https://source.android.com/docs/security/test/autorepro).