What the agent does
The agent reads the build before adding a plugin to it, because where the scan runs and what it fails on depend on the existing phases. In a Spring Boot service like the complete/ project in spring-guides/gs-rest-service, pom.xml inherits from spring-boot-starter-parent 4.0.8, sets java.version to 17, and depends on spring-boot-starter-webmvc plus spring-boot-starter-webmvc-test in test scope; the only plugin is spring-boot-maven-plugin. .mvn/wrapper/maven-wrapper.properties pins Maven 3.9.16 through the wrapper. .github/workflows/continuous-integration-build.yml sets up Temurin 17 with the Maven cache and runs ./mvnw --batch-mode clean package in each module, and .github/dependabot.yml groups monthly Maven and Gradle updates while ignoring major and minor bumps, so a vulnerable transitive dependency can sit unnoticed for a long time between those updates.
The plugin goes into <build><plugins> as org.owasp:dependency-check-maven at 12.1.3, the latest release on Maven Central at the time of writing, with one execution bound to the verify phase running the check goal. The agent sets failBuildOnCVSS to 7 so high and critical findings fail the build and lower ones only appear in the report, leaves the analyzers at their defaults, and adds an empty dependency-check-suppressions.xml wired through suppressionFiles so a false positive has a documented place to go. Report formats are HTML for people and JSON for tooling, written under target/, which .gitignore already excludes.
The part that decides whether the scan is usable is the vulnerability database. Dependency-check downloads NVD data through the NVD API, and without an API key the download is throttled hard enough that the first run takes far longer than a build should. The agent reads the key from an environment variable rather than putting it in the pom: <nvdApiKey>${env.NVD_API_KEY}</nvdApiKey>, and in the sandbox that variable comes from a Project secret, which Rush exposes as an environment variable to every session started in that Project. In the workflow it adds a step that runs ./mvnw --batch-mode verify with NVD_API_KEY from a repository secret, and caches the plugin's data directory under ~/.m2/repository/org/owasp/dependency-check-data keyed by the date, so each CI run updates the database incrementally instead of downloading it from scratch.
The agent runs ./mvnw --batch-mode clean verify in the sandbox with the key, reads target/dependency-check-report.html, and records what the scan found against the current spring-boot-starter-webmvc tree. If anything scores at or above the threshold the build fails, and the pull request says so with the CVE ids and the dependency path rather than suppressing them; the suppression file stays empty unless a finding is a confirmed false positive, in which case the entry carries a notes element explaining why. It also runs the two existing GreetingControllerTests through the same verify, since binding to that phase means tests run first and a failing scan never masks a failing test.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add OWASP Dependency-Check to this Maven project. Read pom.xml, .mvn/wrapper/maven-wrapper.properties, .github/workflows/continuous-integration-build.yml, .github/dependabot.yml and .gitignore first. Add org.owasp:dependency-check-maven at the latest release on Maven Central as a build plugin with one execution of the check goal bound to the verify phase; set failBuildOnCVSS to 7, HTML and JSON report formats, and a suppressionFiles entry pointing at a new, empty dependency-check-suppressions.xml. Read the NVD API key from the NVD_API_KEY environment variable through the nvdApiKey parameter; never write a key into the pom. Add a CI step that runs ./mvnw --batch-mode verify with that secret and caches the dependency-check data directory in the local Maven repository. Run ./mvnw --batch-mode clean verify, read target/dependency-check-report.html, and open a pull request that lists every finding at or above the threshold with its CVE id and dependency path, or states that there were none, and does not suppress anything.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes pom.xml and the CI workflow and adds dependency-check-suppressions.xml. The description names the plugin version, the CVSS threshold and the phase the scan runs in, explains why the key is an environment variable and how CI supplies it, and lists the findings from the first scan with their CVE ids and the dependency path that pulls each one in, or says the tree was clean at the threshold.
The run's record keeps the full ./mvnw verify output, including the plugin's database update, the analyzer summary and the test run, so a reviewer can see how long the scan took with a key and that the existing tests still pass in the same build.
Before merging, a reviewer adds NVD_API_KEY to the repository's secrets, decides whether 7 is the right threshold for this service or whether to fail on anything above 0 and suppress deliberately, and considers running the scan on a schedule as well as on push, since a new CVE against an unchanged tree will not otherwise be noticed until the next commit.
Run it on every Monday morning
A dependency tree that passed on Friday can fail on Monday because a CVE was published against it, so the useful cadence is a schedule rather than a push. An automation on the Project with a schedule trigger each Monday morning and the prompt "run ./mvnw --batch-mode verify with the NVD key from the Project secret, and if dependency-check fails at the configured threshold open a pull request that bumps the affected dependency or, if no fix exists, adds a suppression with an expiry and a note" starts one run a week. The run reads NVD_API_KEY from the Project's secrets and clones the repository into its own sandbox.
A team with several Maven services starts the first setup once per repository from its own server: a POST /o/{org}/p/{project}/sessions each, in the Project that holds the NVD_API_KEY secret, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than opening a second pull request.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The plugin is a block of XML; the first run is the expensive part, because the NVD database has to come down and the findings have to be read against the real dependency tree. The agent does that once in its own sandbox with the key from a Project secret, so the pull request arrives with the actual findings and the actual scan time rather than a guess at either, and the workflow step is written knowing what the cache has to hold.
Every command and its output stay with the run, including the analyzer summary and the test output from the same verify, so a reviewer checks the evidence rather than the description. Several services can be set up at once, each on its own machine, each with its own report.
Frequently asked questions
Do I need an NVD API key?
In practice, yes. Without one the NVD API throttles the database download so heavily that the first run takes far longer than a CI job should. Request a key from NVD, store it as the NVD_API_KEY repository secret for CI and as a Project secret for runs on Rush, and the pom reads it from the environment; the key itself never goes into the repository.
Will it fail my build on the first run?
Only if a dependency in the tree has a vulnerability scoring 7 or above. The agent runs the scan before opening the pull request and reports what it found, so you know the answer before merging. Lower-scoring findings appear in the HTML report without failing anything.
Why bind it to verify rather than run it separately?
Because verify already runs after the tests in the Maven lifecycle, so ./mvnw verify gives one answer for both, and a failing test is reported before a failing scan. Running ./mvnw org.owasp:dependency-check-maven:check on its own still works for a quick local scan.
What about the Gradle build in the same module?
The guide repository also has a build.gradle beside pom.xml. This change covers Maven only; the Gradle equivalent is the org.owasp.dependencycheck plugin with the same settings, and the pull request notes that so the two builds do not drift.
More Maven jobs
The same job on other stacks
More jobs like this: Hand off a long task
- Add Page Caching to a Wagtail Site (Wagtail)
- Add Page Titles per Route to an Angular App (Angular)