Add PoC quality and AGENTS.md
Bug: 441727732
Test: verified gemini-cli uses AGENTS.md
Change-Id: If5fc006f51b8d02ebabdf8d30b928557c57ad5ee
diff --git a/README.md b/README.md
index 5e88223..69397f0 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,26 @@
* [`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.
diff --git a/example/.gemini/settings.json b/example/.gemini/settings.json
new file mode 100644
index 0000000..05d52d7
--- /dev/null
+++ b/example/.gemini/settings.json
@@ -0,0 +1,5 @@
+{
+ "context": {
+ "fileName": "AGENTS.md"
+ }
+}
diff --git a/example/AGENTS.md b/example/AGENTS.md
new file mode 100644
index 0000000..172e49e
--- /dev/null
+++ b/example/AGENTS.md
@@ -0,0 +1,56 @@
+# Agent Instructions for AutoRepro Submissions
+
+This document provides quality standards and instructions for creating and modifying AutoRepro proofs-of-concept (PoCs). The primary goal is to produce a high-impact PoC that clearly demonstrates the security impact of a vulnerability.
+
+## Guiding Principle: Prove the Security Boundary Crossing
+
+A high-quality PoC must do more than just trigger a bug. It should provide proof that a security boundary has been crossed. To achieve this, all PoCs should follow a three-step "fail-then-succeed" pattern.
+
+### The Three-Step Pattern
+
+1. **Setup:** Prepare the device and get it into a vulnerable state. This includes installing necessary apps, pushing files, and setting the device to the state it needs to be in just before the exploit is triggered. The setup step can use root to configure the device so long as it's justified with inline comments and is a generally accepted state for an end-user's device to be in.
+
+2. **Prove the Boundary:** Before triggering the vulnerability, attempt to perform the target action and **assert that the action fails**. For example, if the vulnerability allows you to read a protected file, first try to read it and assert that you receive a "Permission Denied" error.
+
+3. **Trigger & Verify:** Trigger the vulnerability. Immediately afterward, repeat the exact same action from Step 2 and **assert that the action fails on a patched device**. This provides clear proof that your exploit has bypassed the security boundary. A vulnerable device should fail the test because the trigger action passed.
+
+### The Final Assertion
+
+The final assertion in Step 3 is the most important part of the test. It must be clear, descriptive, and contain the proof of the exploit.
+
+The final assertion message (for a vulnerable device) **should include the captured artifact** as proof when possible.
+
+**Good Example:**
+```java
+// Step 3: Trigger the vulnerability, then read the file again.
+try {
+ String fileContent = readFile("/data/data/com.victim.app/files/secret.txt");
+ // The test fails because the device is vulnerable, and the failure message
+ // contains the proof (the content of the secret file).
+ Assert.fail("Vulnerability Verified: Successfully read protected file. Content: '" + fileContent + "'");
+} catch (ThisVulnSpecificException e) {
+ Log.i(TAG, "protected against reading protected file", e);
+}
+
+```
+
+By following this pattern, the resulting test provides a clear, verifiable, and high-impact demonstration of the vulnerability.
+
+## Style Guidelines
+
+* It's helpful if the test code is annotated with comments explaining why certain steps work.
+* Tests should be non-interactive and avoid manual steps or manual UI interaction.
+* UI interaction can be driven with uiautomator.
+* Avoid `Thread.sleep()` for synchronization.
+
+## How to Run Tests Manually
+
+The recommended way to run tests is using the pre-configured Android Studio run configurations (e.g., `autorepro_nonroot_arm64`).
+
+To run the tests from the command line, you must replicate the steps found in the `.run/*.run.xml` files. These XML files define the two-stage process for running a test:
+
+1. **The Build Step:** Look for a "BeforeRunTask" that executes a Gradle command. This command is responsible for compiling all the code and assembling the necessary test artifacts.
+
+2. **The Execution Step:** After the build, the configuration defines the main command that invokes the test harness (e.g., Tradefed) and runs the actual test suite. You will need to identify the executable and the program parameters being passed to it.
+
+By inspecting the XML, you can extract these two commands to run the full test process from your terminal.
diff --git a/sync-common.sh b/sync-common.sh
index 5b2dfd2..361b63e 100755
--- a/sync-common.sh
+++ b/sync-common.sh
@@ -106,6 +106,8 @@
"${SOURCE_DIR}/./gradlew"
"${SOURCE_DIR}/./gradlew.bat"
"${SOURCE_DIR}/./settings.gradle.kts"
+ "${SOURCE_DIR}/./AGENTS.md"
+ "${SOURCE_DIR}/./.gemini/settings.json"
)
# Start syncing
diff --git a/templates/app-instrumented-only/.gemini/settings.json b/templates/app-instrumented-only/.gemini/settings.json
new file mode 100644
index 0000000..05d52d7
--- /dev/null
+++ b/templates/app-instrumented-only/.gemini/settings.json
@@ -0,0 +1,5 @@
+{
+ "context": {
+ "fileName": "AGENTS.md"
+ }
+}
diff --git a/templates/app-instrumented-only/AGENTS.md b/templates/app-instrumented-only/AGENTS.md
new file mode 100644
index 0000000..172e49e
--- /dev/null
+++ b/templates/app-instrumented-only/AGENTS.md
@@ -0,0 +1,56 @@
+# Agent Instructions for AutoRepro Submissions
+
+This document provides quality standards and instructions for creating and modifying AutoRepro proofs-of-concept (PoCs). The primary goal is to produce a high-impact PoC that clearly demonstrates the security impact of a vulnerability.
+
+## Guiding Principle: Prove the Security Boundary Crossing
+
+A high-quality PoC must do more than just trigger a bug. It should provide proof that a security boundary has been crossed. To achieve this, all PoCs should follow a three-step "fail-then-succeed" pattern.
+
+### The Three-Step Pattern
+
+1. **Setup:** Prepare the device and get it into a vulnerable state. This includes installing necessary apps, pushing files, and setting the device to the state it needs to be in just before the exploit is triggered. The setup step can use root to configure the device so long as it's justified with inline comments and is a generally accepted state for an end-user's device to be in.
+
+2. **Prove the Boundary:** Before triggering the vulnerability, attempt to perform the target action and **assert that the action fails**. For example, if the vulnerability allows you to read a protected file, first try to read it and assert that you receive a "Permission Denied" error.
+
+3. **Trigger & Verify:** Trigger the vulnerability. Immediately afterward, repeat the exact same action from Step 2 and **assert that the action fails on a patched device**. This provides clear proof that your exploit has bypassed the security boundary. A vulnerable device should fail the test because the trigger action passed.
+
+### The Final Assertion
+
+The final assertion in Step 3 is the most important part of the test. It must be clear, descriptive, and contain the proof of the exploit.
+
+The final assertion message (for a vulnerable device) **should include the captured artifact** as proof when possible.
+
+**Good Example:**
+```java
+// Step 3: Trigger the vulnerability, then read the file again.
+try {
+ String fileContent = readFile("/data/data/com.victim.app/files/secret.txt");
+ // The test fails because the device is vulnerable, and the failure message
+ // contains the proof (the content of the secret file).
+ Assert.fail("Vulnerability Verified: Successfully read protected file. Content: '" + fileContent + "'");
+} catch (ThisVulnSpecificException e) {
+ Log.i(TAG, "protected against reading protected file", e);
+}
+
+```
+
+By following this pattern, the resulting test provides a clear, verifiable, and high-impact demonstration of the vulnerability.
+
+## Style Guidelines
+
+* It's helpful if the test code is annotated with comments explaining why certain steps work.
+* Tests should be non-interactive and avoid manual steps or manual UI interaction.
+* UI interaction can be driven with uiautomator.
+* Avoid `Thread.sleep()` for synchronization.
+
+## How to Run Tests Manually
+
+The recommended way to run tests is using the pre-configured Android Studio run configurations (e.g., `autorepro_nonroot_arm64`).
+
+To run the tests from the command line, you must replicate the steps found in the `.run/*.run.xml` files. These XML files define the two-stage process for running a test:
+
+1. **The Build Step:** Look for a "BeforeRunTask" that executes a Gradle command. This command is responsible for compiling all the code and assembling the necessary test artifacts.
+
+2. **The Execution Step:** After the build, the configuration defines the main command that invokes the test harness (e.g., Tradefed) and runs the actual test suite. You will need to identify the executable and the program parameters being passed to it.
+
+By inspecting the XML, you can extract these two commands to run the full test process from your terminal.
diff --git a/templates/app-with-activity/.gemini/settings.json b/templates/app-with-activity/.gemini/settings.json
new file mode 100644
index 0000000..05d52d7
--- /dev/null
+++ b/templates/app-with-activity/.gemini/settings.json
@@ -0,0 +1,5 @@
+{
+ "context": {
+ "fileName": "AGENTS.md"
+ }
+}
diff --git a/templates/app-with-activity/AGENTS.md b/templates/app-with-activity/AGENTS.md
new file mode 100644
index 0000000..172e49e
--- /dev/null
+++ b/templates/app-with-activity/AGENTS.md
@@ -0,0 +1,56 @@
+# Agent Instructions for AutoRepro Submissions
+
+This document provides quality standards and instructions for creating and modifying AutoRepro proofs-of-concept (PoCs). The primary goal is to produce a high-impact PoC that clearly demonstrates the security impact of a vulnerability.
+
+## Guiding Principle: Prove the Security Boundary Crossing
+
+A high-quality PoC must do more than just trigger a bug. It should provide proof that a security boundary has been crossed. To achieve this, all PoCs should follow a three-step "fail-then-succeed" pattern.
+
+### The Three-Step Pattern
+
+1. **Setup:** Prepare the device and get it into a vulnerable state. This includes installing necessary apps, pushing files, and setting the device to the state it needs to be in just before the exploit is triggered. The setup step can use root to configure the device so long as it's justified with inline comments and is a generally accepted state for an end-user's device to be in.
+
+2. **Prove the Boundary:** Before triggering the vulnerability, attempt to perform the target action and **assert that the action fails**. For example, if the vulnerability allows you to read a protected file, first try to read it and assert that you receive a "Permission Denied" error.
+
+3. **Trigger & Verify:** Trigger the vulnerability. Immediately afterward, repeat the exact same action from Step 2 and **assert that the action fails on a patched device**. This provides clear proof that your exploit has bypassed the security boundary. A vulnerable device should fail the test because the trigger action passed.
+
+### The Final Assertion
+
+The final assertion in Step 3 is the most important part of the test. It must be clear, descriptive, and contain the proof of the exploit.
+
+The final assertion message (for a vulnerable device) **should include the captured artifact** as proof when possible.
+
+**Good Example:**
+```java
+// Step 3: Trigger the vulnerability, then read the file again.
+try {
+ String fileContent = readFile("/data/data/com.victim.app/files/secret.txt");
+ // The test fails because the device is vulnerable, and the failure message
+ // contains the proof (the content of the secret file).
+ Assert.fail("Vulnerability Verified: Successfully read protected file. Content: '" + fileContent + "'");
+} catch (ThisVulnSpecificException e) {
+ Log.i(TAG, "protected against reading protected file", e);
+}
+
+```
+
+By following this pattern, the resulting test provides a clear, verifiable, and high-impact demonstration of the vulnerability.
+
+## Style Guidelines
+
+* It's helpful if the test code is annotated with comments explaining why certain steps work.
+* Tests should be non-interactive and avoid manual steps or manual UI interaction.
+* UI interaction can be driven with uiautomator.
+* Avoid `Thread.sleep()` for synchronization.
+
+## How to Run Tests Manually
+
+The recommended way to run tests is using the pre-configured Android Studio run configurations (e.g., `autorepro_nonroot_arm64`).
+
+To run the tests from the command line, you must replicate the steps found in the `.run/*.run.xml` files. These XML files define the two-stage process for running a test:
+
+1. **The Build Step:** Look for a "BeforeRunTask" that executes a Gradle command. This command is responsible for compiling all the code and assembling the necessary test artifacts.
+
+2. **The Execution Step:** After the build, the configuration defines the main command that invokes the test harness (e.g., Tradefed) and runs the actual test suite. You will need to identify the executable and the program parameters being passed to it.
+
+By inspecting the XML, you can extract these two commands to run the full test process from your terminal.
diff --git a/templates/same-app-id/.gemini/settings.json b/templates/same-app-id/.gemini/settings.json
new file mode 100644
index 0000000..05d52d7
--- /dev/null
+++ b/templates/same-app-id/.gemini/settings.json
@@ -0,0 +1,5 @@
+{
+ "context": {
+ "fileName": "AGENTS.md"
+ }
+}
diff --git a/templates/same-app-id/AGENTS.md b/templates/same-app-id/AGENTS.md
new file mode 100644
index 0000000..172e49e
--- /dev/null
+++ b/templates/same-app-id/AGENTS.md
@@ -0,0 +1,56 @@
+# Agent Instructions for AutoRepro Submissions
+
+This document provides quality standards and instructions for creating and modifying AutoRepro proofs-of-concept (PoCs). The primary goal is to produce a high-impact PoC that clearly demonstrates the security impact of a vulnerability.
+
+## Guiding Principle: Prove the Security Boundary Crossing
+
+A high-quality PoC must do more than just trigger a bug. It should provide proof that a security boundary has been crossed. To achieve this, all PoCs should follow a three-step "fail-then-succeed" pattern.
+
+### The Three-Step Pattern
+
+1. **Setup:** Prepare the device and get it into a vulnerable state. This includes installing necessary apps, pushing files, and setting the device to the state it needs to be in just before the exploit is triggered. The setup step can use root to configure the device so long as it's justified with inline comments and is a generally accepted state for an end-user's device to be in.
+
+2. **Prove the Boundary:** Before triggering the vulnerability, attempt to perform the target action and **assert that the action fails**. For example, if the vulnerability allows you to read a protected file, first try to read it and assert that you receive a "Permission Denied" error.
+
+3. **Trigger & Verify:** Trigger the vulnerability. Immediately afterward, repeat the exact same action from Step 2 and **assert that the action fails on a patched device**. This provides clear proof that your exploit has bypassed the security boundary. A vulnerable device should fail the test because the trigger action passed.
+
+### The Final Assertion
+
+The final assertion in Step 3 is the most important part of the test. It must be clear, descriptive, and contain the proof of the exploit.
+
+The final assertion message (for a vulnerable device) **should include the captured artifact** as proof when possible.
+
+**Good Example:**
+```java
+// Step 3: Trigger the vulnerability, then read the file again.
+try {
+ String fileContent = readFile("/data/data/com.victim.app/files/secret.txt");
+ // The test fails because the device is vulnerable, and the failure message
+ // contains the proof (the content of the secret file).
+ Assert.fail("Vulnerability Verified: Successfully read protected file. Content: '" + fileContent + "'");
+} catch (ThisVulnSpecificException e) {
+ Log.i(TAG, "protected against reading protected file", e);
+}
+
+```
+
+By following this pattern, the resulting test provides a clear, verifiable, and high-impact demonstration of the vulnerability.
+
+## Style Guidelines
+
+* It's helpful if the test code is annotated with comments explaining why certain steps work.
+* Tests should be non-interactive and avoid manual steps or manual UI interaction.
+* UI interaction can be driven with uiautomator.
+* Avoid `Thread.sleep()` for synchronization.
+
+## How to Run Tests Manually
+
+The recommended way to run tests is using the pre-configured Android Studio run configurations (e.g., `autorepro_nonroot_arm64`).
+
+To run the tests from the command line, you must replicate the steps found in the `.run/*.run.xml` files. These XML files define the two-stage process for running a test:
+
+1. **The Build Step:** Look for a "BeforeRunTask" that executes a Gradle command. This command is responsible for compiling all the code and assembling the necessary test artifacts.
+
+2. **The Execution Step:** After the build, the configuration defines the main command that invokes the test harness (e.g., Tradefed) and runs the actual test suite. You will need to identify the executable and the program parameters being passed to it.
+
+By inspecting the XML, you can extract these two commands to run the full test process from your terminal.
diff --git a/templates/single-ndk/.gemini/settings.json b/templates/single-ndk/.gemini/settings.json
new file mode 100644
index 0000000..05d52d7
--- /dev/null
+++ b/templates/single-ndk/.gemini/settings.json
@@ -0,0 +1,5 @@
+{
+ "context": {
+ "fileName": "AGENTS.md"
+ }
+}
diff --git a/templates/single-ndk/AGENTS.md b/templates/single-ndk/AGENTS.md
new file mode 100644
index 0000000..172e49e
--- /dev/null
+++ b/templates/single-ndk/AGENTS.md
@@ -0,0 +1,56 @@
+# Agent Instructions for AutoRepro Submissions
+
+This document provides quality standards and instructions for creating and modifying AutoRepro proofs-of-concept (PoCs). The primary goal is to produce a high-impact PoC that clearly demonstrates the security impact of a vulnerability.
+
+## Guiding Principle: Prove the Security Boundary Crossing
+
+A high-quality PoC must do more than just trigger a bug. It should provide proof that a security boundary has been crossed. To achieve this, all PoCs should follow a three-step "fail-then-succeed" pattern.
+
+### The Three-Step Pattern
+
+1. **Setup:** Prepare the device and get it into a vulnerable state. This includes installing necessary apps, pushing files, and setting the device to the state it needs to be in just before the exploit is triggered. The setup step can use root to configure the device so long as it's justified with inline comments and is a generally accepted state for an end-user's device to be in.
+
+2. **Prove the Boundary:** Before triggering the vulnerability, attempt to perform the target action and **assert that the action fails**. For example, if the vulnerability allows you to read a protected file, first try to read it and assert that you receive a "Permission Denied" error.
+
+3. **Trigger & Verify:** Trigger the vulnerability. Immediately afterward, repeat the exact same action from Step 2 and **assert that the action fails on a patched device**. This provides clear proof that your exploit has bypassed the security boundary. A vulnerable device should fail the test because the trigger action passed.
+
+### The Final Assertion
+
+The final assertion in Step 3 is the most important part of the test. It must be clear, descriptive, and contain the proof of the exploit.
+
+The final assertion message (for a vulnerable device) **should include the captured artifact** as proof when possible.
+
+**Good Example:**
+```java
+// Step 3: Trigger the vulnerability, then read the file again.
+try {
+ String fileContent = readFile("/data/data/com.victim.app/files/secret.txt");
+ // The test fails because the device is vulnerable, and the failure message
+ // contains the proof (the content of the secret file).
+ Assert.fail("Vulnerability Verified: Successfully read protected file. Content: '" + fileContent + "'");
+} catch (ThisVulnSpecificException e) {
+ Log.i(TAG, "protected against reading protected file", e);
+}
+
+```
+
+By following this pattern, the resulting test provides a clear, verifiable, and high-impact demonstration of the vulnerability.
+
+## Style Guidelines
+
+* It's helpful if the test code is annotated with comments explaining why certain steps work.
+* Tests should be non-interactive and avoid manual steps or manual UI interaction.
+* UI interaction can be driven with uiautomator.
+* Avoid `Thread.sleep()` for synchronization.
+
+## How to Run Tests Manually
+
+The recommended way to run tests is using the pre-configured Android Studio run configurations (e.g., `autorepro_nonroot_arm64`).
+
+To run the tests from the command line, you must replicate the steps found in the `.run/*.run.xml` files. These XML files define the two-stage process for running a test:
+
+1. **The Build Step:** Look for a "BeforeRunTask" that executes a Gradle command. This command is responsible for compiling all the code and assembling the necessary test artifacts.
+
+2. **The Execution Step:** After the build, the configuration defines the main command that invokes the test harness (e.g., Tradefed) and runs the actual test suite. You will need to identify the executable and the program parameters being passed to it.
+
+By inspecting the XML, you can extract these two commands to run the full test process from your terminal.
