Skip to content

Configure javaagent options per dependency and plugin context - #379

Merged
ryandens merged 7 commits into
mainfrom
worktree-javaagent-options-issue-50
Oct 17, 2026
Merged

ryandens merged 7 commits into
mainfrom
worktree-javaagent-options-issue-50

Conversation

@ryandens

@ryandens ryandens commented Jul 7, 2026 •

Copy link
Copy Markdown
Owner

Closes #50.

Adds dependency-owned options for -javaagent:<jar>=<options>, with independent configuration for application runs, tests, distributions, and Jib images.

import com.ryandens.javaagent.agentOptions

dependencies {
    applicationRunJavaagent("io.prometheus.jmx:jmx_prometheus_javaagent:0.20.0") {
        agentOptions = "12345:config/local.yaml"
    }
    testJavaagent("io.prometheus.jmx:jmx_prometheus_javaagent:0.20.0") {
        agentOptions = "12346:config/test.yaml"
    }
    applicationDistributionJavaagent("io.prometheus.jmx:jmx_prometheus_javaagent:0.20.0") {
        agentOptions = "12345:config/distribution.yaml"
    }
    jibJavaagent("io.prometheus.jmx:jmx_prometheus_javaagent:0.20.0") {
        agentOptions = "12345:/etc/agent/container.yaml"
    }
}

Each plugin registers only its own dependency configuration. The application convenience plugin supplies both run and distribution configurations; tar, zip, and installed distributions share generated launchers. The existing javaagent dependency configuration remains available for declarations shared by the enabled plugins. The project-wide options extension has been removed.

Any downstream configuration can override inherited options, including custom configurations. Descendant declarations take precedence over ancestors; conflicting sibling declarations fail unless a descendant supplies an override. Direct dependency options override inherited values, an explicit empty string clears inherited options, and conflicting direct options fail explicitly. Resolution follows dependency substitution and version conflict selection while preserving configuration-cache reuse. Classified and explicit-artifact dependencies without options remain supported, and main-artifact options do not leak to classifier artifacts. Distribution launchers preserve spaces and shell special characters.

Shared resolution strategies and configuration attributes follow normal Gradle semantics: extendsFrom does not inherit them. The README documents configuring the relevant agent configurations together, with tests for substitution and force rules.

Validation covers application/test execution, archive launchers and contents, container entrypoints, configuration-cache reuse, task invalidation, classifier compatibility, late dependency overrides, substitutions, forced versions, and option isolation. The full Gradle build, formatting, and plugin validation pass locally (31 tests). New coverage verifies shared defaults across all contexts, test-only options, custom downstream inheritance, sibling conflicts, and descendant overrides. GitHub Actions Linux, Windows, and Gradle wrapper validation all pass on the latest follow-up.

Comment thread jib-common/src/main/kotlin/com/ryandens/javaagent/jib/JavaagentJibExtension.kt Outdated
Comment thread plugin/src/main/java/com/ryandens/javaagent/AgentOptionsResolver.java Outdated
@ryandens
ryandens force-pushed the worktree-javaagent-options-issue-50 branch from 11e0ae1 to 7072c0e Compare July 7, 2026 06:28
macroscopeapp Bot added a commit that referenced this pull request Jul 23, 2026
…llegalStateExceptio (#391)

## Summary

Fixes an `IllegalStateException` that occurs when `agentOptions` is not
explicitly configured in the Jib extension.

## Changes

- Updated `JavaagentJibExtension.kt` to use `getOrElse(emptyMap())`
instead of `get()` when accessing `agentOptions`
- When `agentOptions` is not configured, the code now gracefully
defaults to an empty map rather than throwing an exception

## Problem

Previously, calling `extraConfig.get().agentOptions.get()` would throw
an `IllegalStateException` if the user had not set any agent options in
their configuration. This made `agentOptions` effectively required even
though it should be optional.

## Solution

Using `getOrElse(emptyMap())` provides a safe default value, making
`agentOptions` truly optional as intended.

<!-- Macroscope (Fix It For Me) template starts here -->
> [!NOTE]
> ### Macroscope: _Fix It For Me_
> - This PR originated from [this
comment](https://github.com/ryandens/javaagent-gradle-plugin/pull/379/files#r3641209014)
in #379.
> - Since auto-merge is on, Macroscope will merge this PR after waiting
for checks to pass.
> - If you'd rather not wait, you can always merge this yourself but
**no further action from you is currently needed**.
> - You can also @mention Macroscope in this PR to request further
changes.
>
> #### Activity
> Currently: <!-- Macroscope (Fix It For Me) current status starts here
-->_Waiting on checks_<!-- Macroscope (Fix It For Me) current status
ends here -->
>
> <details>
> <summary>Previously</summary>
>
> <!-- Macroscope (Fix It For Me) previous status starts here -->
> - Pushed ce934b7
> - Action failed: Validate
> - Waiting on checks
> - Pushed c882d5a
> - Working on next commit...
> - Waiting on checks
> - Pushed 089c78f
> <!-- Macroscope (Fix It For Me) previous status ends here -->
>
> </details>

----
<!-- Macroscope (Fix It For Me) template ends here -->
<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible
markers, and the markers themselves will not be visible in the GitHub
rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's
description, Macroscope will append its summary at the bottom of the
description. -->
> [!NOTE]
> ### Fix `IllegalStateException` by keying agent options on canonical
file path
> - Fixes a runtime `IllegalStateException` in `JavaagentJibExtension`
by replacing `Provider.get()` with `Provider.getOrElse(emptyMap())` when
no `agentOptions` are configured.
> - Changes `AgentOptionsResolver.optionsByFileName` to
`optionsByFilePath`, keying the options map by each artifact's canonical
file path instead of its file name. All consumers
(`JavaForkOptionsConfigurer`, `JavaagentAwareStartScriptGenerator`, Jib
plugin, run/test/distribution plugins) are updated to match.
> - Behavioral Change: agent option lookups in JVM fork args and
generated start scripts now use canonical paths; configs that relied on
file-name keying will need to be re-evaluated if duplicate file names
exist across different directories.
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized
ce934b7.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

---------

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
macroscopeapp Bot added a commit that referenced this pull request Jul 23, 2026
…artScriptGenerator (#392)

## Summary

Fixes a shell injection vulnerability in
`JavaagentAwareStartScriptGenerator.Fake.write()` by adding
platform-aware shell escaping for javaagent option strings.

## Changes

Added proper escaping for agent option values to prevent malicious input
from being interpreted as shell commands:

- **Unix scripts**: Option values are wrapped in single quotes with
internal single quotes escaped as `'\''`
- **Windows scripts**: `%` characters are doubled to `%%` to prevent
environment variable expansion

## Security Impact

Previously, unescaped option strings passed to the javaagent could
potentially be exploited to execute arbitrary shell commands. This fix
ensures that special characters in option values are properly escaped
for the target platform's shell interpreter.

<!-- Macroscope (Fix It For Me) template starts here -->
> [!NOTE]
> ### Macroscope: _Fix It For Me_
> - This PR originated from [this
comment](https://github.com/ryandens/javaagent-gradle-plugin/pull/379/files#r3641346092)
in #379.
> - Since auto-merge is on, Macroscope will merge this PR after waiting
for checks to pass.
> - If you'd rather not wait, you can always merge this yourself but
**no further action from you is currently needed**.
> - You can also @mention Macroscope in this PR to request further
changes.
>
> #### Activity
> Currently: <!-- Macroscope (Fix It For Me) current status starts here
-->_Waiting on checks_<!-- Macroscope (Fix It For Me) current status
ends here -->
>
> <details>
> <summary>Previously</summary>
>
> <!-- Macroscope (Fix It For Me) previous status starts here -->
> - Pushed 51d4603
> - Action failed: Validate
> - Waiting on checks
> - Pushed a62e381
> <!-- Macroscope (Fix It For Me) previous status ends here -->
>
> </details>

----
<!-- Macroscope (Fix It For Me) template ends here -->
<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible
markers, and the markers themselves will not be visible in the GitHub
rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's
description, Macroscope will append its summary at the bottom of the
description. -->
> [!NOTE]
> ### Fix shell injection vulnerability in
`JavaagentAwareStartScriptGenerator` by escaping option values
> - On Unix, javaagent option values are wrapped in single quotes with
internal single quotes escaped to prevent shell injection.
> - On Windows, percent signs in option values are doubled to prevent
variable expansion.
> - The
[`Writer`](https://github.com/ryandens/javaagent-gradle-plugin/pull/392/files#diff-b35a17536e95a01f0d06c07c9255cbcd47cfceeb6231638cda0393b65d70967b)
now accepts a `platform` argument to apply the correct escaping strategy
per OS.
> - Behavioral Change: generated start scripts now quote javaagent
option values, which changes the output format of `DEFAULT_JVM_OPTS` on
Unix.
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized
51d4603.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

---------

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
@ryandens

Copy link
Copy Markdown
Owner Author

could it work like this?

dependencies {
    javaagent("io.prometheus.jmx:jmx_prometheus_javaagent:0.20.0") {
            agentOptions.put("io.prometheus.jmx:jmx_prometheus_javaagent", "12345:config.yaml")
    }
}

ryandens and others added 6 commits October 17, 2026 00:20
Support the `-javaagent:<jar>=<options>` form of the flag by introducing a
`javaagent { }` extension with an `agentOptions` map keyed by dependency
coordinate (`group:name` for module dependencies, project path for project
dependencies). Keying by coordinate keeps options independent of the resolved
jar file name so they survive version bumps.

A shared `AgentOptionsResolver` resolves the coordinate-keyed options against
the configuration's resolved artifacts into a `fileName -> options` map, which
is threaded into all four contexts that build a `-javaagent:` argument: the
application `run` task, the `test` task, application distribution start
scripts, and jib container entrypoints. Agents without a matching entry are
attached with no suffix, preserving existing behavior.

Per the design discussion on the issue, options are a single project-level
value shared across contexts; per-context overrides are left as a follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FBTxQkVXBjJoBSfKPWyY3K
…llegalStateExceptio (#391)

## Summary

Fixes an `IllegalStateException` that occurs when `agentOptions` is not
explicitly configured in the Jib extension.

## Changes

- Updated `JavaagentJibExtension.kt` to use `getOrElse(emptyMap())`
instead of `get()` when accessing `agentOptions`
- When `agentOptions` is not configured, the code now gracefully
defaults to an empty map rather than throwing an exception

## Problem

Previously, calling `extraConfig.get().agentOptions.get()` would throw
an `IllegalStateException` if the user had not set any agent options in
their configuration. This made `agentOptions` effectively required even
though it should be optional.

## Solution

Using `getOrElse(emptyMap())` provides a safe default value, making
`agentOptions` truly optional as intended.

<!-- Macroscope (Fix It For Me) template starts here -->
> [!NOTE]
> ### Macroscope: _Fix It For Me_
> - This PR originated from [this
comment](https://github.com/ryandens/javaagent-gradle-plugin/pull/379/files#r3641209014)
in #379.
> - Since auto-merge is on, Macroscope will merge this PR after waiting
for checks to pass.
> - If you'd rather not wait, you can always merge this yourself but
**no further action from you is currently needed**.
> - You can also @mention Macroscope in this PR to request further
changes.
>
> #### Activity
> Currently: <!-- Macroscope (Fix It For Me) current status starts here
-->_Waiting on checks_<!-- Macroscope (Fix It For Me) current status
ends here -->
>
> <details>
> <summary>Previously</summary>
>
> <!-- Macroscope (Fix It For Me) previous status starts here -->
> - Pushed ce934b7
> - Action failed: Validate
> - Waiting on checks
> - Pushed c882d5a
> - Working on next commit...
> - Waiting on checks
> - Pushed 089c78f
> <!-- Macroscope (Fix It For Me) previous status ends here -->
>
> </details>

----
<!-- Macroscope (Fix It For Me) template ends here -->
<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible
markers, and the markers themselves will not be visible in the GitHub
rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's
description, Macroscope will append its summary at the bottom of the
description. -->
> [!NOTE]
> ### Fix `IllegalStateException` by keying agent options on canonical
file path
> - Fixes a runtime `IllegalStateException` in `JavaagentJibExtension`
by replacing `Provider.get()` with `Provider.getOrElse(emptyMap())` when
no `agentOptions` are configured.
> - Changes `AgentOptionsResolver.optionsByFileName` to
`optionsByFilePath`, keying the options map by each artifact's canonical
file path instead of its file name. All consumers
(`JavaForkOptionsConfigurer`, `JavaagentAwareStartScriptGenerator`, Jib
plugin, run/test/distribution plugins) are updated to match.
> - Behavioral Change: agent option lookups in JVM fork args and
generated start scripts now use canonical paths; configs that relied on
file-name keying will need to be re-evaluated if duplicate file names
exist across different directories.
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized
ce934b7.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

---------

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
…artScriptGenerator (#392)

## Summary

Fixes a shell injection vulnerability in
`JavaagentAwareStartScriptGenerator.Fake.write()` by adding
platform-aware shell escaping for javaagent option strings.

## Changes

Added proper escaping for agent option values to prevent malicious input
from being interpreted as shell commands:

- **Unix scripts**: Option values are wrapped in single quotes with
internal single quotes escaped as `'\''`
- **Windows scripts**: `%` characters are doubled to `%%` to prevent
environment variable expansion

## Security Impact

Previously, unescaped option strings passed to the javaagent could
potentially be exploited to execute arbitrary shell commands. This fix
ensures that special characters in option values are properly escaped
for the target platform's shell interpreter.

<!-- Macroscope (Fix It For Me) template starts here -->
> [!NOTE]
> ### Macroscope: _Fix It For Me_
> - This PR originated from [this
comment](https://github.com/ryandens/javaagent-gradle-plugin/pull/379/files#r3641346092)
in #379.
> - Since auto-merge is on, Macroscope will merge this PR after waiting
for checks to pass.
> - If you'd rather not wait, you can always merge this yourself but
**no further action from you is currently needed**.
> - You can also @mention Macroscope in this PR to request further
changes.
>
> #### Activity
> Currently: <!-- Macroscope (Fix It For Me) current status starts here
-->_Waiting on checks_<!-- Macroscope (Fix It For Me) current status
ends here -->
>
> <details>
> <summary>Previously</summary>
>
> <!-- Macroscope (Fix It For Me) previous status starts here -->
> - Pushed 51d4603
> - Action failed: Validate
> - Waiting on checks
> - Pushed a62e381
> <!-- Macroscope (Fix It For Me) previous status ends here -->
>
> </details>

----
<!-- Macroscope (Fix It For Me) template ends here -->
<!-- Macroscope's pull request summary starts here -->
<!-- Macroscope will only edit the content between these invisible
markers, and the markers themselves will not be visible in the GitHub
rendered markdown. -->
<!-- If you delete either of the start / end markers from your PR's
description, Macroscope will append its summary at the bottom of the
description. -->
> [!NOTE]
> ### Fix shell injection vulnerability in
`JavaagentAwareStartScriptGenerator` by escaping option values
> - On Unix, javaagent option values are wrapped in single quotes with
internal single quotes escaped to prevent shell injection.
> - On Windows, percent signs in option values are doubled to prevent
variable expansion.
> - The
[`Writer`](https://github.com/ryandens/javaagent-gradle-plugin/pull/392/files#diff-b35a17536e95a01f0d06c07c9255cbcd47cfceeb6231638cda0393b65d70967b)
now accepts a `platform` argument to apply the correct escaping strategy
per OS.
> - Behavioral Change: generated start scripts now quote javaagent
option values, which changes the output format of `DEFAULT_JVM_OPTS` on
Unix.
>
> <!-- Macroscope's review summary starts here -->
>
> <sup><a href="https://app.macroscope.com">Macroscope</a> summarized
51d4603.</sup>
> <!-- Macroscope's review summary ends here -->
>
<!-- macroscope-ui-refresh -->
<!-- Macroscope's pull request summary ends here -->

---------

Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>
@ryandens
ryandens force-pushed the worktree-javaagent-options-issue-50 branch from 2ae86eb to 8375b7d Compare October 17, 2026 07:20
@ryandens ryandens changed the title Add ability to pass options to javaagents (#50) Configure javaagent options per dependency and plugin context Oct 17, 2026
@ryandens
ryandens marked this pull request as ready for review October 17, 2026 07:33
@testlens-app

testlens-app Bot commented Oct 17, 2026

Copy link
Copy Markdown

✅ All tests passed ✅

🏷️ Commit: 9b9ac20
▶️ Tests: 2 executed
⚪️ Checks: 3/3 completed


Learn more about TestLens at testlens.app/docs.

@ryandens
ryandens merged commit 7757a6b into main Oct 17, 2026
3 checks passed
@ryandens
ryandens deleted the worktree-javaagent-options-issue-50 branch October 17, 2026 19:26
@ryandens ryandens mentioned this pull request Oct 17, 2026
ryandens added a commit that referenced this pull request Oct 17, 2026
Prepare version 0.13.0 after #379. Update the shared project version,
README plugin examples, and commented local-testing coordinates to match
the release, following the previous release-bump convention.

Publication follows the existing workflow: merge after Linux/Windows
checks pass, push the signed `0.13.0` tag at the merge commit, then
verify the Gradle Plugin Portal release job and create GitHub release
notes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add ability to pass arguments to a Java agent

1 participant