feat(scanner): expose LLM token usage in ScanResult JSON output (#146)

* feat(adjudicator): demote literal-regex false positives on deterministic HIGH+ findings

Introduces an optional per-finding adjudicator that runs between the
deterministic analyzers (static / pipeline / behavioral / bytecode / yara)
and the LLM analyzer. For each deterministic HIGH or CRITICAL finding it
asks the configured LLM whether the file around the matched line actually
contains the threat the rule was designed to catch, or whether the regex
fired on benign content. Findings identified as literal-regex false
positives (verdict=false_positive, confidence>=threshold) are demoted to
INFO for downstream verdict computation. The original severity and the
LLM's reasoning are preserved in the finding's metadata for audit.

Because the adjudicator runs before the LLM analyzer, demoted findings do
not enter the LLM analyzer's static-finding enrichment context — so a
wrong deterministic HIGH cannot be amplified into further LLM findings
citing the same pattern hit. This addresses the confirmation-cascade
failure mode described in the linked issue without any changes to
llm_analyzer.py.

Safety property (load-bearing): the adjudicator can only demote findings,
never promote them. LLM errors, timeouts, malformed output, or unexpected
verdicts all leave the finding at its original severity. Enabling this
pass cannot introduce false negatives.

Off by default (--adjudicate CLI flag, ScanPolicy.adjudicator.enabled).
Reuses the same env-var conventions as the LLM analyzer for model and
temperature configuration, so Claude 4.x on Bedrock and OpenAI o1-series
work out of the box.

Includes:
- New skill_scanner/core/analyzers/adjudicator.py (self-contained module)
- AdjudicatorPolicy in ScanPolicy
- --adjudicate CLI flag on both scan entry points
- Integration in scanner.py between Phase 1 and Phase 2 analyzers
- Audit records surfaced in ScanResult.scan_metadata.adjudicator
- 11 pytest tests covering the load-bearing safety cases
- docs/architecture/analyzers/adjudicator.md

* style(adjudicator): ruff --fix + ruff format for pre-commit compliance

* fix(adjudicator): address CodeRabbit review — path containment, YAML round-trip, override precedence, prompt hardening

Six review-driven fixes plus a soften-the-language docs pass.

1. **Path containment** (adjudicator.py:_adjudicate_one) — resolve
   ``skill_dir / file_path`` and reject anything that lands outside the
   skill directory. Absolute paths and ``..`` traversal now short-circuit
   to a "skipped" AdjudicationResult before any file is read.

2. **YAML round-trip for AdjudicatorPolicy** (scan_policy.py:_from_dict
   and _to_dict) — custom policy files with an ``adjudicator:`` section
   were silently discarded on load and never emitted on ``to_yaml``.
   Wired through following the AnalyzersPolicy / LLMAnalysisPolicy
   pattern already in the file.

3. **--adjudicate on scan-repo** (cli.py:scan_repo_command) — the flag
   was defined in _add_common_scan_flags but scan_repo_command didn't
   read it, so ``skill-scanner scan-repo <url> --adjudicate`` silently
   did nothing. Mirrors the toggle already present on scan_command and
   scan_all_command.

4. **Confidence range enforcement** (adjudicator.py:_adjudicate_one) —
   the response contract is confidence 1-5, but the code accepted any
   integer. A malformed ``{"verdict":"false_positive","confidence":999}``
   would demote past any min_fp_confidence threshold. Now validated and
   fails closed on out-of-range values (including 0).

5. **Preserve adjudicator demotion through severity_overrides**
   (scanner.py:_apply_severity_overrides) — a policy severity-override
   entry could raise a demoted finding back to HIGH/CRITICAL, defeating
   the demote-to-INFO contract. _apply_severity_overrides now skips
   findings that carry ``metadata['adjudication']['demoted_to']``.

6. **Prompt-injection hardening** (adjudicator.py:_call_llm and new
   _SYSTEM_PROMPT constant) — scanned file content is untrusted evidence.
   Split the request into a role=system rubric (trusted) and a role=user
   payload (rubric + untrusted evidence), with the system prompt
   explicitly instructing the model to ignore any instructions embedded
   in the file content. Defense in depth: the demote-only invariant
   already bounds the blast radius, but keeping trusted rubric separate
   from untrusted evidence is standard practice for LLM-as-judge flows.

7. **Docs / docstring softening** — replaced "cannot introduce false
   negatives" with a more accurate statement: error paths (LLM
   unavailable, malformed output, out-of-range confidence, path escape)
   preserve severity, but a wrong ``false_positive`` verdict from the
   LLM itself can still demote a real threat. That's why the pass is
   off by default and every demotion is preserved in metadata for review.

New tests (all 16 pass):
- test_out_of_range_confidence_keeps_original_severity
- test_zero_confidence_keeps_original_severity
- test_absolute_path_outside_skill_dir_is_skipped
- test_parent_traversal_is_skipped
- test_llm_receives_system_prompt

Ruff-clean, format-clean.

* feat: add trusted_reference_domains to LLM analysis policy

Add a policy-driven mechanism to demote LLM findings (transitive trust,
supply chain) to LOW when all referenced domains are declared as trusted
in the scan policy.

This addresses systematic false positives for organizations hosting
skills and documentation on self-managed GitLab/GitHub instances, where
the LLM analyzer flags references to internal repos as external threats.

Changes:
- LLMAnalysisPolicy: new trusted_reference_domains field (set[str])
- llm_analyzer._convert_to_findings: demotion logic after existing
  is_internal_file_reading filter
- Two helpers: _references_only_trusted_domains (URL extraction) and
  _mentions_only_trusted_domains (plain-text domain detection)
- default_policy.yaml: empty default list with documentation

The mechanism mirrors known_installer_domains: findings are demoted to
LOW (maintaining visibility) rather than suppressed entirely.

* fix(llm): allow Vertex AI to use ambient Application Default Credentials

ProviderConfig.validate() required a truthy credential for every provider
except Bedrock and Ollama, and the only credential source it checked for
Vertex was GOOGLE_APPLICATION_CREDENTIALS. This blocked ambient auth via
a GCE/Cloud Run attached service account or Workload Identity, even though
LiteLLM/google-auth already fall back to it automatically when no explicit
credential is passed -- the same pattern already supported for Bedrock's
IAM role. Excludes is_vertex from the check, mirroring the Bedrock/Ollama
precedent, and documents the fallback.

* Bumps to resolve security findings

* feat(scanner): expose LLM token usage in ScanResult JSON output (#136)

LiteLLM and the Google GenAI SDK both return prompt/completion token
counts on every response, but the scanner discarded them after pulling
out the text content, leaving downstream pipelines with no way to
attribute LLM call cost to a scan without monkey-patching provider
internals.

Extract token usage at the provider-response boundary for both LiteLLM
and Google SDK request paths, accumulate it per analyzer (covering
multi-call cases like consensus-judging runs and meta-analysis
follow-up passes), aggregate across all LLM analyzers in
SkillScanner, and fold in MetaAnalyzer's spend separately since it
runs as a post-processing step outside the scanner's own aggregation.
Surfaces as an additive `llm_usage` field on ScanResult.to_dict(),
omitted entirely on static-only scans.

* fix(llm): don't leak Vertex ADC credential path into GEMINI_API_KEY

- _resolve_api_key() now returns None for Vertex instead of the
  GOOGLE_APPLICATION_CREDENTIALS path, since vertex_ai/gemini-* models
  set both is_vertex and is_gemini, which was causing the file path to
  be written into GEMINI_API_KEY.
- Regenerated configuration-reference.md via generate_reference_docs.py
  instead of hand-editing, and updated the underlying descriptions so
  the doc doesn't drift on next regeneration.

Addresses CodeRabbit review feedbak on #144.

* revert unrelated cli-command-reference.md regeneration

* fix: address CodeRabbit review comments on PR #146

- Fix inconsistent JSON example: analyzers_used now includes
  llm_analyzer/meta_analyzer to match the shown non-empty llm_usage block.
- Expose ScanResult.llm_usage through the /scan API response: ScanResponse
  was missing the field, so single-scan (and /scan-upload, which delegates
  to it) API clients never received token usage even though the scanner
  computed it. Batch scan was unaffected since it serializes via to_dict().
- Add regression tests covering both the combined analyzer+meta-analyzer
  usage case and the omitted-when-disabled case.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(llm): scope trusted-domain severity demotion

---------

Co-authored-by: Rohan Isawe <rohan.isawe@smartsheet.com>
Co-authored-by: Olivier Jacques <ojacques2@gmail.com>
Co-authored-by: gyrospectre <7224858+gyrospectre@users.noreply.github.com>
Co-authored-by: Vineeth Sai Narajala <vnarajal@cisco.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: 6 people

docs/reference/output-formats.md

@@ -95,17 +95,24 @@ skill-scanner scan evals/skills/data-exfiltration/environment-secrets --format j
   ],
   "scan_duration_seconds": 0.13,
   "duration_ms": 127,
-  "analyzers_used": ["static_analyzer", "bytecode", "pipeline"],
+  "analyzers_used": ["static_analyzer", "bytecode", "pipeline", "llm_analyzer", "meta_analyzer"],
   "timestamp": "2026-02-19T21:58:33.032573",
   "scan_metadata": {
     "policy_name": "default",
     "policy_version": "1.0",
     "policy_preset_base": "balanced",
     "policy_fingerprint_sha256": "45b486..."
+  },
+  "llm_usage": {
+    "input_tokens": 5312,
+    "output_tokens": 842,
+    "total_tokens": 6154
   }
 }
 ```
 
+`llm_usage` is only present when at least one LLM call was made (`--use-llm` and/or `--enable-meta`), aggregated across every LLM analyzer and meta-analysis call for the scan. It's omitted entirely on static-only scans.
+
 Use `--compact` to remove pretty-printing for machine pipelines.
 
 ### Table

skill_scanner/api/router.py

@@ -97,14 +97,20 @@
 
 MetaAnalyzer: type | None
 apply_meta_analysis_to_results: Callable[..., list] | None
+merge_meta_analyzer_usage: Callable[..., None] | None
 try:
-    from ..core.analyzers.meta_analyzer import MetaAnalyzer, apply_meta_analysis_to_results
+    from ..core.analyzers.meta_analyzer import (
+        MetaAnalyzer,
+        apply_meta_analysis_to_results,
+        merge_meta_analyzer_usage,
+    )
 
     META_AVAILABLE = True
 except (ImportError, ModuleNotFoundError):
     META_AVAILABLE = False
     MetaAnalyzer = None
     apply_meta_analysis_to_results = None
+    merge_meta_analyzer_usage = None
 
 router = APIRouter()
 
@@ -215,6 +221,7 @@ class ScanResponse(BaseModel):
     scan_duration_seconds: float
     timestamp: str
     findings: list[dict]
+    llm_usage: dict[str, int] | None = None
 
 
 class HealthResponse(BaseModel):
@@ -456,6 +463,8 @@ def run_scan():
                 )
                 result.findings = filtered_findings
                 result.analyzers_used.append("meta_analyzer")
+                if merge_meta_analyzer_usage is not None:
+                    merge_meta_analyzer_usage(result, meta_analyzer)
             except Exception as meta_error:
                 logger.warning("Meta-analysis failed: %s", meta_error)
 
@@ -469,6 +478,7 @@ def run_scan():
             scan_duration_seconds=result.scan_duration_seconds,
             timestamp=result.timestamp.isoformat(),
             findings=[f.to_dict() for f in result.findings],
+            llm_usage=result.llm_usage,
         )
 
     except SkillLoadError as e:
@@ -712,6 +722,8 @@ async def _run_batch_meta(scanner_ref, report_ref, policy_ref):
                             )
                             result.findings = filtered_findings
                             result.analyzers_used.append("meta_analyzer")
+                            if merge_meta_analyzer_usage is not None:
+                                merge_meta_analyzer_usage(result, meta_analyzer)
                         except Exception:
                             pass
 

skill_scanner/cli/cli.py

@@ -54,14 +54,20 @@
 # Optional Meta analyzer
 MetaAnalyzer: type | None
 apply_meta_analysis_to_results: Callable[..., list] | None
+merge_meta_analyzer_usage: Callable[..., None] | None
 try:
-    from ..core.analyzers.meta_analyzer import MetaAnalyzer, apply_meta_analysis_to_results
+    from ..core.analyzers.meta_analyzer import (
+        MetaAnalyzer,
+        apply_meta_analysis_to_results,
+        merge_meta_analyzer_usage,
+    )
 
     META_AVAILABLE = True
 except (ImportError, ModuleNotFoundError):
     META_AVAILABLE = False
     MetaAnalyzer = None
     apply_meta_analysis_to_results = None
+    merge_meta_analyzer_usage = None
 
 logger = logging.getLogger("skill_scanner.cli")
 
@@ -411,6 +417,8 @@ def scan_command(args: argparse.Namespace) -> int:
                 )
                 result.findings = filtered
                 result.analyzers_used.append("meta_analyzer")
+                if merge_meta_analyzer_usage is not None:
+                    merge_meta_analyzer_usage(result, meta_analyzer)
 
                 # Surface meta-analysis insights into scan_metadata
                 if result.scan_metadata is None:
@@ -524,6 +532,8 @@ def scan_all_command(args: argparse.Namespace) -> int:
                     total_new += len(meta_result.missed_threats)
                     result.findings = filtered
                     result.analyzers_used.append("meta_analyzer")
+                    if merge_meta_analyzer_usage is not None:
+                        merge_meta_analyzer_usage(result, meta_analyzer)
 
                     # Surface meta-analysis insights
                     if result.scan_metadata is None:
@@ -649,6 +659,8 @@ def scan_repo_command(args: argparse.Namespace) -> int:
                             total_new += len(meta_result.missed_threats)
                             result.findings = filtered
                             result.analyzers_used.append("meta_analyzer")
+                            if merge_meta_analyzer_usage is not None:
+                                merge_meta_analyzer_usage(result, meta_analyzer)
 
                             # Surface meta-analysis insights
                             if result.scan_metadata is None:

skill_scanner/core/analyzers/llm_analyzer.py

@@ -41,7 +41,13 @@
 from .base import BaseAnalyzer
 from .llm_prompt_builder import PromptBuilder
 from .llm_provider_config import ProviderConfig
-from .llm_request_handler import _TEMPERATURE_UNSET, LLMRequestHandler
+from .llm_request_handler import (
+    _TEMPERATURE_UNSET,
+    LLMRequestHandler,
+    LLMTokenUsage,
+    _add_token_usage,
+    _empty_token_usage,
+)
 from .llm_response_parser import ResponseParser
 
 if TYPE_CHECKING:
@@ -254,6 +260,9 @@ def __init__(
         self.rate_limit_delay = rate_limit_delay
         self.timeout = timeout
 
+        # Cumulative token usage across all LLM calls in the most recent analyze() run.
+        self._llm_usage: LLMTokenUsage = _empty_token_usage()
+
         # Enriched context from other analyzers (set externally before analyze())
         self.enrichment_context: str | None = None
 
@@ -263,6 +272,11 @@ def __init__(
         # Tracks the last analysis error (read by the scanner for analyzers_failed)
         self.last_error: str | None = None
 
+    @property
+    def llm_usage(self) -> LLMTokenUsage:
+        """Cumulative token usage from the most recent analyze() run."""
+        return dict(self._llm_usage)  # type: ignore[return-value]
+
     def set_enrichment_context(
         self,
         *,
@@ -327,6 +341,7 @@ async def analyze_async(self, skill: Skill) -> list[Finding]:
         Returns:
             List of security findings
         """
+        self._llm_usage = _empty_token_usage()
         findings = []
         budget_skipped: list[dict] = []
 
@@ -450,6 +465,7 @@ async def analyze_async(self, skill: Skill) -> list[Finding]:
                 response_content = await self.request_handler.make_request(
                     messages, context=f"threat analysis for {skill.name}"
                 )
+                _add_token_usage(self._llm_usage, self.request_handler.last_usage)
                 analysis_result = self.response_parser.parse(response_content)
                 findings.extend(self._convert_to_findings(analysis_result, skill))
             else:
@@ -503,6 +519,7 @@ async def _consensus_analyze(self, messages: list[dict], skill: Skill) -> list[F
                 response_content = await self.request_handler.make_request(
                     messages, context=f"consensus run {run_idx + 1}/{self.consensus_runs} for {skill.name}"
                 )
+                _add_token_usage(self._llm_usage, self.request_handler.last_usage)
                 analysis_result = self.response_parser.parse(response_content)
                 run_findings = self._convert_to_findings(analysis_result, skill)
                 all_run_findings.append(run_findings)

skill_scanner/core/analyzers/llm_request_handler.py

@@ -28,10 +28,63 @@
 import os
 import warnings
 from pathlib import Path
-from typing import Any
+from typing import Any, TypedDict
 
 from .llm_provider_config import ProviderConfig
 
+
+class LLMTokenUsage(TypedDict):
+    """Provider-normalized token counts for one or more LLM calls."""
+
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+
+
+def _empty_token_usage() -> LLMTokenUsage:
+    return {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
+
+
+def _extract_token_usage(response: Any) -> LLMTokenUsage:
+    """Read token counts from a LiteLLM (or compatible) response object.
+
+    LiteLLM exposes usage as ``response.usage.prompt_tokens`` /
+    ``response.usage.completion_tokens``.  Both fields are normalised to the
+    ``input_tokens`` / ``output_tokens`` names used in our output schema so
+    callers never need to know which provider returned which key.
+    """
+    usage = getattr(response, "usage", None)
+    if usage is None:
+        return _empty_token_usage()
+    input_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
+    output_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
+    total_tokens = int(getattr(usage, "total_tokens", 0) or input_tokens + output_tokens)
+    return {"input_tokens": input_tokens, "output_tokens": output_tokens, "total_tokens": total_tokens}
+
+
+def _add_token_usage(total: LLMTokenUsage, delta: LLMTokenUsage) -> None:
+    """Accumulate *delta* into *total* in-place."""
+    total["input_tokens"] += delta["input_tokens"]
+    total["output_tokens"] += delta["output_tokens"]
+    total["total_tokens"] += delta["total_tokens"]
+
+
+def _extract_google_sdk_token_usage(response: Any) -> LLMTokenUsage:
+    """Read token counts from a Google GenAI SDK ``GenerateContentResponse``.
+
+    The SDK exposes usage as ``response.usage_metadata.prompt_token_count`` /
+    ``candidates_token_count``, normalised here to the same ``input_tokens`` /
+    ``output_tokens`` names ``_extract_token_usage`` produces for LiteLLM.
+    """
+    usage = getattr(response, "usage_metadata", None)
+    if usage is None:
+        return _empty_token_usage()
+    input_tokens = int(getattr(usage, "prompt_token_count", 0) or 0)
+    output_tokens = int(getattr(usage, "candidates_token_count", 0) or 0)
+    total_tokens = int(getattr(usage, "total_token_count", 0) or input_tokens + output_tokens)
+    return {"input_tokens": input_tokens, "output_tokens": output_tokens, "total_tokens": total_tokens}
+
+
 logger = logging.getLogger(__name__)
 
 acompletion: Any
@@ -151,6 +204,14 @@ def __init__(
         self.response_schema = self._load_response_schema()
         self._use_plain_json_output = self._env_flag_enabled("SKILL_SCANNER_LLM_FORCE_JSON_OBJECT")
 
+        # Token usage for the most recent make_request() call (reset each call).
+        self._last_usage: LLMTokenUsage = _empty_token_usage()
+
+    @property
+    def last_usage(self) -> LLMTokenUsage:
+        """Token counts from the most recent make_request() call."""
+        return dict(self._last_usage)  # type: ignore[return-value]
+
     def _env_flag_enabled(self, env_name: str) -> bool:
         """Treat common truthy env values as enabled."""
         raw_value = os.getenv(env_name, "")
@@ -283,6 +344,7 @@ async def make_request(self, messages: list[dict[str, str]], context: str = "")
         Raises:
             Exception: If all retries exhausted
         """
+        self._last_usage = _empty_token_usage()
         if self.provider_config.use_google_sdk:
             # For Google SDK, combine system and user messages into a single prompt
             # Google SDK doesn't have separate system/user roles like OpenAI/Anthropic
@@ -322,6 +384,7 @@ async def _make_litellm_request(self, messages: list[dict[str, str]], context: s
 
                 response = await acompletion(**request_params, drop_params=True)
                 content: str = response.choices[0].message.content or ""
+                self._last_usage = _extract_token_usage(response)
                 return content
 
             except Exception as e:
@@ -336,6 +399,7 @@ async def _make_litellm_request(self, messages: list[dict[str, str]], context: s
                     retry_params["response_format"] = {"type": "json_object"}
                     response = await acompletion(**retry_params, drop_params=True)
                     content: str = response.choices[0].message.content or ""
+                    self._last_usage = _extract_token_usage(response)
                     return content
 
                 last_exception = e
@@ -407,6 +471,7 @@ def generate():
                     return response
 
                 response = await loop.run_in_executor(None, generate)
+                self._last_usage = _extract_google_sdk_token_usage(response)
 
                 # Extract text from response (new SDK format)
                 # Response has .text attribute directly

skill_scanner/core/analyzers/meta_analyzer.py

@@ -45,10 +45,18 @@
 from typing import TYPE_CHECKING, Any
 
 from ...threats.threats import ThreatMapping
-from ..models import Finding, Severity, Skill, ThreatCategory
+from ..models import Finding, ScanResult, Severity, Skill, ThreatCategory
 from .base import BaseAnalyzer
 from .llm_provider_config import ProviderConfig
-from .llm_request_handler import _TEMPERATURE_UNSET, LLMRequestHandler, _resolve_temperature
+from .llm_request_handler import (
+    _TEMPERATURE_UNSET,
+    LLMRequestHandler,
+    LLMTokenUsage,
+    _add_token_usage,
+    _empty_token_usage,
+    _extract_token_usage,
+    _resolve_temperature,
+)
 from .llm_request_options import resolve_llm_user, supports_openai_user_param
 
 if TYPE_CHECKING:
@@ -365,9 +373,17 @@ def __init__(
         self.max_retries = max_retries
         self.timeout = timeout
 
+        # Cumulative token usage across all LLM calls in the most recent analyze_with_findings() run.
+        self._llm_usage: LLMTokenUsage = _empty_token_usage()
+
         # Load prompts
         self._load_prompts()
 
+    @property
+    def llm_usage(self) -> LLMTokenUsage:
+        """Cumulative token usage from the most recent analyze_with_findings() run."""
+        return dict(self._llm_usage)  # type: ignore[return-value]
+
     def _load_prompts(self):
         """Load meta-analysis prompt templates from files."""
         prompts_dir = Path(__file__).parent.parent.parent / "data" / "prompts"
@@ -427,6 +443,8 @@ async def analyze_with_findings(
         Returns:
             MetaAnalysisResult with validated findings, false positives, and recommendations
         """
+        self._llm_usage = _empty_token_usage()
+
         if not findings:
             return MetaAnalysisResult(
                 overall_risk_assessment={
@@ -877,6 +895,7 @@ async def _make_llm_request(self, system_prompt: str, user_prompt: str) -> str:
             try:
                 response = await acompletion(**api_params, drop_params=True)
                 content: str = response.choices[0].message.content or ""
+                _add_token_usage(self._llm_usage, _extract_token_usage(response))
                 return content
 
             except Exception as e:
@@ -1128,3 +1147,20 @@ def apply_meta_analysis_to_results(
     result_findings.extend(missed_findings)
 
     return result_findings
+
+
+def merge_meta_analyzer_usage(result: ScanResult, meta_analyzer: MetaAnalyzer) -> None:
+    """Fold a MetaAnalyzer's token usage into a scan result's aggregated ``llm_usage``.
+
+    MetaAnalyzer always runs as a separate post-processing step after
+    ``SkillScanner`` has already produced a ``ScanResult`` (see
+    ``analyze_with_findings``), so its token spend isn't captured by
+    ``SkillScanner``'s own per-scan aggregation. Call this immediately after
+    ``analyze_with_findings()`` to fold the meta-analysis call(s) in.
+    """
+    usage = meta_analyzer.llm_usage
+    if not any(usage.values()):
+        return
+    aggregated: LLMTokenUsage = dict(result.llm_usage) if result.llm_usage else _empty_token_usage()  # type: ignore[assignment]
+    _add_token_usage(aggregated, usage)
+    result.llm_usage = dict(aggregated)  # type: ignore[arg-type]

skill_scanner/core/models.py

@@ -218,6 +218,7 @@ class ScanResult:
     analyzability_score: float | None = None
     analyzability_details: dict[str, Any] | None = None
     scan_metadata: dict[str, Any] | None = None
+    llm_usage: dict[str, int] | None = None
 
     @property
     def is_safe(self) -> bool:
@@ -265,6 +266,8 @@ def to_dict(self) -> dict[str, Any]:
         }
         if self.analyzers_failed:
             result["analyzers_failed"] = self.analyzers_failed
+        if self.llm_usage:
+            result["llm_usage"] = self.llm_usage
         return result