libidentifier 0.2.0rc1__py3-none-any.whl

libidentifier/__init__.py

@@ -0,0 +1,36 @@
+"""Public API for LibIdentifier."""
+
+from .api import build_profile, export_cyclonedx, identify, inspect, correlate, scan
+from .vulnerabilities.models import AssessmentResult, VulnerabilityOptions, VulnerabilityReport
+from .vulnerabilities.database import provision_advisory_database, update_advisory_database, validate_advisory_database
+from .config import IdentifyOptions
+from .models import ProfileBuildResult, ScanResult
+from .models import (Producer, AnalysisRun, EvidenceRecord, EntityRef, OwnershipAssertion,
+                     Relationship, UnattributedCluster)
+from .version import __version__
+from .profiles.distribution import install_profiles, package_profiles, validate_profiles
+
+__all__ = [
+    "install_profiles",
+    "package_profiles",
+    "validate_profiles",
+    "IdentifyOptions",
+    "ProfileBuildResult",
+    "ScanResult",
+    "build_profile",
+    "export_cyclonedx",
+    "identify",
+    "inspect",
+    "correlate",
+    "scan",
+    "AssessmentResult",
+    "VulnerabilityOptions",
+    "VulnerabilityReport",
+    "provision_advisory_database",
+    "update_advisory_database",
+    "validate_advisory_database",
+    "Producer", "AnalysisRun", "EvidenceRecord", "EntityRef", "OwnershipAssertion",
+    "Relationship", "UnattributedCluster",
+]
+
+

libidentifier/api.py

@@ -0,0 +1,90 @@
+"""Python API entry points."""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import replace
+from pathlib import Path
+
+from .config import FINGERPRINT_ALGORITHM, SCHEMA_VERSION, IdentifyOptions
+from .errors import ProfileError
+from .inventory import empty_scan_result, inspect_path
+from .matcher import match_inventory
+from .models import ScanResult
+from .profiles.builder import build_profile
+from .profiles.store import connect_readonly, database_record
+from .sbom import export_cyclonedx
+from .version import __version__
+from .vulnerabilities.models import AssessmentResult, VulnerabilityOptions, VulnerabilityReport
+
+
+def _result_coverage(coverage, *, total: int, emitted: int, identification: str):
+    limitations = list(coverage.limitations)
+    limitations.append("Identification is limited to supplied reference profiles; no matches does not mean no third-party code")
+    if identification == "not_performed":
+        limitations.append("Library matching was not performed (inspect has no reference database)")
+    elif identification == "no_profiles":
+        limitations.append("The reference database contains no profiles")
+    if emitted < total:
+        limitations.append(f"Unknown class output truncated: emitted {emitted} of {total} unmatched definitions")
+    return replace(coverage, library_identification=identification,
+                   unknown_classes_total=total, unknown_classes_emitted=emitted,
+                   unknown_classes_truncated=emitted < total, limitations=limitations)
+
+
+def inspect(path, *, options: IdentifyOptions | None = None) -> ScanResult:
+    opts = options or IdentifyOptions()
+    inv = inspect_path(Path(path), opts)
+    result = empty_scan_result(inv, __version__)
+    from .relationships import enrich
+    from .extractors.version_metadata import apply_version_metadata
+    result = enrich(apply_version_metadata(result, inv), inv, opts)
+    unknown = result.unknown_classes if opts.max_emitted_unknown_classes is None else result.unknown_classes[:opts.max_emitted_unknown_classes]
+    return replace(result, unknown_classes=unknown,
+        coverage=_result_coverage(result.coverage, total=len(inv.dex_classes), emitted=len(unknown), identification="not_performed"))
+
+
+def identify(path, *, profiles, options: IdentifyOptions | None = None) -> ScanResult:
+    opts = options or IdentifyOptions()
+    inv = inspect_path(Path(path), opts)
+    conn = connect_readonly(profiles)
+    try:
+        components, hints, unknown = match_inventory(conn, inv, opts)
+        database = database_record(profiles)
+        result = ScanResult(
+            schema_version=SCHEMA_VERSION, tool_name="libidentifier", tool_version=__version__,
+            fingerprint_algorithm=FINGERPRINT_ALGORITHM, profile_database=database,
+            input=inv.input,
+            analyzed_files=sorted(inv.analyzed_files, key=lambda a: (a.member or "", a.sha256)),
+            frameworks_detected=inv.frameworks_detected, components=components,
+            class_ownership_hints=hints, unknown_classes=unknown, coverage=inv.coverage, errors=inv.errors)
+        from .extractors.version_metadata import apply_version_metadata
+        from .relationships import enrich
+        result = enrich(apply_version_metadata(result, inv), inv, opts, conn)
+    except sqlite3.Error as exc:
+        raise ProfileError(f"cannot query profile database: {exc}") from exc
+    finally:
+        conn.close()
+    emitted = unknown if opts.max_emitted_unknown_classes is None else unknown[:opts.max_emitted_unknown_classes]
+    return replace(result, unknown_classes=emitted,
+        coverage=_result_coverage(inv.coverage, total=len(unknown), emitted=len(emitted),
+                                  identification="limited" if database.profile_count else "no_profiles"))
+
+
+
+def correlate(result: ScanResult, *, options: VulnerabilityOptions) -> VulnerabilityReport:
+    """Assess an existing inventory using explicitly configured local OSV data."""
+    from .vulnerabilities.correlate import correlate as assess
+    return assess(result, options=options)
+
+
+def scan(path, *, profiles, options: IdentifyOptions | None = None,
+         vulnerabilities: VulnerabilityOptions | None = None) -> AssessmentResult:
+    """Identify, then optionally assess; never provision or download dependencies."""
+    from .vulnerabilities.models import AssessmentResult, VulnerabilityReport
+    result = identify(path, profiles=profiles, options=options)
+    report = correlate(result, options=vulnerabilities) if vulnerabilities is not None else VulnerabilityReport(
+        "not_requested", result.input, result.tool_version, result.profile_database,
+        limitations=["Vulnerability assessment was not requested"],
+        identification_coverage=result.coverage, identification_errors=result.errors)
+    return AssessmentResult(result, report)

libidentifier/archive.py

@@ -0,0 +1,133 @@
+"""Bounded ZIP/APK traversal for untrusted archives."""
+
+from __future__ import annotations
+
+import hashlib
+import posixpath
+import stat
+import zipfile
+import zlib
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from .config import IdentifyOptions
+from .detect import detect_bytes
+from .models import AnalysisError
+
+
+@dataclass(frozen=True)
+class ArchiveMember:
+    name: str
+    format: str
+    data: bytes
+    sha256: str
+
+
+def _safe_member_name(name: str) -> bool:
+    if "\x00" in name or "\\" in name:
+        return False
+    if name.startswith("/") or name.startswith("//"):
+        return False
+    if len(name) >= 2 and name[1] == ":":
+        return False
+    if ".." in PurePosixPath(name).parts:
+        return False
+    normalized = posixpath.normpath(name)
+    if normalized == "." or normalized.startswith("../") or normalized == "..":
+        return False
+    parts = PurePosixPath(normalized).parts
+    return ".." not in parts
+
+
+def _is_symlink(info: zipfile.ZipInfo) -> bool:
+    mode = (info.external_attr >> 16) & 0o170000
+    return mode == stat.S_IFLNK
+
+
+def _interesting_by_path(name: str) -> bool:
+    from .extractors.metadata import ASSETS
+
+    lowered = name.lower()
+    base = PurePosixPath(lowered).name
+    return (
+        (base.startswith("classes") and base.endswith(".dex"))
+        or (lowered.startswith("lib/") and lowered.endswith(".so"))
+        or lowered.endswith("/pom.properties")
+        or lowered == "androidmanifest.xml"
+        or base in {"libflutter.so", "libapp.so"}
+        or any(name in paths for paths in ASSETS.values())
+    )
+
+
+def read_selected_members(path, options: IdentifyOptions) -> tuple[list[ArchiveMember], list[AnalysisError]]:
+    errors: list[AnalysisError] = []
+    members: list[ArchiveMember] = []
+    total = 0
+    with zipfile.ZipFile(path) as zf:
+        infos = sorted(zf.infolist(), key=lambda i: i.filename)
+        if len(infos) > options.max_archive_members:
+            raise ValueError("archive has too many members")
+        occurrences = Counter(info.filename for info in infos)
+        duplicates_reported = set()
+        for info in infos:
+            name = info.filename
+            if info.is_dir():
+                continue
+            if occurrences[name] > 1:
+                if name not in duplicates_reported:
+                    errors.append(AnalysisError("duplicate_member", name, "Duplicate ZIP member names cannot be located unambiguously; skipped"))
+                    duplicates_reported.add(name)
+                continue
+            if not _safe_member_name(name):
+                errors.append(AnalysisError("unsafe_member_path", name, "ZIP member path is unsafe", "warning"))
+                continue
+            if _is_symlink(info):
+                errors.append(AnalysisError("unsupported_member", name, "ZIP symlink member skipped", "warning"))
+                continue
+            if info.flag_bits & 0x1:
+                errors.append(AnalysisError("encrypted_member", name, "Encrypted ZIP member skipped", "warning"))
+                continue
+            if info.compress_type not in {zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED}:
+                errors.append(AnalysisError("unsupported_compression", name, "Unsupported ZIP compression skipped", "warning"))
+                continue
+            if info.file_size > options.max_member_uncompressed_bytes:
+                errors.append(AnalysisError("member_too_large", name, "ZIP member exceeds size limit", "warning"))
+                continue
+            if info.compress_size and info.file_size / max(info.compress_size, 1) > options.max_compression_ratio:
+                errors.append(AnalysisError("compression_ratio", name, "ZIP member compression ratio exceeds limit", "warning"))
+                continue
+
+            selected = _interesting_by_path(name)
+            remaining = options.max_total_selected_uncompressed_bytes - total
+            try:
+                with zf.open(info) as fh:
+                    head = fh.read(8)
+                    fmt = detect_bytes(head, name=name)
+                    selected = selected or fmt in {"dex", "elf"}
+                    if not selected:
+                        continue
+                    if info.file_size > remaining:
+                        errors.append(AnalysisError("archive_budget", name, "Selected archive members exceed total byte limit"))
+                        break
+                    limit = min(options.max_member_uncompressed_bytes, remaining)
+                    rest = fh.read(max(0, limit + 1 - len(head)))
+                data = head + rest
+            except (OSError, RuntimeError, zipfile.BadZipFile, zlib.error) as exc:
+                errors.append(AnalysisError("member_read_error", name, str(exc), "error"))
+                continue
+            if len(data) > options.max_member_uncompressed_bytes:
+                errors.append(AnalysisError("member_too_large", name, "ZIP member exceeds size limit", "warning"))
+                continue
+            total += len(data)
+            if total > options.max_total_selected_uncompressed_bytes:
+                errors.append(AnalysisError("archive_budget", name, "Selected archive members exceed total byte limit", "warning"))
+                break
+            fmt = detect_bytes(data, name=name)
+            if fmt == "unknown" and (name.lower().endswith(".dex") or name.lower().endswith(".so")):
+                errors.append(AnalysisError("member_read_error", name, "Selected binary has invalid magic", "error"))
+                continue
+            if fmt in {"unknown", "zip"} and name.lower().endswith("/pom.properties"):
+                fmt = "metadata"
+            members.append(ArchiveMember(name=name, format=fmt, data=data, sha256=hashlib.sha256(data).hexdigest()))
+    return members, errors

libidentifier/cli.py

@@ -0,0 +1,340 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .api import identify, inspect, scan, correlate
+from .vulnerabilities.models import AssessmentResult
+from .vulnerabilities.setup import prepare_options
+from .vulnerabilities.correlate import unavailable_report
+from .vulnerabilities.database import provision_advisory_database, update_advisory_database, validate_advisory_database
+from .errors import AdvisoryError, InputError, LibIdentifierError, ProfileError
+from .models import ScanResult
+from .config import IdentifyOptions
+from .serialization import write_stream
+from .table import write_table
+from .profiles.builder import build_profile, validate_database
+from .profiles.catalog import load_catalog
+from .profiles.fetcher import fetch_catalog, rebuild_database
+from .profiles.distribution import DEFAULT_ENGINE_REQUIREMENT, DEFAULT_PROFILE_MANIFEST, install_profiles, package_profiles
+from .sbom import export_cyclonedx
+from .version import __version__
+
+
+def _write_result(result: ScanResult, args) -> None:
+    if args.format == "json":
+        if args.output:
+            result.write_json(args.output)
+        else:
+            write_stream(result, sys.stdout)
+    else:
+        write_table(result)
+
+
+def _identify_options(args):
+    return IdentifyOptions(max_emitted_unknown_classes=args.max_unknown_classes,
+        extract_relationships=not args.no_relationships, extract_calls=not args.no_calls,
+        group_unknown_classes=not args.no_grouping)
+
+
+def _cmd_inspect(args) -> int:
+    result = inspect(args.path, options=_identify_options(args))
+    _write_result(result, args)
+    return 4 if any(e.severity == "error" for e in result.errors) else 0
+
+
+def _cmd_identify(args) -> int:
+    profiles = args.profiles or os.environ.get("LIBIDENTIFIER_PROFILES")
+    if not profiles:
+        raise ProfileError(
+            "no profile database specified; pass --profiles, set LIBIDENTIFIER_PROFILES, "
+            "or build one with 'libidentifier profiles rebuild'"
+        )
+    result = identify(args.path, profiles=profiles, options=_identify_options(args))
+    if args.vulnerabilities:
+        assessment = AssessmentResult(result, _assess(result, args))
+        _write_assessment(assessment, args)
+        return _assessment_exit(assessment)
+    _write_result(result, args)
+    return 4 if any(e.severity == "error" for e in result.errors) else 0
+
+
+def _cmd_profiles_build(args) -> int:
+    built = build_profile(
+        args.path,
+        purl=args.purl,
+        database=args.database,
+        d8=args.d8,
+        android_jar=args.android_jar,
+        reference_sha256=args.sha256,
+    )
+    sys.stdout.write(json.dumps(built.to_dict(), sort_keys=True, separators=(",", ":")) + "\n")
+    return 0
+
+
+def _cmd_profiles_package(args) -> int:
+    manifest = package_profiles(args.database, output_dir=args.output_dir,
+        snapshot_version=args.snapshot_version, source_revision=args.source_revision,
+        requires_engine=args.requires_engine)
+    sys.stdout.write(json.dumps(manifest, indent=2) + "\n")
+    return 0
+
+
+def _cmd_profiles_install(args) -> int:
+    manifest = install_profiles(args.manifest, database=args.database, offline=args.offline,
+        replace=args.replace, manifest_sha256=args.manifest_sha256,
+        timeout_seconds=args.timeout_seconds)
+    sys.stdout.write(json.dumps(manifest, indent=2) + "\n")
+    return 0
+
+
+def _cmd_profiles_validate(args) -> int:
+    validate_database(args.database)
+    sys.stdout.write("profile database is valid\n")
+    return 0
+
+
+def _cmd_profiles_fetch(args) -> int:
+    catalog = load_catalog(args.catalog)
+    rows = fetch_catalog(catalog, args.cache, offline=args.offline)
+    sys.stdout.write(json.dumps(rows, sort_keys=True, separators=(",", ":")) + "\n")
+    return 0
+
+
+def _cmd_profiles_rebuild(args) -> int:
+    rows = rebuild_database(
+        args.catalog,
+        cache_dir=args.cache,
+        database=args.database,
+        d8=args.d8,
+        android_jar=args.android_jar,
+        offline=args.offline,
+    )
+    sys.stdout.write(json.dumps(rows, sort_keys=True, separators=(",", ":")) + "\n")
+    return 0
+
+
+def _cmd_sbom(args) -> int:
+    data = json.loads(Path(args.input).read_text(encoding="utf-8"))
+    export_cyclonedx(ScanResult.from_dict(data), args.output)
+    return 0
+
+
+def _assess(result, args):
+    try:
+        if error := getattr(args, "_setup_error", None):
+            raise error
+        report = correlate(result, options=prepare_options(args))
+    except (AdvisoryError, OSError) as exc:
+        report = unavailable_report(result, exc)
+    if report.errors:
+        issue = report.errors[0]
+        download = (' Download OSV-Scanner v2 from https://github.com/google/osv-scanner/releases.'
+                    if issue.code == 'scanner_missing' else '')
+        print(f"libidentifier: warning: advisories not fully assessed ({issue.code}): {issue.message}{download}", file=sys.stderr)
+    return report
+
+
+def _write_assessment(result, args):
+    if args.format == "json":
+        if args.output:
+            result.write_json(args.output)
+        else:
+            write_stream(result, sys.stdout)
+    else:
+        inventory = result.identification if hasattr(result, 'identification') else None
+        report = result.vulnerabilities if inventory is not None else result
+        if args.output:
+            with Path(args.output).open("w", encoding="utf-8") as stream:
+                write_table(inventory, report, stream=stream)
+        else:
+            write_table(inventory, report)
+
+
+def _assessment_exit(result):
+    report = result.vulnerabilities if hasattr(result, "identification") else result
+    if any(e.severity == "error" for e in report.identification_errors):
+        return 4
+    if report.errors and all(e.code == 'scanner_missing' for e in report.errors):
+        return 0  # Identification completed; assessment is explicitly unavailable.
+    if report.status in {"blocked", "failed"}:
+        return 3
+    if report.errors or any(e.severity == "error" for e in report.identification_errors):
+        return 4
+    return 0
+
+
+def _cmd_scan(args):
+    profiles = args.profiles or os.environ.get("LIBIDENTIFIER_PROFILES")
+    managed = not profiles
+    if args.format is None:
+        args.format = "table" if managed and not args.output else "json"
+    if not profiles:
+        from .cli_setup import prepare_managed_scan
+        profiles = prepare_managed_scan(args)
+    if args.vulnerabilities:
+        identification = identify(args.path, profiles=profiles,
+            options=_identify_options(args))
+        result = AssessmentResult(identification, _assess(identification, args))
+    else:
+        result = scan(args.path, profiles=profiles,
+            options=_identify_options(args))
+    _write_assessment(result, args)
+    return _assessment_exit(result)
+
+
+def _cmd_correlate(args):
+    try:
+        result = ScanResult.from_dict(json.loads(Path(args.input).read_text(encoding="utf-8")))
+    except (KeyError, TypeError, ValueError) as exc:
+        raise InputError(f"invalid identification JSON: {exc}") from exc
+    report = _assess(result, args)
+    _write_assessment(report, args)
+    return _assessment_exit(report)
+
+
+def _cmd_advisories(args):
+    if args.advisory_command == "provision":
+        record = provision_advisory_database(args.database, archives={args.ecosystem: args.archive}, fetched_at=args.fetched_at)
+    elif args.advisory_command == "update":
+        record = update_advisory_database(args.database, ecosystems=[args.ecosystem])
+    else:
+        record = validate_advisory_database(args.database, max_age_days=args.max_database_age_days)
+    sys.stdout.write(record.to_json() + "\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="libidentifier")
+    parser.add_argument("--version", action="version", version=f"libidentifier {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inspect_p = sub.add_parser("inspect")
+    inspect_p.add_argument("path")
+    inspect_p.add_argument("--format", choices=["json", "table"], default="json")
+    inspect_p.add_argument("--output")
+    inspect_p.add_argument("--max-unknown-classes", type=int, default=None)
+    inspect_p.set_defaults(func=_cmd_inspect)
+
+    identify_p = sub.add_parser("identify")
+    identify_p.add_argument("path")
+    identify_p.add_argument("--profiles")
+    identify_p.add_argument("--format", choices=["json", "table"], default="json")
+    identify_p.add_argument("--output")
+    identify_p.add_argument("--max-unknown-classes", type=int, default=None)
+    identify_p.add_argument("--vulnerabilities", "--vulns", action="store_true")
+    identify_p.set_defaults(func=_cmd_identify)
+
+    profiles_p = sub.add_parser("profiles")
+    profiles_sub = profiles_p.add_subparsers(dest="profiles_command", required=True)
+    package_p = profiles_sub.add_parser("package", help="prepare portable profile release assets")
+    package_p.add_argument("--database", required=True)
+    package_p.add_argument("--output-dir", required=True)
+    package_p.add_argument("--snapshot-version", required=True)
+    package_p.add_argument("--source-revision", required=True)
+    package_p.add_argument("--requires-engine", default=DEFAULT_ENGINE_REQUIREMENT)
+    package_p.set_defaults(func=_cmd_profiles_package)
+    install_p = profiles_sub.add_parser("install", help="explicitly install a local or HTTPS profile release")
+    install_p.add_argument("--manifest", default=DEFAULT_PROFILE_MANIFEST)
+    install_p.add_argument("--database", required=True)
+    install_p.add_argument("--offline", action="store_true")
+    install_p.add_argument("--replace", action="store_true")
+    install_p.add_argument("--manifest-sha256")
+    install_p.add_argument("--timeout-seconds", type=float, default=60)
+    install_p.set_defaults(func=_cmd_profiles_install)
+    build_p = profiles_sub.add_parser("build")
+    build_p.add_argument("path")
+    build_p.add_argument("--purl", required=True)
+    build_p.add_argument("--database", required=True)
+    build_p.add_argument("--d8")
+    build_p.add_argument("--android-jar")
+    build_p.add_argument("--sha256")
+    build_p.set_defaults(func=_cmd_profiles_build)
+    validate_p = profiles_sub.add_parser("validate")
+    validate_p.add_argument("database")
+    validate_p.set_defaults(func=_cmd_profiles_validate)
+    fetch_p = profiles_sub.add_parser("fetch")
+    fetch_p.add_argument("--catalog", default="catalog/references.json")
+    fetch_p.add_argument("--cache", default="reference-artifacts")
+    fetch_p.add_argument("--offline", action="store_true")
+    fetch_p.set_defaults(func=_cmd_profiles_fetch)
+    rebuild_p = profiles_sub.add_parser("rebuild")
+    rebuild_p.add_argument("--catalog", default="catalog/references.json")
+    rebuild_p.add_argument("--cache", default="reference-artifacts")
+    rebuild_p.add_argument("--database", required=True)
+    rebuild_p.add_argument("--d8")
+    rebuild_p.add_argument("--android-jar")
+    rebuild_p.add_argument("--offline", action="store_true")
+    rebuild_p.set_defaults(func=_cmd_profiles_rebuild)
+
+    sbom_p = sub.add_parser("sbom")
+    sbom_p.add_argument("input")
+    sbom_p.add_argument("--output", required=True)
+    sbom_p.set_defaults(func=_cmd_sbom)
+
+    scan_p = sub.add_parser("scan")
+    scan_p.add_argument("path")
+    scan_p.add_argument("--profiles")
+    scan_p.add_argument("--vulnerabilities", "--vulns", action="store_true")
+    scan_p.add_argument("--yes", action="store_true", help="authorize first-run managed resource downloads without prompting")
+    scan_p.add_argument("--max-unknown-classes", type=int, default=None)
+    scan_p.set_defaults(func=_cmd_scan)
+    correlate_p = sub.add_parser("correlate")
+    correlate_p.add_argument("input")
+    correlate_p.set_defaults(func=_cmd_correlate)
+    for command in (inspect_p, identify_p, scan_p):
+        command.add_argument('--no-relationships', action='store_true', help='skip structural and published relationships')
+        command.add_argument('--no-calls', action='store_true', help='skip explicit invocation extraction')
+        command.add_argument('--no-grouping', action='store_true', help='skip unattributed clustering')
+    for command in (scan_p, correlate_p, identify_p):
+        if command is not identify_p:
+            command.add_argument("--format", choices=["json", "table"], default=None if command is scan_p else "json")
+            command.add_argument("--output")
+        command.add_argument("--osv-scanner")
+        command.add_argument("--osv-scanner-sha256", help="optional SHA-256 pin for the selected executable")
+        command.add_argument("--osv-db")
+        command.add_argument("--offline", action="store_true", help="prohibit all setup downloads (assessment always runs offline)")
+        command.add_argument("--osv-timeout", type=float, default=60)
+        command.add_argument("--max-database-age-days", type=float, default=30)
+        command.add_argument("--no-potential", action="store_true")
+        command.add_argument("--max-potential", type=int, default=100)
+        command.add_argument("--min-identity-score", type=float, default=0.75,
+                             help="minimum component score for advisory attribution (0 to 1; default: 0.75)")
+    advisories = sub.add_parser("vulnerabilities")
+    actions = advisories.add_subparsers(dest="advisory_command", required=True)
+    for name in ("provision", "update", "validate"):
+        action = actions.add_parser(name)
+        action.add_argument("--database", required=True)
+        if name != "validate":
+            action.add_argument("--ecosystem", choices=["Maven"], default="Maven")
+        if name == "provision":
+            action.add_argument("--archive", required=True)
+            action.add_argument("--fetched-at")
+        if name == "validate":
+            action.add_argument("--max-database-age-days", type=float, default=30)
+        action.set_defaults(func=_cmd_advisories)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # JSON and table output must preserve non-ASCII descriptors on Windows,
+    # including when stdout is a pipe rather than an interactive terminal.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (InputError, ProfileError, LibIdentifierError, OSError, ValueError) as exc:
+        print(f"libidentifier: {exc}", file=sys.stderr)
+        return 2 if isinstance(exc, InputError) else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

libidentifier/cli_resources.py

@@ -0,0 +1,36 @@
+"""Project-qualified managed scanner builds, independent of GitHub's latest tag."""
+from dataclasses import dataclass
+import platform
+
+from .errors import AdvisoryError
+
+
+@dataclass(frozen=True)
+class ScannerRelease:
+    version: str
+    filename: str
+    sha256: str
+
+    @property
+    def url(self):
+        return f"https://github.com/google/osv-scanner/releases/download/v{self.version}/{self.filename}"
+
+
+# Publisher release SHA-256 values qualified by the project's native CI matrix.
+SUPPORTED_SCANNERS = {
+    ("Windows", "amd64"): ScannerRelease("2.7.0", "osv-scanner_windows_amd64.exe",
+        "9964ed64ec9a387391eb4cc006ad5c531154821aef29b793e02c448de4686438"),
+    ("Linux", "amd64"): ScannerRelease("2.7.0", "osv-scanner_linux_amd64",
+        "160c6253e2922e9e0a6a9771c5c4c40a4b3c6090b34a3cdd5e80c96cc2e4218b"),
+}
+
+
+def supported_scanner(system=None, machine=None):
+    system, machine = system or platform.system(), (machine or platform.machine()).lower()
+    architecture = "amd64" if machine in {"amd64", "x86_64"} else machine
+    try:
+        return SUPPORTED_SCANNERS[(system, architecture)]
+    except KeyError as error:
+        raise AdvisoryError(f"No project-qualified automatic OSV installation for {system}/{machine}; "
+                            "use an explicitly configured compatible native scanner",
+                            code="scanner_platform_unsupported") from error