libidentifier 0.2.0rc1__py3-none-any.whl

libidentifier/profiles/schema.py

@@ -0,0 +1,137 @@
+"""SQLite schema and compatibility validation."""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+
+from ..config import FINGERPRINT_ALGORITHM, DATABASE_SCHEMA_VERSION
+from ..errors import ProfileError
+from ..purl import reference_coordinates
+
+DDL = """
+CREATE TABLE IF NOT EXISTS db_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS library_family (
+  family_id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  ecosystem TEXT,
+  package_name TEXT
+);
+CREATE TABLE IF NOT EXISTS library_release (
+  release_id TEXT PRIMARY KEY,
+  family_id TEXT NOT NULL REFERENCES library_family(family_id),
+  version TEXT NOT NULL,
+  purl TEXT NOT NULL,
+  fingerprint_algorithm TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS reference_artifact (
+  artifact_id TEXT PRIMARY KEY,
+  release_id TEXT NOT NULL REFERENCES library_release(release_id),
+  sha256 TEXT NOT NULL,
+  format TEXT NOT NULL,
+  provenance_json TEXT NOT NULL,
+  UNIQUE(release_id,sha256)
+);
+CREATE TABLE IF NOT EXISTS build_variant (
+  variant_id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL REFERENCES reference_artifact(artifact_id),
+  output_sha256 TEXT NOT NULL,
+  configuration_json TEXT NOT NULL,
+  is_primary INTEGER NOT NULL CHECK(is_primary IN (0,1))
+);
+CREATE TABLE IF NOT EXISTS fingerprint (
+  fingerprint_id TEXT PRIMARY KEY,
+  algorithm TEXT NOT NULL,
+  digest TEXT NOT NULL,
+  UNIQUE(algorithm,digest)
+);
+CREATE TABLE IF NOT EXISTS fingerprint_occurrence (
+  variant_id TEXT NOT NULL REFERENCES build_variant(variant_id),
+  fingerprint_id TEXT NOT NULL REFERENCES fingerprint(fingerprint_id),
+  locator TEXT NOT NULL,
+  multiplicity INTEGER NOT NULL CHECK(multiplicity>0),
+  PRIMARY KEY(variant_id,fingerprint_id,locator)
+);
+CREATE INDEX IF NOT EXISTS idx_fingerprint_digest ON fingerprint(digest);
+CREATE INDEX IF NOT EXISTS idx_occurrence_fingerprint ON fingerprint_occurrence(fingerprint_id);
+CREATE INDEX IF NOT EXISTS idx_artifact_release ON reference_artifact(release_id);
+CREATE VIEW IF NOT EXISTS dex_class AS
+  SELECT a.release_id, f.digest, o.locator AS descriptor, o.multiplicity
+  FROM fingerprint_occurrence o JOIN fingerprint f USING(fingerprint_id)
+  JOIN build_variant v USING(variant_id) JOIN reference_artifact a USING(artifact_id)
+  WHERE f.algorithm='dex-shape-v2' AND v.is_primary=1;
+CREATE VIEW IF NOT EXISTS dex_shape AS
+  SELECT release_id,digest,SUM(multiplicity) AS multiplicity FROM dex_class
+  GROUP BY release_id,digest;
+CREATE TABLE IF NOT EXISTS elf_identity (
+  release_id TEXT NOT NULL REFERENCES library_release(release_id),
+  abi TEXT NOT NULL,
+  sha256 TEXT NOT NULL,
+  build_id TEXT,
+  soname TEXT,
+  symbol_digest TEXT,
+  PRIMARY KEY (release_id, abi, sha256)
+);
+CREATE INDEX IF NOT EXISTS idx_elf_sha256 ON elf_identity(sha256);
+CREATE TABLE IF NOT EXISTS published_metadata (
+  release_id TEXT NOT NULL REFERENCES library_release(release_id),
+  source_sha256 TEXT NOT NULL,
+  body_json TEXT NOT NULL,
+  PRIMARY KEY(release_id,source_sha256)
+);
+"""
+
+
+def initialize(conn: sqlite3.Connection) -> None:
+    if conn.execute("SELECT 1 FROM sqlite_master WHERE name='db_meta'").fetchone():
+        version = conn.execute("SELECT value FROM db_meta WHERE key='schema_version'").fetchone()
+        if not version or version[0] != str(DATABASE_SCHEMA_VERSION):
+            raise ProfileError('profile database schema is incompatible; rebuild with profiles rebuild')
+    conn.executescript(DDL)
+    meta = {
+        "schema_version": str(DATABASE_SCHEMA_VERSION),
+        "fingerprint_algorithm": FINGERPRINT_ALGORITHM,
+        "database_id": "local",
+        "generated_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+    }
+    for key, value in meta.items():
+        conn.execute("INSERT OR IGNORE INTO db_meta(key, value) VALUES (?, ?)", (key, value))
+
+
+def validate(conn: sqlite3.Connection) -> None:
+    rows = dict(conn.execute("SELECT key, value FROM db_meta"))
+    if rows.get("schema_version") != str(DATABASE_SCHEMA_VERSION):
+        raise ProfileError("profile database schema version is incompatible; rebuild with profiles rebuild")
+    if rows.get("fingerprint_algorithm") != FINGERPRINT_ALGORITHM:
+        raise ProfileError("profile database fingerprint algorithm is incompatible")
+    required = {
+        "db_meta",
+        "library_family",
+        "library_release",
+        "dex_shape",
+        "dex_class",
+        "elf_identity",
+        "reference_artifact", "build_variant", "fingerprint", "fingerprint_occurrence", "published_metadata",
+    }
+    actual = {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type IN ('table','view')")}
+    missing = required - actual
+    if missing:
+        raise ProfileError(f"profile database is missing tables: {', '.join(sorted(missing))}")
+    incompatible = conn.execute(
+        "SELECT COUNT(*) FROM library_release WHERE fingerprint_algorithm != ?",
+        (FINGERPRINT_ALGORITHM,),
+    ).fetchone()[0]
+    if incompatible:
+        raise ProfileError("profile database contains incompatible release fingerprints; rebuild it")
+    for purl, version, name, namespace in conn.execute(
+        "SELECT r.purl, r.version, f.name, f.package_name FROM library_release r JOIN library_family f USING(family_id)"
+    ):
+        try:
+            _, expected_namespace, expected_name, expected_version, _ = reference_coordinates(purl)
+        except ValueError as exc:
+            raise ProfileError(f"profile database has an invalid reference PURL: {exc}") from exc
+        if (version, name, namespace) != (expected_version, expected_name, expected_namespace):
+            raise ProfileError("profile database identity disagrees with reference PURL; rebuild it")

libidentifier/profiles/store.py

@@ -0,0 +1,212 @@
+"""Transactional profile storage and read-only matching index queries."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from collections import Counter
+from pathlib import Path
+from urllib.parse import quote
+
+from ..config import FINGERPRINT_ALGORITHM
+from ..errors import ProfileError
+from ..models import ProfileDatabaseRecord
+from ..purl import reference_coordinates
+from .schema import initialize, validate
+
+
+def sha256_file(path: str | Path) -> str:
+    h = hashlib.sha256()
+    with Path(path).open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def connect_write(path: str | Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(Path(path))
+    try:
+        conn.execute("PRAGMA foreign_keys=ON")
+        initialize(conn)
+        validate(conn)
+        return conn
+    except Exception:
+        conn.close()
+        raise
+
+
+def connect_readonly(path: str | Path) -> sqlite3.Connection:
+    p = Path(path)
+    if not p.is_file():
+        raise ProfileError(f"profile database does not exist or is not a file: {p}")
+    uri = f"file:{quote(str(p.resolve()).replace(chr(92), '/'))}?mode=ro"
+    conn = None
+    try:
+        conn = sqlite3.connect(uri, uri=True)
+        validate(conn)
+        return conn
+    except (sqlite3.Error, ProfileError) as exc:
+        if conn is not None:
+            conn.close()
+        raise ProfileError(f"cannot use profile database {p}: {exc}") from exc
+
+
+def database_record(path: str | Path | None) -> ProfileDatabaseRecord:
+    if path is None:
+        return ProfileDatabaseRecord()
+    p = Path(path)
+    conn = connect_readonly(p)
+    try:
+        rows = dict(conn.execute("SELECT key, value FROM db_meta"))
+        count = conn.execute("SELECT COUNT(*) FROM library_release").fetchone()[0]
+    except sqlite3.Error as exc:
+        raise ProfileError(f"cannot read profile database metadata {p}: {exc}") from exc
+    finally:
+        conn.close()
+    try:
+        digest = sha256_file(p)
+    except OSError as exc:
+        raise ProfileError(f"cannot read profile database {p}: {exc}") from exc
+    return ProfileDatabaseRecord(
+        id=rows.get("database_id"),
+        version=rows.get("schema_version"),
+        sha256=digest,
+        generated_at=rows.get("generated_at"),
+        profile_count=int(count),
+    )
+
+
+def family_id_from_purl(purl: str) -> tuple[str, str, str | None, str]:
+    ecosystem, package_name, name, version, _ = reference_coordinates(purl)
+    family_id = hashlib.sha256(f"{ecosystem}:{package_name or ''}:{name}".encode()).hexdigest()[:16]
+    return family_id, name, package_name, version
+
+
+def release_id(family_id: str, version: str, source_sha256: str) -> str:
+    # Kept as an internal call shape; release identity no longer depends on bytes.
+    return hashlib.sha256(f"{family_id}:{version}".encode()).hexdigest()[:24]
+
+
+def upsert_release(
+    conn: sqlite3.Connection,
+    *,
+    purl: str,
+    source_sha256: str,
+    source_format: str,
+    provenance: dict,
+    dex_shapes: Counter[str] | None = None,
+    dex_classes: Counter[tuple[str, str]] | None = None,
+    elf_identity: dict | None = None,
+    build_configuration: dict | None = None,
+    output_sha256: str | None = None,
+    published_metadata: dict | None = None,
+) -> tuple[str, str, str]:
+    family_id, name, package_name, version = family_id_from_purl(purl)
+    rid = release_id(family_id, version, source_sha256)
+    ecosystem = "Maven" if purl.startswith("pkg:maven/") else (purl[4:].split("/", 1)[0] if purl.startswith("pkg:") else None)
+    with conn:
+        conn.execute(
+            "INSERT OR IGNORE INTO library_family(family_id, name, ecosystem, package_name) VALUES (?, ?, ?, ?)",
+            (family_id, name, ecosystem, package_name),
+        )
+        conn.execute(
+            """
+            INSERT OR IGNORE INTO library_release(
+              release_id, family_id, version, purl, fingerprint_algorithm
+            ) VALUES (?, ?, ?, ?, ?)
+            """,
+            (
+                rid,
+                family_id,
+                version,
+                purl,
+                FINGERPRINT_ALGORITHM,
+            ),
+        )
+        aid = hashlib.sha256(f'{rid}:{source_sha256}'.encode()).hexdigest()[:24]
+        configuration = json.dumps(build_configuration or {'kind': 'original'}, sort_keys=True, separators=(',', ':'))
+        output_sha = output_sha256 or source_sha256
+        vid = hashlib.sha256(f'{aid}:{output_sha}:{configuration}'.encode()).hexdigest()[:24]
+        primary = not conn.execute("SELECT 1 FROM build_variant v JOIN reference_artifact a USING(artifact_id) WHERE a.release_id=? AND v.is_primary=1 AND ((a.format='elf')=?)", (rid, int(source_format == 'elf'))).fetchone()
+        conn.execute('INSERT OR IGNORE INTO reference_artifact VALUES (?,?,?,?,?)',
+                     (aid, rid, source_sha256, source_format, json.dumps(provenance, sort_keys=True)))
+        conn.execute('INSERT OR IGNORE INTO build_variant VALUES (?,?,?,?,?)', (vid, aid, output_sha, configuration, int(primary)))
+        occurrences = dex_classes or Counter({(d, ''): n for d, n in (dex_shapes or {}).items()})
+        for (digest, descriptor), count in sorted(occurrences.items()):
+            fid = hashlib.sha256(f'dex-shape-v2:{digest}'.encode()).hexdigest()
+            conn.execute('INSERT OR IGNORE INTO fingerprint VALUES (?,?,?)', (fid, 'dex-shape-v2', digest))
+            conn.execute('INSERT OR REPLACE INTO fingerprint_occurrence VALUES (?,?,?,?)', (vid, fid, descriptor, count))
+        if published_metadata is not None:
+            conn.execute('INSERT OR REPLACE INTO published_metadata VALUES (?,?,?)',
+                         (rid, published_metadata['sha256'], json.dumps(published_metadata, sort_keys=True)))
+        if elf_identity:
+            fid = hashlib.sha256(f"elf-identity-v1:{elf_identity['sha256']}".encode()).hexdigest()
+            conn.execute('INSERT OR IGNORE INTO fingerprint VALUES (?,?,?)', (fid, 'elf-identity-v1', elf_identity['sha256']))
+            conn.execute('INSERT OR IGNORE INTO fingerprint_occurrence VALUES (?,?,?,1)', (vid, fid, elf_identity['abi']))
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO elf_identity(release_id, abi, sha256, build_id, soname, symbol_digest)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    rid,
+                    elf_identity["abi"],
+                    elf_identity["sha256"],
+                    elf_identity.get("build_id"),
+                    elf_identity.get("soname"),
+                    elf_identity.get("symbol_digest"),
+                ),
+            )
+        conn.execute(
+            "INSERT OR REPLACE INTO db_meta(key, value) VALUES ('generated_at', datetime('now'))"
+        )
+    return rid, family_id, version
+
+
+def dex_class_rows(conn: sqlite3.Connection, release_id: str, digests: set[str]) -> dict[str, Counter[str]]:
+    if not digests:
+        return {}
+    placeholders = ",".join("?" for _ in digests)
+    rows: dict[str, Counter[str]] = {}
+    for digest, descriptor, multiplicity in conn.execute(
+        f"""
+        SELECT digest, descriptor, multiplicity
+        FROM dex_class
+        WHERE release_id=? AND digest IN ({placeholders})
+        """,
+        (release_id, *tuple(sorted(digests))),
+    ):
+        rows.setdefault(digest, Counter())[descriptor] += int(multiplicity)
+    return rows
+
+
+def release_rows(conn: sqlite3.Connection, release_ids: set[str]) -> dict[str, dict]:
+    if not release_ids:
+        return {}
+    placeholders = ",".join("?" for _ in release_ids)
+    rows = {}
+    for row in conn.execute(
+        f"""
+        SELECT r.release_id, r.family_id, r.version, r.purl,
+               (SELECT sha256 FROM reference_artifact WHERE release_id=r.release_id ORDER BY artifact_id LIMIT 1),
+               (SELECT format FROM reference_artifact WHERE release_id=r.release_id ORDER BY artifact_id LIMIT 1),
+               f.name, f.ecosystem, f.package_name
+        FROM library_release r JOIN library_family f USING(family_id)
+        WHERE r.release_id IN ({placeholders})
+        """,
+        tuple(sorted(release_ids)),
+    ):
+        rows[row[0]] = {
+            "release_id": row[0],
+            "family_id": row[1],
+            "version": row[2],
+            "purl": row[3],
+            "source_sha256": row[4],
+            "source_format": row[5],
+            "name": row[6],
+            "ecosystem": row[7],
+            "package_name": row[8],
+            "source_hashes": [x[0] for x in conn.execute('SELECT sha256 FROM reference_artifact WHERE release_id=?', (row[0],))],
+        }
+    return rows

libidentifier/purl.py

@@ -0,0 +1,36 @@
+"""Small PURL coordinate reader for trusted reference identities.
+
+This does not resolve packages or validate ecosystem-specific release names.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import unquote
+
+
+def reference_coordinates(purl: str) -> tuple[str, str | None, str, str, str]:
+    """Return type, namespace, name, decoded version and versionless PURL."""
+    if not isinstance(purl, str) or not purl.startswith("pkg:"):
+        raise ValueError("reference PURL must start with pkg:")
+    if re.search(r"\s|%(?![0-9a-fA-F]{2})", purl):
+        raise ValueError("reference PURL has invalid escaping or whitespace")
+    coordinate = re.split(r"[?#]", purl, maxsplit=1)[0]
+    suffix = purl[len(coordinate):]
+    if coordinate.count("@") != 1:
+        raise ValueError("reference PURL must include one explicit version")
+    base, encoded_version = coordinate.rsplit("@", 1)
+    parts = base[4:].split("/")
+    if len(parts) < 2 or not re.fullmatch(r"[a-z][a-z0-9.+-]*", parts[0]):
+        raise ValueError("reference PURL has invalid package type")
+    decoded = [unquote(part, errors="strict") for part in parts[1:]]
+    version = unquote(encoded_version, errors="strict")
+    if not version or any(not part or part in {".", ".."} or "/" in part for part in decoded):
+        raise ValueError("reference PURL needs a package name and non-empty version")
+    if parts[0] == "maven" and len(decoded) != 2:
+        raise ValueError("Maven PURL must include group and artifact")
+    return parts[0], "/".join(decoded[:-1]) or None, decoded[-1], version, base + suffix
+
+
+def family_purl(purl: str) -> str:
+    return reference_coordinates(purl)[4]

libidentifier/relationships.py

@@ -0,0 +1,168 @@
+"""Evidence-backed structural/call relationships and component aggregation."""
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import replace
+import json
+from urllib.parse import quote
+
+from .extractors.instructions import decode_invocations
+from .grouping import locator_key, stable_id, group_unknown
+from .models import (AnalysisRun, Producer, EvidenceRecord, EntityRef, Relationship,
+                     OwnershipAssertion, AnalysisError)
+from .purl import family_purl
+
+PRODUCER = Producer('dex-relationships', '1')
+
+
+def enrich(result, inv, options, conn=None):
+    """Run once against the complete internal inventory, before output capping."""
+    evidence, edges, runs = list(result.evidence_records), [], list(result.analysis_runs)
+    definitions = defaultdict(list)
+    methods = defaultdict(list)
+    for cls in inv.dex_classes:
+        definitions[cls.descriptor].append(cls.locator)
+        for method in cls.methods:
+            if method.descriptor:
+                methods[method.descriptor].append(replace(cls.locator, method_descriptor=method.descriptor))
+    assertions = inv.ownership_assertions or [OwnershipAssertion(cls.locator,
+        'ambiguous' if len(definitions[cls.descriptor]) > 1 else 'unattributed', []) for cls in inv.dex_classes]
+    resolved_assertions = []
+    for assertion in assertions:
+        ids = []
+        if assertion.component_ids:
+            eid = stable_id('evidence', ['ownership', assertion.to_dict()])
+            evidence.append(EvidenceRecord(eid, 'component_match', Producer('component-matcher', '2'),
+                assertion.location, details={'component_ids': assertion.component_ids, 'status': assertion.status},
+                provenance={'profile_database_sha256': result.profile_database.sha256}, limitations=assertion.limitations))
+            ids.append(eid)
+        resolved_assertions.append(replace(assertion, evidence_ids=ids))
+    incomplete = inv.coverage.dex == 'partial'
+    runs.append(AnalysisRun('ownership', 'not_requested' if conn is None else ('partial' if incomplete or any(a.status == 'ambiguous' for a in assertions) else 'complete'),
+        Producer('component-matcher', '2'), {'definitions': len(assertions), 'ambiguous': sum(a.status == 'ambiguous' for a in assertions)},
+        ['Ownership is a supported attribution, not proof of original authorship']))
+
+    def entity(kind, descriptor, locations):
+        location = locations[0] if len(locations) == 1 else None
+        identity = [kind, locator_key(location), descriptor] if location else [kind, descriptor, 'ambiguous' if locations else 'external']
+        return EntityRef(kind, stable_id(kind, identity), location)
+
+    def emit(kind, source, target, location, details, qualifiers=None):
+        eid = stable_id('evidence', [kind, location.to_dict(), details])
+        evidence.append(EvidenceRecord(eid, kind, PRODUCER, location, details))
+        rid = stable_id('relationship', [kind, source.id, target.id, eid])
+        edges.append(Relationship(rid, kind, source, target, [eid], PRODUCER,
+            qualifiers=qualifiers or {}, limitations=['Static reference does not establish runtime execution']))
+
+    structural_count = 0
+    calls_examined = calls_skipped = 0
+    call_errors = []
+    if options.extract_relationships:
+        for cls in inv.dex_classes:
+            source = entity('class', cls.descriptor, [cls.locator])
+            refs = [('inheritance', cls.superclass, cls.locator, {'role': 'superclass'})]
+            refs += [('interface_implementation', desc, cls.locator, {'role': 'interface'}) for desc in cls.interfaces]
+            refs += [('class_reference', f.type_descriptor, cls.locator, {'role': 'field_type', 'field': f.name}) for f in cls.fields]
+            for method in cls.methods:
+                loc = replace(cls.locator, method_descriptor=method.descriptor)
+                refs.append(('class_reference', method.return_type, loc, {'role': 'return_type'}))
+                refs += [('class_reference', desc, loc, {'role': 'parameter_type', 'parameter_index': i}) for i,desc in enumerate(method.parameter_types)]
+            for kind, desc, loc, details in refs:
+                if not desc or not desc.lstrip('[').startswith('L'):
+                    continue
+                target_desc = desc.lstrip('[')
+                target = entity('class', target_desc, definitions.get(target_desc, []))
+                emit(kind, source, target, loc, {**details, 'target_descriptor': target_desc},
+                     {'target_resolution': 'unique' if target.location else ('ambiguous' if definitions.get(target_desc) else 'external')})
+                structural_count += 1
+    runs.append(AnalysisRun('relationships.structural', ('partial' if incomplete else 'complete') if options.extract_relationships else 'not_requested',
+        PRODUCER, {'relationships': structural_count}, ['Only declaration/signature type references are extracted']))
+
+    if options.extract_calls:
+        for cls in inv.dex_classes:
+            tables = inv.dex_tables.get((cls.locator.container, cls.locator.member))
+            for method in cls.methods:
+                if method.code_offset is None:
+                    continue
+                calls_examined += 1
+                loc = replace(cls.locator, method_descriptor=method.descriptor)
+                if tables is None:
+                    calls_skipped += 1
+                    call_errors.append(AnalysisError('call_tables_missing', loc.member, 'Method reference tables unavailable'))
+                    continue
+                calls, issues = decode_invocations(method.bytecode, method_count=len(tables.methods), dex_version=int(tables.data[4:7]))
+                if issues:
+                    calls_skipped += 1
+                    call_errors.extend(AnalysisError('call_extraction_partial', loc.member,
+                        f'{method.descriptor}: {issue}') for issue in issues)
+                source = entity('method', method.descriptor, [loc])
+                for offset, kind, index in calls:
+                    target_desc = tables.method_descriptor(index)
+                    target = entity('method', target_desc, methods.get(target_desc, []))
+                    emit('static_call_reference', source, target,
+                        replace(loc, byte_offset=method.code_offset + offset),
+                        {'declared_target': target_desc, 'instruction_byte_offset': offset, 'method_index': index},
+                        {'invocation_kind': kind, 'target_resolution': 'unique' if target.location else ('ambiguous' if methods.get(target_desc) else 'external')})
+    runs.append(AnalysisRun('relationships.calls', ('partial' if incomplete or call_errors else 'complete') if options.extract_calls else 'not_requested',
+        PRODUCER, {'methods_examined': calls_examined, 'methods_partial': calls_skipped},
+        ['Declared ordinary invocation targets only; no runtime dispatch or reachability'], call_errors))
+
+    ownership = {locator_key(a.location): a.component_ids[0] for a in resolved_assertions if a.status == 'attributed' and len(a.component_ids) == 1}
+    aggregates = defaultdict(list)
+    for edge in edges:
+        if edge.source.location and edge.target.location:
+            src, dst = ownership.get(locator_key(edge.source.location)), ownership.get(locator_key(edge.target.location))
+            if src and dst and src != dst:
+                aggregates[(edge.type, src, dst)].append(edge)
+    for (kind, src, dst), supporting in sorted(aggregates.items()):
+        edges.append(Relationship(stable_id('relationship', [kind, src, dst]), kind,
+            EntityRef('component', src), EntityRef('component', dst),
+            sorted({eid for edge in supporting for eid in edge.evidence_ids}), PRODUCER,
+            strength='attributed', supporting_relationship_ids=sorted(e.id for e in supporting),
+            limitations=['Component edge depends on code ownership; does not prove build introduction or runtime execution']))
+    runs.append(AnalysisRun('relationships.components', 'not_requested' if conn is None or not (options.extract_relationships or options.extract_calls) else ('partial' if incomplete or any(a.status == 'ambiguous' for a in assertions) or call_errors else 'complete'),
+        PRODUCER, {'relationships': len(aggregates)}, ['Only uniquely attributed embedded endpoints are aggregated']))
+
+    published_count, missing_metadata = 0, 0
+    if conn is not None and options.extract_relationships:
+        metadata_rows = list(conn.execute('SELECT r.purl,m.body_json FROM published_metadata m JOIN library_release r USING(release_id) ORDER BY r.purl,m.source_sha256'))
+        for component in result.components:
+            supported = {v for v,details in component.score_details.get('version_candidate_scores',{}).items() if details.get('supported')}
+            versions = {component.version} if component.version else supported | set(component.version_candidates)
+            selected = [(purl, json.loads(body)) for purl,body in metadata_rows
+                        if family_purl(purl) == component.family_purl and purl_version(purl) in versions]
+            if not selected:
+                missing_metadata += 1
+            for purl, metadata in selected:
+                if metadata['status'] != 'complete':
+                    missing_metadata += 1
+                for index, declaration in enumerate(metadata['declarations']):
+                    values = declaration['interpreted']
+                    target_purl = ('pkg:maven/' + quote(values['groupId'], safe='.') + '/' + quote(values['artifactId'], safe='')
+                                   if values['groupId'] and values['artifactId'] else None)
+                    eid = stable_id('evidence', [purl, metadata['sha256'], index])
+                    evidence.append(EvidenceRecord(eid, 'pom_declaration', Producer('pom-direct', '1'),
+                        details=declaration, provenance={'source':metadata['source'], 'sha256':metadata['sha256'], 'release_purl':purl}, limitations=metadata['limitations']))
+                    edges.append(Relationship(stable_id('relationship', [component.component_id, eid]), 'published_dependency',
+                        EntityRef('reference_release', purl, purl=purl), EntityRef('package', target_purl or stable_id('unresolved', declaration), purl=target_purl),
+                        [eid], Producer('pom-direct','1'), strength='declared',
+                        qualifiers={'component_id':component.component_id, 'release_association':'exact' if component.version else 'candidate', **declaration},
+                        limitations=['Published reference declaration does not prove APK dependency inclusion or selected version']))
+                    published_count += 1
+    runs.append(AnalysisRun('relationships.published', 'not_requested' if conn is None or not options.extract_relationships else ('partial' if missing_metadata else 'complete'),
+        Producer('pom-direct','1'), {'declarations':published_count, 'incomplete_components':missing_metadata},
+        ['Only supplied reference metadata is evaluated; candidate release declarations are conditional']))
+
+    assigned = {locator_key(a.location) for a in resolved_assertions if a.status == 'attributed'}
+    unknown = [c.locator for c in inv.dex_classes if locator_key(c.locator) not in assigned]
+    clusters = group_unknown(inv.dex_classes, unknown, edges) if options.group_unknown_classes else []
+    runs.append(AnalysisRun('grouping', ('partial' if incomplete else 'complete') if options.group_unknown_classes else 'not_requested',
+        Producer('namespace-structural','1'), {'classes_total':len(unknown), 'classes_emitted':sum(c.class_count for c in clusters), 'clusters':len(clusters)},
+        ['Grouping covers successfully extracted unmatched definitions only']))
+    return replace(result, ownership_assertions=resolved_assertions, evidence_records=sorted({e.id:e for e in evidence}.values(),key=lambda e:e.id),
+        relationships=sorted(edges,key=lambda e:e.id), analysis_runs=runs, unattributed_clusters=clusters)
+
+
+def purl_version(purl):
+    from .purl import reference_coordinates
+    return reference_coordinates(purl)[3]

libidentifier/sbom.py

@@ -0,0 +1,62 @@
+"""CycloneDX 1.5 JSON export for exact, high-confidence components."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .models import ScanResult
+from .purl import reference_coordinates
+
+
+def export_cyclonedx(result: ScanResult, path) -> None:
+    components = []
+    excluded = []
+    for component in result.components:
+        if not component.purl or not component.version:
+            excluded.append({"component_id": component.component_id, "reason": "exact version or PURL unavailable"})
+            continue
+        if component.identity_confidence != "high" or component.version_confidence != "high":
+            excluded.append({"component_id": component.component_id, "reason": "identity and version confidence must both be high"})
+            continue
+        try:
+            _, _, name, version, _ = reference_coordinates(component.purl)
+        except ValueError:
+            excluded.append({"component_id": component.component_id, "reason": "invalid reference PURL"})
+            continue
+        if version != component.version or name != component.name:
+            excluded.append({"component_id": component.component_id, "reason": "PURL disagrees with component identity/version"})
+            continue
+        components.append(
+            {
+                "type": "library",
+                "bom-ref": component.component_id,
+                "name": component.name,
+                "version": component.version,
+                "purl": component.purl,
+                "properties": [{"name": "libidentifier:matched_code", "value": json.dumps(
+                    [loc.to_dict() for loc in component.matched_code], sort_keys=True, separators=(",", ":"))}],
+            }
+        )
+    bom = {
+        "bomFormat": "CycloneDX",
+        "specVersion": "1.5",
+        "version": 1,
+        "metadata": {
+            "tools": [{"name": result.tool_name, "version": result.tool_version}],
+            "properties": [
+                {"name": "libidentifier:inventory_scope", "value": "Only high-confidence exact-version matches; not a complete software inventory"},
+                {"name": "libidentifier:input", "value": json.dumps(result.input.to_dict(), sort_keys=True)},
+                {"name": "libidentifier:profile_database", "value": json.dumps(result.profile_database.to_dict(), sort_keys=True)},
+                {"name": "libidentifier:fingerprint_algorithm", "value": result.fingerprint_algorithm},
+                {"name": "libidentifier:scan_schema_version", "value": str(result.schema_version)},
+                {"name": "libidentifier:excluded_components", "value": json.dumps(excluded, sort_keys=True)},
+                {"name": "libidentifier:coverage", "value": json.dumps(result.coverage.to_dict(), sort_keys=True)},
+                {"name": "libidentifier:errors", "value": json.dumps([e.to_dict() for e in result.errors], sort_keys=True)},
+            ],
+        },
+        "compositions": [{"aggregate": "incomplete"}],
+        "components": sorted(components, key=lambda c: c["bom-ref"]),
+    }
+    Path(path).write_text(json.dumps(bom, sort_keys=True, separators=(",", ":")) + "\n", encoding="utf-8")
+