From 65bbf02a4c9164bb4718ed6592d80f94293785cd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 26 Jun 2026 06:38:28 +0000
Subject: [PATCH 1/2] Run SpotBugs early in CI code-style gate; suppress
 model-path PATH_TRAVERSAL_IN
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

spotbugs:check is bound to the Maven verify phase, which only the publish
deploy goal reaches, so SpotBugs ran only at snapshot/release publish — a
PATH_TRAVERSAL_IN finding red a release after every jar had already built.

Add a SpotBugs step to the existing fast code-style job (after Spotless,
before the informational jdeps step) so it runs on every PR/push and gates
publish (publish-* already needs: code-style). Mirrors the existing early
Spotless gate; no needs: change required.

Provisionally suppress the PATH_TRAVERSAL_IN finding in OfflineModelGuard /
ModelParameters (operator-supplied --model path; same threat model as the
existing LlamaLoader suppression) and track an open deep-check in TODO.md for
whether it — and the LlamaLoader suppression — can be genuinely resolved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0137c1LhUbNvW3kt4eF9Kqyb
---
 .github/workflows/publish.yml |  2 ++
 TODO.md                       | 13 +++++++++++++
 spotbugs-exclude.xml          | 23 +++++++++++++++++++++++
 3 files changed, 38 insertions(+)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 0f073ff1..0f63804e 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -84,6 +84,8 @@ jobs:
           distribution: temurin
       - name: Spotless check (fail fast on format violations)
         run: mvn -B --no-transfer-progress spotless:check
+      - name: SpotBugs check (fail fast on static-analysis findings)
+        run: mvn -B --no-transfer-progress -DskipTests -Denforcer.skip=true compile spotbugs:check
       - name: Print internal package dependency graph (jdeps, informational)
         continue-on-error: true
         run: |
diff --git a/TODO.md b/TODO.md
index d28f1d1b..0e976eee 100644
--- a/TODO.md
+++ b/TODO.md
@@ -13,6 +13,19 @@ cross-cutting initiative.
 
 ## Open — jllama-specific
 
+### PATH_TRAVERSAL_IN suppressions — deep-check whether they can be resolved (open)
+
+Two `PATH_TRAVERSAL_IN` suppressions live in `spotbugs-exclude.xml`: the long-standing
+`LlamaLoader` (native-lib path resolved from three operator-controlled inputs) and the new
+`OfflineModelGuard` / `ModelParameters` (`--model` GGUF path), added when SpotBugs moved from
+the publish-only `verify` phase to the fast early `code-style` CI gate (so the finding now reds
+every PR, not just a release). Both are currently justified as "operator-supplied path, no
+meaningful allowed-root." **Deep-check whether a genuine fix is feasible** — e.g. canonicalize +
+validate, reject `..` traversal where an expected root exists, or otherwise narrow the sink —
+instead of suppressing. If it is, replace the suppression with code + a regression test; if it
+genuinely is not, keep the suppression and record the finalized rationale here (and on the
+`LlamaLoader` block). See [`../workspace/policies/spotbugs-suppressions.md`](../workspace/policies/spotbugs-suppressions.md).
+
 ### PIT gate not hermetic — `value.ContentPart.audioFile(Path)` (open)
 
 The PIT mutation gate reaches 100% **only when the audio test fixture is present**. Without it the
diff --git a/spotbugs-exclude.xml b/spotbugs-exclude.xml
index 94db590c..ccfbed28 100644
--- a/spotbugs-exclude.xml
+++ b/spotbugs-exclude.xml
@@ -147,6 +147,29 @@ SPDX-License-Identifier: MIT
         <Bug pattern="PATH_TRAVERSAL_IN"/>
     </Match>
 
+    <!--
+        PROVISIONAL (under review; see java-llama.cpp TODO.md
+        "PATH_TRAVERSAL_IN suppressions deep-check"). Same operator-supplied
+        model-path case as the LlamaLoader suppression above.
+        OfflineModelGuard.check() does Files.exists(Paths.get(model)) where the
+        model path comes from ModelParameters.getModel() (the configured local
+        model file) to verify the GGUF exists before native load; findsecbugs
+        PATH_TRAVERSAL_IN taints that path. The model path is configured by
+        whoever launches the process (CLI flag or builder), not untrusted
+        end-user input, and the whole point of the setting is to let the
+        operator point at an arbitrary GGUF on disk, so there is no meaningful
+        allowed-root to validate against. Suppressed pending a deep check of
+        whether a real resolution (canonicalize / restrict) is feasible for
+        this and the LlamaLoader case.
+    -->
+    <Match>
+        <Or>
+            <Class name="net.ladenthin.llama.loader.OfflineModelGuard"/>
+            <Class name="net.ladenthin.llama.parameters.ModelParameters"/>
+        </Or>
+        <Bug pattern="PATH_TRAVERSAL_IN"/>
+    </Match>
+
     <!--
         LlamaIterator and LlamaModel form a deliberate producer/consumer
         cycle: LlamaModel.generate(...) returns a LlamaIterable that

From 0534b06fa634b32b295014c6e3dead178837b8d6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 26 Jun 2026 06:47:01 +0000
Subject: [PATCH 2/2] Finalize PATH_TRAVERSAL_IN suppression after deep-check
 (settled false positive)

Deep-checked the two PATH_TRAVERSAL_IN sites flagged by findsecbugs:
LlamaLoader (native-lib path from the lib.path / java.library.path / tmpdir
JVM properties) and OfflineModelGuard.check (a read-only Files.exists on the
configured model path). In both the tainted input is the operator's own
process configuration set at launch, not untrusted input crossing a privilege
boundary, and there is no allowed-root to validate against (pointing at an
arbitrary GGUF/library anywhere on disk is the whole point). So it is a settled
false positive for a JNI library and no code fix is appropriate.

Consolidate the two suppression blocks into one finalized <Match> over all
three classes with the reviewed rationale, drop the "provisional/under review"
language, and close the deep-check item in TODO.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0137c1LhUbNvW3kt4eF9Kqyb
---
 TODO.md              | 13 ---------
 spotbugs-exclude.xml | 68 +++++++++++++++++++-------------------------
 2 files changed, 30 insertions(+), 51 deletions(-)

diff --git a/TODO.md b/TODO.md
index 0e976eee..d28f1d1b 100644
--- a/TODO.md
+++ b/TODO.md
@@ -13,19 +13,6 @@ cross-cutting initiative.
 
 ## Open — jllama-specific
 
-### PATH_TRAVERSAL_IN suppressions — deep-check whether they can be resolved (open)
-
-Two `PATH_TRAVERSAL_IN` suppressions live in `spotbugs-exclude.xml`: the long-standing
-`LlamaLoader` (native-lib path resolved from three operator-controlled inputs) and the new
-`OfflineModelGuard` / `ModelParameters` (`--model` GGUF path), added when SpotBugs moved from
-the publish-only `verify` phase to the fast early `code-style` CI gate (so the finding now reds
-every PR, not just a release). Both are currently justified as "operator-supplied path, no
-meaningful allowed-root." **Deep-check whether a genuine fix is feasible** — e.g. canonicalize +
-validate, reject `..` traversal where an expected root exists, or otherwise narrow the sink —
-instead of suppressing. If it is, replace the suppression with code + a regression test; if it
-genuinely is not, keep the suppression and record the finalized rationale here (and on the
-`LlamaLoader` block). See [`../workspace/policies/spotbugs-suppressions.md`](../workspace/policies/spotbugs-suppressions.md).
-
 ### PIT gate not hermetic — `value.ContentPart.audioFile(Path)` (open)
 
 The PIT mutation gate reaches 100% **only when the audio test fixture is present**. Without it the
diff --git a/spotbugs-exclude.xml b/spotbugs-exclude.xml
index ccfbed28..6cabea32 100644
--- a/spotbugs-exclude.xml
+++ b/spotbugs-exclude.xml
@@ -123,47 +123,39 @@ SPDX-License-Identifier: MIT
     </Match>
 
     <!--
-        LlamaLoader is the native-library bootstrap. It resolves the path
-        to libjllama.{so,dylib,dll} from three operator-controlled inputs:
-
-          1. -Dnet.ladenthin.llama.lib.path=<dir>   (line 94)
-          2. java.library.path entries              (line 119)
-          3. java.io.tmpdir + hardcoded basename    (lines 133, 171, 215)
-
-        findsecbugs PATH_TRAVERSAL_IN flags every non-literal argument to
-        Paths.get, treating "user input" syntactically as "any non-literal
-        string". The threat-model reality is different: all three sources
-        are JVM properties set at process launch by whoever started the
-        process. An attacker who can set JVM properties has already won;
-        there is no untrusted end-user input reaching these paths.
-
-        Canonicalize-and-restrict-to-root mitigation is not applicable
-        because the whole purpose of the .lib.path property is to let the
-        operator point at any directory containing the native library;
-        there is no meaningful "allowed root" to validate against.
-    -->
-    <Match>
-        <Class name="net.ladenthin.llama.loader.LlamaLoader"/>
-        <Bug pattern="PATH_TRAVERSAL_IN"/>
-    </Match>
-
-    <!--
-        PROVISIONAL (under review; see java-llama.cpp TODO.md
-        "PATH_TRAVERSAL_IN suppressions deep-check"). Same operator-supplied
-        model-path case as the LlamaLoader suppression above.
-        OfflineModelGuard.check() does Files.exists(Paths.get(model)) where the
-        model path comes from ModelParameters.getModel() (the configured local
-        model file) to verify the GGUF exists before native load; findsecbugs
-        PATH_TRAVERSAL_IN taints that path. The model path is configured by
-        whoever launches the process (CLI flag or builder), not untrusted
-        end-user input, and the whole point of the setting is to let the
-        operator point at an arbitrary GGUF on disk, so there is no meaningful
-        allowed-root to validate against. Suppressed pending a deep check of
-        whether a real resolution (canonicalize / restrict) is feasible for
-        this and the LlamaLoader case.
+        PATH_TRAVERSAL_IN (reviewed 2026-06-26): confirmed a false positive for
+        this JNI library, so this suppression is permanent and no code fix is
+        appropriate. Two operator-controlled path sites are flagged:
+
+          1. LlamaLoader (native-library bootstrap) resolves
+             libjllama.{so,dylib,dll} from three JVM-launch inputs:
+               a. the net.ladenthin.llama.lib.path system property (a directory)
+               b. java.library.path entries
+               c. java.io.tmpdir plus a hard-coded basename
+          2. OfflineModelGuard.check() does Files.exists(Paths.get(model)),
+             where model is ModelParameters.getModel() (the configured local
+             model-file path), to fail fast when the offline flag is set and the
+             local model is absent. This is a read-only existence check; the
+             path is not opened or written here.
+
+        findsecbugs taints every non-literal Paths.get argument (System
+        properties and CLI/builder config count as taint sources), but all of
+        these inputs are the operator's own process configuration set at launch,
+        not untrusted end-user input crossing a privilege boundary. An attacker
+        who can set the model path, the lib.path property, or java.library.path
+        already controls the JVM; there is no traversal boundary to cross.
+
+        Why no fix: the canonicalize-and-restrict-to-an-allowed-root remediation
+        does not apply. Pointing at an arbitrary GGUF or library directory
+        anywhere on disk is the entire purpose of these settings, so there is no
+        meaningful allowed root, and a parent-directory-rejecting check would
+        break the legitimate relative-path case. An embedder that exposes the
+        model path to untrusted remote users must validate it before calling this
+        library; that lies outside the library's API contract.
     -->
     <Match>
         <Or>
+            <Class name="net.ladenthin.llama.loader.LlamaLoader"/>
             <Class name="net.ladenthin.llama.loader.OfflineModelGuard"/>
             <Class name="net.ladenthin.llama.parameters.ModelParameters"/>
         </Or>