> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentgg.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Test findings against a running app

> Live validation tests each finding against a running copy of your application and records the proof.

A browser in a Docker sandbox runs the attack of each finding and records the requests, screenshots, and a video as proof.

Live validation is off by default.

<Warning>
  Live validation sends real attack requests, and a test can change or delete data. Test only applications that you own or are authorized to test. Use a test or staging environment, not production.
</Warning>

## Prerequisites

* Docker, installed and running.
* A running copy of your application that your machine can reach.

The first run builds the sandbox image. This takes a few minutes.

## Run live validation

Add `--live-validate` and the URL of your application to a scan:

```bash theme={null}
agentgg scan . --live-validate --target-url http://localhost:3000 -o ./out
```

The sandbox can reach applications on your own machine, so a `localhost` URL works.

To test the findings of a finished scan, run `agentgg live-validate` on its output directory:

```bash theme={null}
agentgg live-validate ./out --target-url http://localhost:3000
```

Then run `agentgg score ./out` and `agentgg fix ./out` to update the scores and the suggested fixes for the new results.

## Add testing instructions

Use `--target-context` to tell the test how to use your application, for example the account to sign in with, the pages to test, and the actions to avoid. Pass the text directly, or `@` followed by the path to a file.

```bash theme={null}
agentgg scan . --live-validate --target-url http://localhost:3000 \
  --target-context @./testing-instructions.txt -o ./out
```

```text testing-instructions.txt theme={null}
Sign in at /login as qa@example.com with the password <password>.
Test the order pages. Do not delete data.
```

<Warning>
  The output directory stores these instructions, and the captured requests contain the session of the test account. Use a dedicated test account, and do not share the output directory publicly.
</Warning>

## Results

Live validation tests each primary finding, except findings that the validator marked `out-of-scope`. A finding is `reproduced` only when the attack succeeds and the same steps with harmless input do not.

| Result | Meaning |
| - | - |
| `reproduced` | The attack worked against the running application. |
| `refuted` | The attack did not work. |
| `inconclusive` | The test found no clear evidence, or it reached its time limit. |
| `error` | The test did not complete. This result says nothing about the finding. |
| `not-reproducible` | The finding describes a missing control, such as a missing security header, that a browser test cannot show. |

## Evidence

Each tested finding gets a `### Live validation` section in its finding file, with the result and the reasoning.

`reproduced` and `refuted` findings also keep their evidence in a folder next to the finding file: the test script, the Playwright trace, screenshots, and the requests. A `reproduced` finding also keeps a video of the attack.

Run `agentgg view ./out` to see the evidence in your browser.

## Options

| Flag | Default | Description |
| - | - | - |
| `--reproduce-max-turns <n>` | 50 | The maximum number of browser steps for one finding. Raise it for long, multi-step flows. |
| `--reproduce-timeout <s>` | 600 | The time limit for one finding, in seconds. |
| `--force` | Off | With `agentgg live-validate`, tests findings that already have a result. |
| `--sandbox-endpoint <url>` | None | Uses a sandbox that is already running, instead of Docker on this machine. Set the sandbox token in `AGENTGG_SANDBOX_TOKEN`. |

For all flags, see [Scan flags](/cli/reference/scan-flags).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.