libidentifier 0.2.0rc1__tar.gz

libidentifier-0.2.0rc1/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.2.0rc1 — Stage 2 preview (publication pending)
+
+- Complete PyPI/GitHub source installation routes, Windows activation-free
+  commands, result interpretation, managed-path updates and user troubleshooting.
+  README/PyPI links lead to installation/usage before the advanced API reference.
+
+- Managed `scan app.apk` first-run setup with one consent prompt, `--yes`, strict
+  `--offline`, project-pinned scanner downloads and persistent per-user resources.
+- `--vulns` alias, table default for managed scans, preserved explicit-profile
+  JSON defaults and download-free analysis APIs; optional failures retain inventory.
+
+- Explicit profile packaging/acquisition APIs and CLI, portable release manifests,
+  hashes, engine compatibility, bounded downloads/decompression, SQLite integrity
+  checks and atomic install with explicit replacement. Analysis remains offline.
+- Single-source package version, PyPI metadata, wheel/sdist content checks,
+  Trusted Publishing workflow and maintainer publication instructions.
+
+- Release-first roadmap: preview package and small schema-2 profile distribution
+  before catalog expansion and Stage 3 accuracy qualification.
+- Removed obsolete generated validation output and schema-1 sample databases;
+  retained selected dated evidence under `docs/development/validation/`.
+- Canonical DEX implementation now uses `fingerprint/dex_v2.py`; optional local
+  qualification resources use ignored `.local/` and `.tools/` directories.
+
+- Canonical DEX descriptors/interfaces and location-aware ownership uncertainty.
+- Additive evidence, analysis status, unattributed clusters and typed structural,
+  ordinary invocation, published-dependency and component relationship models.
+- Internal reference schema 2 separates releases, artifacts, variants, fingerprints
+  and occurrences; canonical fingerprints require an explicit profile rebuild.
+- Direct POM/local-property interpretation and attributable embedded Maven metadata.
+- Contributor documentation, preserved historical specification, contract fixtures,
+  platform CI and a benchmark harness. Existing OSV provisioning/discovery/offline
+  execution and compact table behavior are preserved.
+- CI validates regular package installations and retains per-environment runtime,
+  scanner and JUnit evidence, including skip reasons.
+
+## 0.1.0
+
+- Initial Stage 1 implementation with APK/DEX/ELF inspection, DEX shape fingerprints, ELF identity fingerprints, SQLite profile building, offline matching, JSON output, CLI commands, and CycloneDX export for exact high-confidence versions.
+

libidentifier-0.2.0rc1/LICENSE

@@ -0,0 +1,62 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of, the Work.
+
+"Contribution" shall mean any work of authorship that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work. If You institute patent litigation against any entity alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet these conditions: You must give recipients a copy of this License; modified files must carry prominent notices stating that You changed the files; and You must retain copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding notices that do not pertain to any part of the Derivative Works. If the Work includes a NOTICE file, Derivative Works that You distribute must include a readable copy of applicable attribution notices.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License.
+
+6. Trademarks.
+
+This License does not grant permission to use trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort, contract, or otherwise, unless required by applicable law or agreed to in writing, shall any Contributor be liable to You for damages arising as a result of this License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to offer support, warranty, indemnity, or other liability obligations. In accepting such obligations, You act only on Your own behalf and on Your sole responsibility.
+
+END OF TERMS AND CONDITIONS
+

libidentifier-0.2.0rc1/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE THIRD_PARTY_NOTICES.md CHANGELOG.md
+recursive-include docs *.md *.json
+recursive-exclude docs __pycache__ *integration-moraine* *moraine-integration*
+recursive-include catalog *.json
+recursive-include benchmarks *.py *.json
+recursive-include tests *.py *.json
+recursive-include tools *.py
+prune .local
+prune .tools
+prune .development-deps
+prune .release-venv
+prune samples
+prune test-results
+prune build
+exclude moraine-integration.md

libidentifier-0.2.0rc1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: libidentifier
+Version: 0.2.0rc1
+Summary: Offline identification of compiled Android and native libraries from local fingerprints
+Author: LibIdentifier authors
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/ernestomgz/libidentifier
+Project-URL: Documentation, https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md
+Project-URL: Installation, https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md
+Project-URL: API reference, https://github.com/ernestomgz/libidentifier/blob/main/docs/integration.md
+Project-URL: Issues, https://github.com/ernestomgz/libidentifier/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: lief==0.17.1
+Requires-Dist: packaging>=24
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Dynamic: license-file
+
+# LibIdentifier
+
+Identify known libraries and frameworks in Android APKs, DEX and native ELF files.
+LibIdentifier is an independent Python package and CLI. Analysis runs locally;
+your APK is never uploaded. Optional OSV assessment uses a local advisory database
+and does not establish reachability or exploitability.
+
+**Preview:** the initial official profile catalog covers six library families and
+eight releases. No match does not mean no third-party code. See
+[limitations](https://github.com/ernestomgz/libidentifier/blob/main/docs/limitations.md). The PyPI route requires a published package, and managed
+library scans require published profiles. Check [installation availability](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md#before-you-start)
+or use the source route and profile-free inspection below.
+
+## Install from PyPI or GitHub
+
+Python 3.12 is recommended. New to Python environments? Follow the complete
+[Windows/Linux installation guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md), including the
+activation-free Windows option.
+
+**Released package from PyPI** (after publication), in your Python environment:
+
+```powershell
+python -m pip install "libidentifier==0.2.0rc1"
+```
+
+**Reviewed source from GitHub**, in your Python environment:
+
+```powershell
+git clone https://github.com/ernestomgz/libidentifier.git
+cd libidentifier
+python -m pip install .
+```
+
+Both methods provide the same command. Check the installation, then scan your
+own APK (replace the example path):
+
+```powershell
+libidentifier --version
+libidentifier scan "app.apk" --vulns
+```
+
+The source route installs the code before PyPI publication, but automatic library
+scans still require the official profiles to be available. Until then,
+`libidentifier inspect "app.apk" --format table` works without profiles; see
+[installation verification](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md#verify-without-profiles).
+
+`--vulnerabilities` is the long spelling of `--vulns`. For library identification
+without advisory assessment:
+
+```powershell
+libidentifier scan app.apk
+```
+
+On first use, the CLI lists missing resources, shows their destination and asks
+`Download and set up these resources? [y/N]`. Accept to install the official
+profiles and, when requested, the project-qualified OSV-Scanner and Maven advisory
+data. Later scans reuse them. Existing resources are never silently updated.
+Without vulnerability assessment, only profiles are needed.
+
+Managed scans print the compact table. Setup messages go to stderr. Windows
+resources live under `%LOCALAPPDATA%/LibIdentifier`; Linux uses
+`${XDG_CACHE_HOME:-~/.cache}/libidentifier`. `LIBIDENTIFIER_HOME` overrides the
+managed root. Automatic scanner installation currently supports Windows/Linux
+x64 and uses project-pinned URLs and SHA-256 values, never GitHub's latest tag.
+
+## Useful options
+
+```powershell
+# Authorize missing-resource setup in scripts; never prompts.
+libidentifier scan app.apk --vulns --yes
+
+# Reuse installed resources without any downloads.
+libidentifier scan app.apk --vulns --offline
+
+# JSON instead of a table; --output alone also selects JSON in managed mode.
+libidentifier scan app.apk --vulns --output results.json
+
+# Existing explicit usage retains its JSON default and resource overrides.
+libidentifier scan app.apk --profiles custom.sqlite --format json --output results.json
+libidentifier identify app.apk --profiles custom.sqlite --format table
+```
+
+A noninteractive first run needs `--yes` or preinstalled resources. `--offline`
+overrides `--yes`. If optional vulnerability setup fails, identification is
+preserved with an explicit unassessed result. Required profile failures stop the
+scan. Continue with [first scan, result meanings, advanced options and resource updates](https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md).
+
+## Python API
+
+Use a local database you explicitly provisioned; the managed CLI cache is not
+automatically copied to your working directory. See the
+[complete API setup example](https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md#use-the-python-api).
+
+```python
+from pathlib import Path
+from libidentifier import identify
+
+result = identify(Path("app.apk"), profiles=Path("profiles.sqlite"))
+result.write_json(Path("libraries.json"))
+```
+
+Analysis APIs never prompt, install tools or download data. Explicit maintenance
+APIs are available for consumers that manage their own setup. The authoritative
+[API/JSON guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/integration.md) documents models, coverage, errors, SBOM,
+profile provisioning and offline advisory assessment. Structural matching normally
+identifies families; exact installed versions require stronger evidence.
+
+## Documentation and development
+
+| I want to… | Read |
+|---|---|
+| Install from pip, GitHub or a source ZIP | [Installation](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md) |
+| Scan, save output, use offline mode or repair setup | [Usage guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md) |
+| Integrate the Python API or consume JSON | [Public contract](https://github.com/ernestomgz/libidentifier/blob/main/docs/integration.md) |
+| Build my own reference catalog | [Profile database](https://github.com/ernestomgz/libidentifier/blob/main/docs/profile-database.md) |
+| Publish/update official releases | [Maintainer release guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/releases.md) |
+
+Python 3.11+; `lief==0.17.1`. To use a reviewed checkout before publication:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Tests generate synthetic DEX/APK/ELF fixtures. JAR/AAR **profile generation** needs
+local D8; ordinary scans do not need Java or the Android SDK. See the
+[developer index](https://github.com/ernestomgz/libidentifier/blob/main/docs/development/README.md), [release checklist](https://github.com/ernestomgz/libidentifier/blob/main/docs/development/release-readiness.md),
+[Stage 2 acceptance](https://github.com/ernestomgz/libidentifier/blob/main/docs/development/stages/stage-2.md) and [contributor instructions](https://github.com/ernestomgz/libidentifier/blob/main/AGENTS.md).

libidentifier-0.2.0rc1/README.md

@@ -0,0 +1,127 @@
+# LibIdentifier
+
+Identify known libraries and frameworks in Android APKs, DEX and native ELF files.
+LibIdentifier is an independent Python package and CLI. Analysis runs locally;
+your APK is never uploaded. Optional OSV assessment uses a local advisory database
+and does not establish reachability or exploitability.
+
+**Preview:** the initial official profile catalog covers six library families and
+eight releases. No match does not mean no third-party code. See
+[limitations](https://github.com/ernestomgz/libidentifier/blob/main/docs/limitations.md). The PyPI route requires a published package, and managed
+library scans require published profiles. Check [installation availability](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md#before-you-start)
+or use the source route and profile-free inspection below.
+
+## Install from PyPI or GitHub
+
+Python 3.12 is recommended. New to Python environments? Follow the complete
+[Windows/Linux installation guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md), including the
+activation-free Windows option.
+
+**Released package from PyPI** (after publication), in your Python environment:
+
+```powershell
+python -m pip install "libidentifier==0.2.0rc1"
+```
+
+**Reviewed source from GitHub**, in your Python environment:
+
+```powershell
+git clone https://github.com/ernestomgz/libidentifier.git
+cd libidentifier
+python -m pip install .
+```
+
+Both methods provide the same command. Check the installation, then scan your
+own APK (replace the example path):
+
+```powershell
+libidentifier --version
+libidentifier scan "app.apk" --vulns
+```
+
+The source route installs the code before PyPI publication, but automatic library
+scans still require the official profiles to be available. Until then,
+`libidentifier inspect "app.apk" --format table` works without profiles; see
+[installation verification](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md#verify-without-profiles).
+
+`--vulnerabilities` is the long spelling of `--vulns`. For library identification
+without advisory assessment:
+
+```powershell
+libidentifier scan app.apk
+```
+
+On first use, the CLI lists missing resources, shows their destination and asks
+`Download and set up these resources? [y/N]`. Accept to install the official
+profiles and, when requested, the project-qualified OSV-Scanner and Maven advisory
+data. Later scans reuse them. Existing resources are never silently updated.
+Without vulnerability assessment, only profiles are needed.
+
+Managed scans print the compact table. Setup messages go to stderr. Windows
+resources live under `%LOCALAPPDATA%/LibIdentifier`; Linux uses
+`${XDG_CACHE_HOME:-~/.cache}/libidentifier`. `LIBIDENTIFIER_HOME` overrides the
+managed root. Automatic scanner installation currently supports Windows/Linux
+x64 and uses project-pinned URLs and SHA-256 values, never GitHub's latest tag.
+
+## Useful options
+
+```powershell
+# Authorize missing-resource setup in scripts; never prompts.
+libidentifier scan app.apk --vulns --yes
+
+# Reuse installed resources without any downloads.
+libidentifier scan app.apk --vulns --offline
+
+# JSON instead of a table; --output alone also selects JSON in managed mode.
+libidentifier scan app.apk --vulns --output results.json
+
+# Existing explicit usage retains its JSON default and resource overrides.
+libidentifier scan app.apk --profiles custom.sqlite --format json --output results.json
+libidentifier identify app.apk --profiles custom.sqlite --format table
+```
+
+A noninteractive first run needs `--yes` or preinstalled resources. `--offline`
+overrides `--yes`. If optional vulnerability setup fails, identification is
+preserved with an explicit unassessed result. Required profile failures stop the
+scan. Continue with [first scan, result meanings, advanced options and resource updates](https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md).
+
+## Python API
+
+Use a local database you explicitly provisioned; the managed CLI cache is not
+automatically copied to your working directory. See the
+[complete API setup example](https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md#use-the-python-api).
+
+```python
+from pathlib import Path
+from libidentifier import identify
+
+result = identify(Path("app.apk"), profiles=Path("profiles.sqlite"))
+result.write_json(Path("libraries.json"))
+```
+
+Analysis APIs never prompt, install tools or download data. Explicit maintenance
+APIs are available for consumers that manage their own setup. The authoritative
+[API/JSON guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/integration.md) documents models, coverage, errors, SBOM,
+profile provisioning and offline advisory assessment. Structural matching normally
+identifies families; exact installed versions require stronger evidence.
+
+## Documentation and development
+
+| I want to… | Read |
+|---|---|
+| Install from pip, GitHub or a source ZIP | [Installation](https://github.com/ernestomgz/libidentifier/blob/main/docs/installation.md) |
+| Scan, save output, use offline mode or repair setup | [Usage guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/quickstart.md) |
+| Integrate the Python API or consume JSON | [Public contract](https://github.com/ernestomgz/libidentifier/blob/main/docs/integration.md) |
+| Build my own reference catalog | [Profile database](https://github.com/ernestomgz/libidentifier/blob/main/docs/profile-database.md) |
+| Publish/update official releases | [Maintainer release guide](https://github.com/ernestomgz/libidentifier/blob/main/docs/releases.md) |
+
+Python 3.11+; `lief==0.17.1`. To use a reviewed checkout before publication:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Tests generate synthetic DEX/APK/ELF fixtures. JAR/AAR **profile generation** needs
+local D8; ordinary scans do not need Java or the Android SDK. See the
+[developer index](https://github.com/ernestomgz/libidentifier/blob/main/docs/development/README.md), [release checklist](https://github.com/ernestomgz/libidentifier/blob/main/docs/development/release-readiness.md),
+[Stage 2 acceptance](https://github.com/ernestomgz/libidentifier/blob/main/docs/development/stages/stage-2.md) and [contributor instructions](https://github.com/ernestomgz/libidentifier/blob/main/AGENTS.md).

libidentifier-0.2.0rc1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-Party Notices
+
+LibIdentifier Stage 1 contains original implementation code and does not vendor Androguard, LibScout, OSV-Scanner, Android SDK artifacts, or third-party library binaries.
+
+Runtime dependency:
+
+- LIEF, used for DEX and ELF parsing. See https://lief.re/ and the LIEF project license for redistribution terms.
+
+Research influence:
+
+- LibScout's profile-and-match approach informed the high-level fingerprinting strategy.
+- Androguard documentation informed Android bytecode terminology.
+
+No upstream source files from those projects were copied into this implementation.
+

libidentifier-0.2.0rc1/benchmarks/corpus.example.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "samples": [
+    {
+      "path": "fixtures/independent.apk",
+      "ground_truth_complete": true,
+      "components": [{"family_purl": "pkg:maven/example/demo", "version": "1.0"}],
+      "build": {"compiler": "record actual version", "transformation": "unoptimized", "keep_rules_sha256": null}
+    }
+  ]
+}

libidentifier-0.2.0rc1/benchmarks/run.py

@@ -0,0 +1,84 @@
+"""Isolated scan measurements; quality metrics require complete build ground truth.
+
+python benchmarks/run.py --profiles profiles.sqlite --corpus corpus.json
+Corpus paths are relative to the manifest. Each sample runs in a new process.
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+
+def peak_rss():
+    if os.name != 'nt':
+        import resource
+        return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss * 1024
+    import ctypes
+    from ctypes import wintypes
+    class Counters(ctypes.Structure):
+        _fields_ = [('cb',wintypes.DWORD),('PageFaultCount',wintypes.DWORD)] + [(name,ctypes.c_size_t) for name in (
+            'PeakWorkingSetSize','WorkingSetSize','QuotaPeakPagedPoolUsage','QuotaPagedPoolUsage',
+            'QuotaPeakNonPagedPoolUsage','QuotaNonPagedPoolUsage','PagefileUsage','PeakPagefileUsage')]
+    counters=Counters();counters.cb=ctypes.sizeof(counters)
+    kernel=ctypes.WinDLL('kernel32',use_last_error=True)
+    kernel.GetCurrentProcess.restype=wintypes.HANDLE
+    psapi=ctypes.WinDLL('psapi',use_last_error=True)
+    psapi.GetProcessMemoryInfo.argtypes=[wintypes.HANDLE,ctypes.POINTER(Counters),wintypes.DWORD]
+    if not psapi.GetProcessMemoryInfo(kernel.GetCurrentProcess(),ctypes.byref(counters),counters.cb):
+        raise ctypes.WinError(ctypes.get_last_error())
+    return counters.PeakWorkingSetSize
+
+
+def worker(path,profiles):
+    import lief
+    from libidentifier import identify
+    started=time.perf_counter();result=identify(path,profiles=profiles)
+    return {'input':result.input.to_dict(),'tool_version':result.tool_version,'python':sys.version.split()[0],
+        'lief':lief.__version__,'profile_database':result.profile_database.to_dict(),
+        'seconds':time.perf_counter()-started,'peak_rss_bytes':peak_rss(),
+        'classes':result.coverage.analyzed_count['classes'],'unknown':result.coverage.unknown_classes_total,
+        'clusters':len(result.unattributed_clusters),'relationships':len(result.relationships),
+        'analysis_runs':[r.to_dict() for r in result.analysis_runs],
+        'errors':[e.to_dict() for e in result.errors],
+        'components':[{'family_purl':c.family_purl,'version':c.version} for c in result.components]}
+
+
+def quality(rows, samples):
+    tp=fp=fn=exact=correct=known=0
+    for row,sample in zip(rows,samples):
+        if not sample.get('ground_truth_complete'):
+            continue
+        expected={c['family_purl']:c.get('version') for c in sample['components']}
+        observed={c['family_purl']:c['version'] for c in row['components']}
+        tp+=len(expected.keys()&observed.keys());fp+=len(observed.keys()-expected.keys());fn+=len(expected.keys()-observed.keys())
+        known+=sum(v is not None for v in expected.values())
+        for family,version in observed.items():
+            if version is not None:
+                exact+=1;correct+=family in expected and expected[family]==version
+    return {'family_true_positive':tp,'family_false_positive':fp,'family_false_negative':fn,
+        'exact_version_predictions':exact,'correct_exact_versions':correct,'ground_truth_versioned_components':known,
+        'family_precision':tp/(tp+fp) if tp+fp else None,'family_recall':tp/(tp+fn) if tp+fn else None,
+        'exact_version_precision':correct/exact if exact else None,'exact_version_coverage':correct/known if known else None}
+
+
+def main():
+    parser=argparse.ArgumentParser();parser.add_argument('--profiles',required=True)
+    parser.add_argument('--corpus');parser.add_argument('--worker')
+    args=parser.parse_args()
+    if args.worker:
+        print(json.dumps(worker(args.worker,args.profiles)));return
+    corpus_path=Path(args.corpus).resolve();corpus=json.loads(corpus_path.read_text())
+    if corpus.get('schema_version')!=1:raise ValueError('Unsupported corpus schema')
+    rows=[]
+    for sample in corpus['samples']:
+        completed=subprocess.run([sys.executable,str(Path(__file__).resolve()),'--profiles',str(Path(args.profiles).resolve()),
+            '--worker',str((corpus_path.parent/sample['path']).resolve())],check=True,capture_output=True,text=True,encoding='utf-8',timeout=300)
+        rows.append(json.loads(completed.stdout))
+    print(json.dumps({'schema_version':1,'platform':sys.platform,'samples':rows,'quality':quality(rows,corpus['samples'])},indent=2))
+
+
+if __name__=='__main__':main()

libidentifier-0.2.0rc1/catalog/references.example.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "references": [
+    {
+      "purl": "pkg:maven/example/library@1.0.0",
+      "path": "reference-artifacts/library-1.0.0.dex",
+      "sha256": "<verified-reference-hash>",
+      "license": "Apache-2.0",
+      "provenance_url": "https://example.invalid/reference"
+    }
+  ]
+}
+

libidentifier-0.2.0rc1/catalog/references.json

@@ -0,0 +1,63 @@
+{
+  "schema_version": 1,
+  "fingerprint_algorithm": "dex-shape-v2-canonical+elf-identity-v1",
+  "references": [
+    {
+      "purl": "pkg:maven/com.google.code.gson/gson@2.11.0",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.11.0/gson-2.11.0.jar",
+      "sha256": "57928d6e5a6edeb2abd3770a8f95ba44dce45f3b23b7a9dc2b309c581552a78b",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/commons-io/commons-io@2.16.1",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/commons-io/commons-io/2.16.1/commons-io-2.16.1.jar",
+      "sha256": "f41f7baacd716896447ace9758621f62c1c6b0a91d89acee488da26fc477c84f",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/com.squareup.retrofit2/retrofit@2.9.0",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/squareup/retrofit2/retrofit/2.9.0/retrofit-2.9.0.jar",
+      "sha256": "e6ea1929c46852f5bec66ab3357da383476cef4e8d1deefdbf195b79cc4d6581",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/com.squareup.retrofit2/converter-gson@2.9.0",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/squareup/retrofit2/converter-gson/2.9.0/converter-gson-2.9.0.jar",
+      "sha256": "32aa206b9a29c9df5eda93a092cfb3b0b9133e232c062baa882f0319f0e79f0e",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/com.squareup.okhttp3/okhttp@4.9.0",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/squareup/okhttp3/okhttp/4.9.0/okhttp-4.9.0.jar",
+      "sha256": "dbc2bb04ecb002b9f4046263ccad996f4a3d3c59a0cc98837e300a6700571f7c",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/com.squareup.okhttp3/okhttp@4.9.3",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/squareup/okhttp3/okhttp/4.9.3/okhttp-4.9.3.jar",
+      "sha256": "93ecd6cba19d87dccfe566ec848d91aae799e3cf16c00709358ea69bd9227219",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/com.scottyab/rootbeer-lib@0.0.8",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/scottyab/rootbeer-lib/0.0.8/rootbeer-lib-0.0.8.aar",
+      "sha256": "4750bedff6605ed4ca96e2dd9b13fd6216ba55eb7abf914cbd9f9f00566ad82a",
+      "license": "Apache-2.0"
+    },
+    {
+      "purl": "pkg:maven/com.squareup.okhttp3/okhttp@3.14.9",
+      "repository": "maven-central",
+      "url": "https://repo.maven.apache.org/maven2/com/squareup/okhttp3/okhttp/3.14.9/okhttp-3.14.9.jar",
+      "sha256": "2570fab55515cbf881d7a4ceef49fc515490bc027057e666776a2832465aeca0",
+      "license": "Apache-2.0",
+      "notes": "Targeted SCA validation against the dependency declared by Retrofit 2.9.0; not an installed-version claim"
+    }
+  ]
+}

libidentifier-0.2.0rc1/docs/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+LibIdentifier is API-first. The CLI delegates to the same `identify()`, `inspect()`, `build_profile()`, and `export_cyclonedx()` functions exposed from `libidentifier`.
+
+The scan pipeline is:
+
+1. Detect top-level format from magic bytes.
+2. Traverse ZIP/APK members with bounded, safe reads.
+3. Extract DEX class features and ELF identity features with LIEF. A bounded
+   standard DEX table reader supplies canonical descriptors, interface lists,
+   method references and code-item locations unavailable in LIEF's Python API.
+4. Convert features to deterministic fingerprints.
+5. Query a local read-only SQLite profile database.
+6. Score candidates conservatively and resolve location-aware ownership claims.
+   Conflicting claims, shape multiplicity ambiguity and duplicate descriptors
+   remain unattributed for component-edge aggregation.
+7. Extract structural/signature relationships and bounded explicit invocation
+   references; aggregate only uniquely attributed embedded endpoints.
+8. Group unmatched definitions deterministically by meaningful exact packages
+   and inheritance/interface links. Preserve singleton groups and unknown origin.
+9. Attach published reference declarations and supported embedded Maven version
+   metadata, reporting capability status, evidence, uncertainty and limitations.
+10. Emit deterministic JSON; unknown-output caps apply after enrichment.
+
+The package has no dependency on any consuming application. Optional `scan()`/`correlate()` assessment
+uses a verified local OSV executable and advisory snapshot. Python scan APIs never
+download; the assessment CLI may provision a wholly absent database unless
+`--offline`. Existing databases require explicit update. Assessment itself always
+runs offline. Hosts retain application ownership, reachability and exploitability
+decisions. See the [public contract](integration.md) and [roadmap](development/roadmap.md).
+
+`extractors/instructions.py` traverses standard DEX widths and switch/array
+payloads. Ordinary invoke/range forms yield declared references with absolute
+member byte offsets; special dynamic formats and undecodable methods report
+partial coverage. No runtime dispatch, execution, reachability or data-flow is
+inferred. External/ambiguous targets have no embedded target location.
+
+`profiles/pom.py` handles direct dependencies/local properties only. Parent,
+BOM, dependency-management and profile context remains preserved but unresolved.
+Source release declarations stay distinct from observed APK code references.
+See [profile storage](profile-database.md) for internal schema/rebuild rules.
+
+
+`cli_setup.py` is a CLI-only orchestration layer for managed scans without profile
+overrides. It gathers missing resources, obtains one consent decision, invokes
+explicit profile/advisory maintenance and installs a scanner pinned by
+`cli_resources.py`. Scanner bytes are bounded and checked before execution.
+The same pin catalog is used by native CI; no GitHub latest lookup occurs.
+After setup the managed assessment path is forced offline, including when setup
+was declined or failed. Existing explicit commands and analysis APIs keep their
+previous resource policies.