Maven
Spider Sense is a -javaagent, and spring-boot:run forks the JVM that runs the application, so the option has to reach that forked JVM, not Maven’s own.
There is no Spider Sense Maven plugin, because the Spring Boot Maven plugin already has the two parameters Spider Sense needs.
agents (user property spring-boot.run.agents) takes agent jars and puts each on the forked JVM as -javaagent:.
jvmArguments (spring-boot.run.jvmArguments) or systemPropertyVariables carry the spidersense.* properties.
Both parameters belong to spring-boot:run and to spring-boot:start, the goal that runs the application around integration tests.
Once, from the command line
mvn spring-boot:run -Dspring-boot.run.agents=/home/me/tools/spider-sense.jar
mvn spring-boot:run -Dspring-boot.run.agents=/home/me/tools/spider-sense.jar \
-Dspring-boot.run.jvmArguments="-Dspidersense.port=4001 -Dspidersense.service=orders"
Without spidersense.service the service is spring.application.name, and without that the directory of the project whose target/classes holds the main class, as The service name describes.
Every property the jar takes is listed in Configuration.
In the POM
The maven-dependency-plugin copies the jar from Maven Central into target/ before the application starts, and spring-boot:run names it in agents.
spring-boot:run runs the test-compile phase first, so the copy bound to the initialize phase has finished by then.
Put both in a profile, so mvn spring-boot:run -Psense is the run under Spider Sense and mvn spring-boot:run is the plain one:
<profiles>
<profile>
<id>sense</id>
<properties>
<spider-sense.version>0.1.0</spider-sense.version>
<spider-sense.jar>${project.build.directory}/spider-sense.jar</spider-sense.jar>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>spider-sense</id>
<phase>initialize</phase>
<goals>
<goal>copy</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>net.benelog.spidersense</groupId>
<artifactId>spider-sense</artifactId>
<version>${spider-sense.version}</version>
<outputDirectory>${project.build.directory}</outputDirectory>
<destFileName>spider-sense.jar</destFileName>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<agents>
<agent>${spider-sense.jar}</agent>
</agents>
<systemPropertyVariables>
<spidersense.service>${project.artifactId}</spidersense.service>
<spidersense.port>4000</spidersense.port>
</systemPropertyVariables>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
A jar that is not on Maven Central goes in as a path.
Drop the maven-dependency-plugin execution and set spider-sense.jar to the file, in the profile or on the command line with -Dspider-sense.jar=/home/me/tools/spider-sense.jar.
Tests under Surefire
Surefire forks its own JVM and takes its options from argLine.
The agent goes into the build’s own argLine through a property, spider-sense.argLine, which is empty in the main <properties> and which the sense profile fills.
mvn test -Psense then runs the tests under Spider Sense, and mvn test runs them plain.
A Surefire <argLine> in the profile instead would replace the build’s own rather than add to it, because Maven takes a plain-text element of a plugin’s configuration from the profile and drops the build’s, so the tests would lose their other JVM options (--add-opens, a heap size, Mockito’s agent) under -Psense only.
Forward to a standalone Spider Sense rather than embedding one.
A test JVM is short-lived and may be forked more than once, and only one of several embedded servers can bind the port.
<properties>
<!-- empty unless the sense profile sets it -->
<spider-sense.argLine></spider-sense.argLine>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<!-- the project's own options, if any, then the agent's -->
<argLine>-Xmx1g ${spider-sense.argLine}</argLine>
</configuration>
</plugin>
</plugins>
</build>
<!-- in the sense profile, beside spider-sense.version and spider-sense.jar -->
<properties>
<spider-sense.argLine>-javaagent:${spider-sense.jar} -Dspidersense.collector=http://127.0.0.1:4000 -Dspidersense.service=${project.artifactId}-test</spider-sense.argLine>
</properties>
-Xmx1g stands for whatever the project already passes; a project that passes nothing writes <argLine>${spider-sense.argLine}</argLine>.
A project whose argLine property is set by JaCoCo’s prepare-agent writes <argLine>@{argLine} ${spider-sense.argLine}</argLine>, so that both agents load.
The sense profile is where spider-sense.jar is defined and the jar copied, so -Psense alone puts the tests under Spider Sense.
Start the standalone once before mvn test -Psense runs, as forwarding describes.
The packaged jar
Running the packaged jar under the agent needs nothing in the POM at all:
mvn -q package -DskipTests
java -javaagent:/home/me/tools/spider-sense.jar -Dspidersense.service=orders -jar target/orders-0.0.1.jar
The CLI from target/
The CLI is the same jar, so once the sense profile has copied it into target/, you run it from there:
java -jar target/spider-sense.jar findings --since=start
java -jar target/spider-sense.jar init # the CLAUDE.md block and the skills
The CLI asks http://127.0.0.1:4000 unless told otherwise, and it does not read the POM.
When the POM gives the application another port, add --url=http://127.0.0.1:<port> to each command.
Or set the port as spidersense.port=<port> in spider-sense.properties in the project directory instead, which the application and the CLI both read (The properties file).
The CLI documents every command, and The Agent Skill documents what init writes.