narvy-cli 1.1.5__tar.gz → 1.2.0__tar.gz

{narvy_cli-1.1.5 → narvy_cli-1.2.0}/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0]
+
+### Added
+
+- `narvy store-check <file>`: store readiness checks for an APK, AAB,
+  split-APK set (`.apks`, `.xapk`, `.apkm`) or IPA against the Google Play
+  and App Store upload requirements: target API level, 16 KB page size
+  (ELF segment alignment and zip alignment of native libraries),
+  `android:exported` on components with intent filters, debuggable builds,
+  cleartext traffic, foreground service types, permissions that need a Play
+  Console declaration, iOS SDK and minimum OS version, required-reason APIs
+  against the privacy manifests, listed third-party SDKs without a privacy
+  manifest, App Transport Security and purpose strings. Every finding cites
+  the value read in the binary and the official page the rule comes from;
+  a question the binary cannot settle is reported `not determined`, never
+  guessed. Options: `--json` (both languages), `--lang fr`, `--as-of DATE`
+  (store requirements are dated), `--fail-on warning`, `--verbose`. Exit
+  codes: 0 no blocker, 1 blocker (or warning with `--fail-on warning`),
+  3 file not analysable. The check runs offline, reads the archive in
+  memory, writes nothing to disk and sends no telemetry. Python standard
+  library only, no new dependency. It is not a security scan.
+
+### Changed
+
+- Secret findings are worded for what they are: "Potential secret: <kind>
+  (format match, not tested)" or "(pattern match, not tested)". Narvy never
+  tests a secret (no login, no API call, no revocation check). Findings
+  carry `secret_confidence` (`likely` or `potential`) and `secret_tested:
+  false` in JSON and SARIF. Public client keys shipped in app code (Firebase
+  configuration, Google API keys restricted by design) are reported as
+  Info.
+- Secret values are masked in every output: console table, JSON, SARIF,
+  the upload payload, raw tool output (`--verbose`) and log records. The
+  wording and masking are the same as the Narvy dashboard, so dashboard
+  fingerprints of uploaded findings do not change.
+
 ## [1.1.5]
 
 ### Changed

{narvy_cli-1.1.5/narvy_cli.egg-info → narvy_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: narvy-cli
-Version: 1.1.5
+Version: 1.2.0
 Summary: Free, local SAST scanner for Android, iOS, and polyglot web/backend source - plus passive web, host-audit, and cloud-posture scanning.
 Author: Narvy
 License: Apache-2.0
@@ -56,6 +56,11 @@ access or your own existing credentials:
 - `cloud-scan` - AWS account posture check using your own ambient AWS
   credentials
 
+and one check that is not a security scan:
+
+- `store-check` - Google Play and App Store upload requirements for an
+  APK, AAB, split-APK set or IPA, offline (see [Store check](#store-check))
+
 Your code, binaries and findings are never uploaded unless you explicitly
 pass `--upload`. The CLI does send anonymous usage statistics, described
 exactly in [Telemetry](#telemetry), which you can turn off.
@@ -181,6 +186,10 @@ narvy scans
 
 # Scan + upload every .apk/.aab/.apkm/.xapk/.ipa found in a folder, in one command
 narvy upload-all ./my-apps-folder/
+
+# Google Play / App Store upload requirements, offline (not a security scan)
+narvy store-check app-release.aab
+narvy store-check MyApp.ipa --lang fr --json
 ```
 
 Run `narvy doctor` before your first scan to check your Java/jadx/iOS
@@ -237,6 +246,40 @@ exhaust the machine. `NARVY_SEMGREP_JOBS` and `NARVY_SEMGREP_MAX_MEMORY_MB`
 listed in the scan notes. Outside a terminal (CI logs), a progress line is
 printed every 30 seconds; `NARVY_PROGRESS_INTERVAL` changes that (0 = off).
 
+## Store check
+
+`narvy store-check` answers one question: will Google Play or the App Store
+accept this build, and what will they ask about it? It reads the manifest,
+resources, native libraries, Info.plist, Mach-O load commands, imported
+symbols and privacy manifests of the file, and evaluates them against the
+store requirements in force at a date (`--as-of`, default today).
+
+```bash
+narvy store-check app-release.aab
+narvy store-check app.xapk --fail-on warning      # CI gate on warnings too
+narvy store-check MyApp.ipa --json > store.json   # EN and FR messages in one report
+narvy store-check MyApp.ipa --as-of 2027-02-01    # evaluate a future deadline
+```
+
+| Store | Checks |
+|-------|--------|
+| Google Play | `PLAY-TARGET-SDK`, `PLAY-16KB-ELF`, `PLAY-16KB-ZIPALIGN`, `PLAY-EXPORTED`, `PLAY-DEBUGGABLE`, `PLAY-CLEARTEXT`, `PLAY-FGS-TYPE`, `PLAY-FGS-PERMISSION`, `PLAY-FGS-DECLARATION`, `PLAY-PERMISSION-DECLARATION` |
+| App Store | `APPSTORE-SDK-VERSION`, `APPSTORE-MIN-OS`, `APPSTORE-REQUIRED-REASON-API`, `APPSTORE-PRIVACY-MANIFEST`, `APPSTORE-THIRD-PARTY-SDK`, `APPSTORE-ATS`, `APPSTORE-PURPOSE-STRINGS` |
+
+Each check reports `fail` (severity `blocker`, `warning` or `info`),
+`pass`, `not_determined` (the binary does not settle the question) or
+`not_applicable`, with the evidence read from the file and the official
+page the rule comes from. Store values and their sources live in
+`narvy/store_check/data/`.
+
+It runs offline: no network call, no telemetry event, nothing written to
+disk (the archive is read in memory). It does not check store listing
+metadata, Data safety answers, whether a declared permission use is
+acceptable under Play policy, or SDK signatures.
+
+Exit codes: 0 no blocker (with `--fail-on warning`, no warning either),
+1 at least one blocker (or warning), 3 the file cannot be analysed.
+
 ## Dependency check (SCA)
 
 The dependency check sends package names and versions (never code, file paths or findings) to Narvy's EU-hosted vulnerability database. Set OSV_API_URL to use another OSV-compatible server.
@@ -262,8 +305,8 @@ in the scan's coverage note. Results are cached for 7 days in
 
 ## Telemetry
 
-The CLI sends one small anonymous event per command, so we can see which
-scan types are used and where they fail. It is sent in the background with
+The CLI sends one small anonymous event per command (`store-check` sends
+none), so we can see which scan types are used and where they fail. It is sent in the background with
 a 1 second timeout, is never retried or stored for later, and never fails a
 scan. At most it adds 1 second at exit. A notice is printed the first time it runs.
 

{narvy_cli-1.1.5 → narvy_cli-1.2.0}/README.md

@@ -23,6 +23,11 @@ access or your own existing credentials:
 - `cloud-scan` - AWS account posture check using your own ambient AWS
   credentials
 
+and one check that is not a security scan:
+
+- `store-check` - Google Play and App Store upload requirements for an
+  APK, AAB, split-APK set or IPA, offline (see [Store check](#store-check))
+
 Your code, binaries and findings are never uploaded unless you explicitly
 pass `--upload`. The CLI does send anonymous usage statistics, described
 exactly in [Telemetry](#telemetry), which you can turn off.
@@ -148,6 +153,10 @@ narvy scans
 
 # Scan + upload every .apk/.aab/.apkm/.xapk/.ipa found in a folder, in one command
 narvy upload-all ./my-apps-folder/
+
+# Google Play / App Store upload requirements, offline (not a security scan)
+narvy store-check app-release.aab
+narvy store-check MyApp.ipa --lang fr --json
 ```
 
 Run `narvy doctor` before your first scan to check your Java/jadx/iOS
@@ -204,6 +213,40 @@ exhaust the machine. `NARVY_SEMGREP_JOBS` and `NARVY_SEMGREP_MAX_MEMORY_MB`
 listed in the scan notes. Outside a terminal (CI logs), a progress line is
 printed every 30 seconds; `NARVY_PROGRESS_INTERVAL` changes that (0 = off).
 
+## Store check
+
+`narvy store-check` answers one question: will Google Play or the App Store
+accept this build, and what will they ask about it? It reads the manifest,
+resources, native libraries, Info.plist, Mach-O load commands, imported
+symbols and privacy manifests of the file, and evaluates them against the
+store requirements in force at a date (`--as-of`, default today).
+
+```bash
+narvy store-check app-release.aab
+narvy store-check app.xapk --fail-on warning      # CI gate on warnings too
+narvy store-check MyApp.ipa --json > store.json   # EN and FR messages in one report
+narvy store-check MyApp.ipa --as-of 2027-02-01    # evaluate a future deadline
+```
+
+| Store | Checks |
+|-------|--------|
+| Google Play | `PLAY-TARGET-SDK`, `PLAY-16KB-ELF`, `PLAY-16KB-ZIPALIGN`, `PLAY-EXPORTED`, `PLAY-DEBUGGABLE`, `PLAY-CLEARTEXT`, `PLAY-FGS-TYPE`, `PLAY-FGS-PERMISSION`, `PLAY-FGS-DECLARATION`, `PLAY-PERMISSION-DECLARATION` |
+| App Store | `APPSTORE-SDK-VERSION`, `APPSTORE-MIN-OS`, `APPSTORE-REQUIRED-REASON-API`, `APPSTORE-PRIVACY-MANIFEST`, `APPSTORE-THIRD-PARTY-SDK`, `APPSTORE-ATS`, `APPSTORE-PURPOSE-STRINGS` |
+
+Each check reports `fail` (severity `blocker`, `warning` or `info`),
+`pass`, `not_determined` (the binary does not settle the question) or
+`not_applicable`, with the evidence read from the file and the official
+page the rule comes from. Store values and their sources live in
+`narvy/store_check/data/`.
+
+It runs offline: no network call, no telemetry event, nothing written to
+disk (the archive is read in memory). It does not check store listing
+metadata, Data safety answers, whether a declared permission use is
+acceptable under Play policy, or SDK signatures.
+
+Exit codes: 0 no blocker (with `--fail-on warning`, no warning either),
+1 at least one blocker (or warning), 3 the file cannot be analysed.
+
 ## Dependency check (SCA)
 
 The dependency check sends package names and versions (never code, file paths or findings) to Narvy's EU-hosted vulnerability database. Set OSV_API_URL to use another OSV-compatible server.
@@ -229,8 +272,8 @@ in the scan's coverage note. Results are cached for 7 days in
 
 ## Telemetry
 
-The CLI sends one small anonymous event per command, so we can see which
-scan types are used and where they fail. It is sent in the background with
+The CLI sends one small anonymous event per command (`store-check` sends
+none), so we can see which scan types are used and where they fail. It is sent in the background with
 a 1 second timeout, is never retried or stored for later, and never fails a
 scan. At most it adds 1 second at exit. A notice is printed the first time it runs.
 

{narvy_cli-1.1.5 → narvy_cli-1.2.0}/narvy/__init__.py

@@ -1,3 +1,3 @@
 """Narvy CLI - free, local SAST for Android, iOS and polyglot source."""
 
-__version__ = "1.1.5"
+__version__ = "1.2.0"

{narvy_cli-1.1.5 → narvy_cli-1.2.0}/narvy/main.py

@@ -41,6 +41,7 @@ from . import decompiler as _decompiler
 from .apk_memory_preflight import is_auto as is_auto_mem
 from .rule_engine import load_rules_from_dir, run_rules_on_file
 from . import auth, own_reports, uploader, telemetry
+from . import secret_output
 from .third_party_filter import get_own_package_roots, resolve_file_scope, check_android_override
 from .scope_config import load_scope_config
 from . import semgrep_engine
@@ -63,6 +64,7 @@ from .web.scan_blocklist import check_blocklist, ScanBlocked, REFUSAL_MESSAGE
 from .web.ssrf_guard import validate_url as web_validate_url, SSRFBlocked
 from .host.ssh_exec import HostConn, SSHExecError, _validate_conn
 from .host.audit import audit_host
+from .store_check import cli as store_check_cli
 from .host.report import normalize_host_findings, severity_counts as host_severity_counts
 # cloud/aws_scan.py and its boto3 dependency are imported lazily inside
 # cmd_cloud_scan(): boto3 is an opt-in extra, not a dependency of the whole CLI.
@@ -158,7 +160,7 @@ def _print_raw_tool_output(label, text):
     if not text:
         return
     console.print(f"\n[dim]--- raw {label} output ---[/dim]")
-    console.print(f"[dim]{rich_escape(text)}[/dim]")
+    console.print(f"[dim]{rich_escape(secret_output.sp.mask_text(text))}[/dim]")
     console.print("[dim]--- end raw output ---[/dim]\n")
 
 
@@ -1632,6 +1634,7 @@ def _scan_to_json(all_findings, rules, scan_mode, target_path, encrypted, scan_m
             "recommendation": details.get("recommendation"),
             "cwe": details.get("cwe"),
             "masvs": details.get("masvs"),
+            **secret_output.json_secret_fields(f),
         })
         if f.get("original_severity"):
             out_findings[-1]["original_severity"] = f["original_severity"]
@@ -1847,6 +1850,11 @@ def cmd_scan(args):
         console.print(f"[dim]Ignored Narvy report file(s) from an earlier run: {rich_escape(names)}"
                       f"{f' and {more} more' if more > 0 else ''}.[/dim]")
 
+    # Honest secret wording + masking, once, on the final list: after every
+    # severity decision, before the table, JSON, SARIF and the upload payload.
+    # Narvy never tests a secret; no output (local or uploaded) carries a raw value.
+    secret_output.present_cli_findings(all_findings, target_path, scan_mode)
+
     # Say so when a hybrid repo (RN/Flutter/Capacitor) has code this mode
     # didn't cover, instead of exiting 0 silently.
     uncovered_notes = _uncovered_surface_notes(target_path, scan_mode,
@@ -2398,6 +2406,8 @@ def _web_to_sarif(findings):
         f.get("url", ""),
         f.get("severity"),
     ) for f in findings]
+    for res, f in zip(results, findings):
+        res["properties"].update(secret_output.sarif_secret_properties(f))
     return {
         "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
         "version": "2.1.0",
@@ -2464,6 +2474,8 @@ def cmd_web_scan(args):
         _print_raw_tool_output("nuclei", result.get("stderr"))
 
     findings = result.get("findings", [])
+    # Honest secret wording + masking before any output (same list as result["findings"]).
+    secret_output.present_web_findings(findings)
 
     if args.format == "json":
         output = json.dumps({"tool": "Narvy Web Scanner CLI", **result}, indent=2)
@@ -2718,6 +2730,23 @@ def _cloud_to_sarif(findings):
     }
 
 
+STORE_CHECK_EXIT_CODES_HELP = (
+    "exit codes:\n"
+    "  0  no blocker (with --fail-on warning: no warning either)\n"
+    "  1  at least one blocker (with --fail-on warning: or at least one warning)\n"
+    "  3  the file cannot be analysed (not found, not an APK, AAB, split-APK set\n"
+    "     or IPA, damaged archive) or an option is invalid\n"
+    "  130  interrupted (Ctrl-C, SIGTERM)\n\n"
+    "Offline: no network call, no telemetry, nothing written to disk. Store\n"
+    "requirements are dated; --as-of evaluates them at another date."
+)
+
+
+def cmd_store_check(args, parser):
+    """Store readiness checks (narvy.store_check). Not a security scan, no telemetry."""
+    raise SystemExit(store_check_cli.run(args, parser, input_error_code=EXIT_BAD_TARGET))
+
+
 def cmd_cloud_scan(args):
     telemetry.note(surface="cloud")
     _reject_format_as_file(args.output_file)
@@ -2903,6 +2932,8 @@ def _safe_console_streams():
 
 def cli(prog=None):
     _safe_console_streams()
+    # Mask provider-format tokens, PEM blocks, JWTs and URL passwords in any log record.
+    secret_output.sp.install_log_masking()
     parser =_ArgumentParser(prog=prog, allow_abbrev=False, description=(
         "Narvy CLI - Static Analysis for Android APKs/AABs, iOS IPAs, "
         "Android/iOS source projects, and web/backend source projects "
@@ -3050,6 +3081,13 @@ def cli(prog=None):
     p_cloud.add_argument("--fail-on", choices=["critical", "high", "medium", "low", "any"], help=FAIL_ON_HELP)
     p_cloud.set_defaults(func=cmd_cloud_scan)
 
+    p_store = sub.add_parser(
+        "store-check", allow_abbrev=False, epilog=STORE_CHECK_EXIT_CODES_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        help="Check an APK, AAB, XAPK or IPA against Google Play and App Store upload requirements (offline)")
+    store_check_cli.add_arguments(p_store)
+    p_store.set_defaults(func=lambda a: cmd_store_check(a, p_store))
+
     args = parser.parse_args()
     # SIGTERM/SIGHUP (CI job cancel, docker stop, dropped SSH) take the Ctrl-C path so
     # child scanners (semgrep workers) are torn down instead of orphaned.

{narvy_cli-1.1.5 → narvy_cli-1.2.0}/narvy/reporter.py

@@ -2,6 +2,7 @@ import json
 from typing import List, Dict, Any
 
 from narvy import __version__
+from narvy.secret_output import sarif_secret_properties
 
 # Canonical SARIF severity mapping, shared by every emitter (scan + web/host/cloud).
 # level = SARIF's per-result rank; security-severity = GitHub/GitLab 0-10 code-scanning score.
@@ -57,7 +58,10 @@ def generate_sarif_report(findings: List[Dict[str, Any]], rules: List[Dict[str,
             "ruleId": finding['rule_id'],
             "level": _SARIF_LEVEL.get(_sev, "warning"),
             "message": {
-                "text": finding['details']['description']
+                # A presented secret leads with its honest title ("Potential secret: ...
+                # (format match, not tested)"); every other finding keeps its description.
+                "text": (finding.get('title') if finding.get('secret_presentation')
+                         and finding.get('title') else finding['details']['description'])
             },
             "locations": [{
                 "physicalLocation": {
@@ -78,6 +82,7 @@ def generate_sarif_report(findings: List[Dict[str, Any]], rules: List[Dict[str,
                     "prngContextEvidence": finding['details'].get('prng_context_evidence', '')}
                    if isinstance(finding.get('details'), dict)
                    and finding['details'].get('prng_context') else {}),
+                **sarif_secret_properties(finding),
             }
         })
 

narvy_cli-1.2.0/narvy/secret_output.py

@@ -0,0 +1,232 @@
+"""CLI wiring of narvy/secret_presentation.py (honest secret wording + masking).
+
+narvy/secret_presentation.py is a byte-identical copy of the hosted engine's
+module, so the CLI and the dashboard word and mask a secret the same way.
+This file only adapts the CLI finding shape to it:
+
+* CLI findings keep description/cwe/recommendation in a nested ``details``
+  dict. The hosted ingest (cli_ingest.normalize_finding) lifts them to the top
+  level before fingerprinting, so the same lift happens here first: the
+  classifier then sees what the server sees, and ``fingerprint_mask_basis`` is
+  taken from exactly the inputs the server's fingerprint used before masking
+  existed (no fixed/new churn on the dashboard).
+* CLI findings carry no snippet. To recognise the provider format (and so
+  word "format match" vs "pattern match", and spot public client keys) the
+  matched line is read from disk into a transient ``line_content`` key, used
+  by the classifier and removed again. It never reaches any output.
+* Terminal, JSON and SARIF read ``details``; the honest, masked wording is
+  copied back there. Severity stays upper-case (the CLI convention).
+
+Runs once per scan, after every severity decision (secret_value_grade) and
+before any output or upload.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Iterable, List, Optional
+
+from . import secret_presentation as sp
+
+__all__ = ["present_cli_finding", "present_cli_findings", "present_web_findings",
+           "json_secret_fields", "sarif_secret_properties", "sp"]
+
+_PEM_BEGIN = "PRIVATE KEY-----"
+_PEM_MAX_LINES = 120
+
+# Fields of a presented finding the local JSON report carries.
+JSON_SECRET_FIELDS = (
+    "title", "title_fr", "description_fr", "remediation", "remediation_fr",
+    "severity_rationale", "severity_rationale_fr", "secret_confidence", "secret_tested",
+    "secret_public_by_design", "secret_kind", "secret_match_basis", "original_severity",
+)
+
+
+def _lift(f: Dict[str, Any], key: str, value: Any, added: List[str]) -> None:
+    if value in (None, "", [], {}):
+        return
+    if f.get(key) in (None, "", [], {}):
+        f[key] = value
+        added.append(key)
+
+
+def _resolve(file_path: str, root: Optional[str]) -> Optional[str]:
+    if not file_path:
+        return None
+    if os.path.isabs(file_path):
+        return file_path if os.path.isfile(file_path) else None
+    if root:
+        base = root if os.path.isdir(root) else os.path.dirname(root)
+        p = os.path.join(base, file_path)
+        if os.path.isfile(p):
+            return p
+    return None
+
+
+def _matched_text(f: Dict[str, Any], root: Optional[str],
+                  cache: Dict[str, Optional[List[str]]]) -> Optional[str]:
+    """The finding's source line (a whole PEM block when the line opens one)."""
+    try:
+        line_no = int(f.get("line") or 0)
+    except (TypeError, ValueError):
+        return None
+    path = _resolve(str(f.get("file_path") or ""), root)
+    if not path or line_no <= 0:
+        return None
+    if path not in cache:
+        try:
+            with open(path, "r", encoding="utf-8", errors="ignore") as fh:
+                cache[path] = fh.read().splitlines()
+        except OSError:
+            cache[path] = None
+    lines = cache[path]
+    if not lines or line_no > len(lines):
+        return None
+    text = lines[line_no - 1]
+    if _PEM_BEGIN in text and "BEGIN" in text:
+        block = [text]
+        for nxt in lines[line_no:line_no + _PEM_MAX_LINES]:
+            block.append(nxt)
+            if "END" in nxt and _PEM_BEGIN in nxt:
+                break
+        text = "\n".join(block)
+    return text
+
+
+# CLI scan mode -> the {platform, scan_mode} the hosted engine files the upload
+# under (cli_ingest: binary vs source), so the wording ("app package" vs
+# "source code") and the client-context call match the dashboard's.
+_SCAN_CONTEXT = {
+    "android": {"platform": "android", "scan_mode": "binary"},
+    "android-bundle": {"platform": "android", "scan_mode": "binary"},
+    "ios-binary": {"platform": "ios", "scan_mode": "binary"},
+    "android-source": {"platform": "android", "scan_mode": "source"},
+    "ios-source": {"platform": "ios", "scan_mode": "source"},
+    "web-source": {"platform": "web", "scan_mode": "source"},
+}
+
+
+def scan_context(scan_mode: Optional[str]) -> Optional[Dict[str, str]]:
+    return _SCAN_CONTEXT.get(str(scan_mode or ""))
+
+
+def _present(f: Dict[str, Any], context: Optional[Dict[str, Any]]) -> bool:
+    return sp.present_finding(f, context) if context else sp.present_finding(f)
+
+
+def present_cli_finding(f: Dict[str, Any], root: Optional[str] = None,
+                        cache: Optional[Dict[str, Optional[List[str]]]] = None,
+                        context: Optional[Dict[str, Any]] = None) -> bool:
+    """Reword + mask one CLI finding in place. Returns True when it changed."""
+    if not isinstance(f, dict):
+        return False
+    cache = {} if cache is None else cache
+    details = f.get("details")
+    if isinstance(details, dict):
+        # Rule definitions share one details dict across all their findings
+        # (and with the SARIF rule descriptors): never write into it.
+        details = dict(details)
+        f["details"] = details
+    added: List[str] = []
+    if isinstance(details, dict):
+        _lift(f, "description", details.get("description"), added)
+        _lift(f, "cwe", details.get("cwe"), added)
+    elif isinstance(details, str):
+        _lift(f, "description", details, added)
+
+    transient = False
+    view = dict(f, **{k: v for k, v in (context or {}).items() if not f.get(k)})
+    if sp.is_secret_finding(view) and not f.get("secret_presentation"):
+        b = f.get("fingerprint_mask_basis")
+        if not (isinstance(b, dict) and b.get("scheme") == sp.MASK_BASIS_SCHEME):
+            # Taken before line_content exists: the server never saw that line.
+            f["fingerprint_mask_basis"] = sp.fingerprint_basis_of(f)
+        if "line_content" not in f:
+            text = _matched_text(f, root, cache)
+            if text:
+                f["line_content"] = text
+                transient = True
+    try:
+        changed = _present(f, context)
+    finally:
+        if transient:
+            f.pop("line_content", None)
+
+    if not changed and not f.get("secret_presentation"):
+        for k in added:  # nothing to present: leave the finding as it was
+            f.pop(k, None)
+        return False
+
+    if isinstance(f.get("severity"), str):
+        f["severity"] = f["severity"].upper()
+    if isinstance(f.get("original_severity"), str):
+        f["original_severity"] = f["original_severity"].upper()
+    details = f.get("details")  # present_finding may have replaced it (masked copy)
+    if isinstance(details, dict) and f.get("secret_presentation"):
+        details["description"] = f.get("description") or details.get("description")
+        if isinstance(f.get("remediation"), str):
+            details["recommendation"] = f["remediation"]
+    return True
+
+
+def present_cli_findings(findings: Iterable[Dict[str, Any]], root: Optional[str] = None,
+                         scan_mode: Optional[str] = None) -> int:
+    """present_cli_finding over a scan's final findings. Never raises."""
+    cache: Dict[str, Optional[List[str]]] = {}
+    context = scan_context(scan_mode)
+    n = 0
+    for f in findings or []:
+        try:
+            if present_cli_finding(f, root, cache, context):
+                n += 1
+        except Exception:  # noqa: BLE001 - a presentation error must never lose a finding
+            try:
+                _mask_only(f)
+            except Exception:  # noqa: BLE001
+                pass
+    return n
+
+
+def _mask_only(f: Dict[str, Any]) -> None:
+    """Fallback when wording failed: at least never show a format-matched value."""
+    for k, v in list(f.items()):
+        if isinstance(v, str) and k not in ("file_path", "rule_id", "severity"):
+            f[k] = sp.mask_text(v)
+        elif isinstance(v, dict):
+            f[k] = {kk: sp.mask_text(vv) if isinstance(vv, str) else vv for kk, vv in v.items()}
+
+
+def present_web_findings(findings: Iterable[Dict[str, Any]]) -> int:
+    """web-scan findings: everything nuclei sees was served to browsers, so a
+    public-by-design key there is client context (same as the hosted web scanner)."""
+    n = 0
+    for f in findings or []:
+        if not isinstance(f, dict):
+            continue
+        try:
+            f.setdefault("secret_client_context", True)
+            if sp.present_finding(f):
+                n += 1
+        except Exception:  # noqa: BLE001
+            try:
+                _mask_only(f)
+            except Exception:  # noqa: BLE001
+                pass
+    return n
+
+
+def json_secret_fields(f: Dict[str, Any]) -> Dict[str, Any]:
+    """Extra keys for the local JSON report (never secret_sha256 or basis internals)."""
+    if not f.get("secret_presentation"):
+        return {}
+    return {k: f[k] for k in JSON_SECRET_FIELDS if k in f}
+
+
+def sarif_secret_properties(f: Dict[str, Any]) -> Dict[str, Any]:
+    if not f.get("secret_presentation"):
+        return {}
+    out: Dict[str, Any] = {"secret_tested": False}
+    for k in ("secret_confidence", "secret_public_by_design", "secret_kind",
+              "secret_match_basis", "original_severity"):
+        if f.get(k) not in (None, ""):
+            out[k] = f[k]
+    return out