> ## Documentation Index
> Fetch the complete documentation index at: https://docs.binarly.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Component and Version Identification
> How the Binarly Transparency Platform identifies third-party components and their versions inside a binary, using package metadata, content rules, filename signals, and code similarity.
The Binarly Transparency Platform (BTP) identifies third-party components from evidence found in the scanned image: the contents of the binaries themselves, and the package databases the image happens to carry. A component is recognized because that evidence is present, whether or not a supplied SBOM, build manifest, or attestation declared it.
Identified components appear in the [Components tab](/user-guides/image-scans/all-about-details), populate the [binary-derived SBOM](/user-guides/export/sbom), and provide the product and version data that known-vulnerability matching runs against.
## Identification signals
Four signals contribute, and they establish different things.
| Signal | What it establishes |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Strings recovered from the binary | That the component is present, and which version it is |
| The component filename | That the component is present, and that this file *is* the component rather than merely containing it |
| Package manager metadata | That the component is present, and its exact version, without inferring either from binary contents |
| Code similarity to reference builds | That the component is present, when no version string survives in the binary |
Only two of these produce a version. Package metadata supplies one directly, and recovered strings are how a version is read out of the binary itself. A filename match identifies a component without producing a version, and so does a code-similarity match. This distinction drives most of the behavior described below.
The signals are not alternatives. On an image that carries a package database, all four run, and the platform has to decide which one to trust for a given component. That decision is covered in [When package data takes precedence](#when-package-data-takes-precedence).
## Rule-based identification
Rule-based identification covers native and embedded targets: Linux and POSIX ELF binaries, Linux kernel images, U-Boot, and Zephyr or MCUboot images. These targets are marked **Known (version)** in the [analysis capability matrix](/user-guides/about/supported-platforms#analysis-capability-matrix). Packages from language ecosystems are identified from their own manifests rather than by the rules described here, and are not covered on this page.
BTP maintains a library of component rules covering widely used open-source software: cryptographic and TLS libraries, compression, networking and server software, core Linux userland, media codecs, parsers, databases, language runtimes, and embedded and industrial components. The set grows with each release.
A rule matches on the strings recovered from a component, on the component's filename, or on both, and separately captures the version out of the recovered text. Each rule carries one or more vendor and product identities, which key the [vulnerability database](/resource-center/vdb-sources) lookup and become the CPE recorded against the component in scan output and exports.
### What the filename contributes
The filename is a real signal, but a narrow one.
Filename matching uses the **basename only**. The directory a component was unpacked into is not used as an identity signal, so the same binary is identified the same way regardless of where it sits in the extracted tree.
Build paths do still contribute, but as recovered strings rather than as path signals. A compiler that bakes `bzip2-1.0.8/blocksort.c` into a binary has put that path into the string table, where a rule can match it. That is a property of the file's contents, not of its location on disk.
A filename match alone never yields a version. If a rule identifies a component by name but no version is recovered from the strings, the component is reported without one. Renamed, stripped, or heavily size-optimized builds land in this case routinely.
### How linkage is determined
Every identified component is recorded with a [dependency linkage](/resource-center/transitive-dependencies) describing its relationship to the file it was found in. The signal that matched decides it.
A **filename** match means the file *is* the component, so the result is recorded as **Project**.
A **content** match means the file *contains* the component, and the linkage comes from the rule:
| Declared linkage | When a rule uses it |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Embedded | Libraries that are commonly linked into a larger binary. This is the common case. |
| Project | Multi-binary suites, where any one applet belongs to the parent project. |
| Build | Toolchain and build-provenance artifacts, where the match records what built the binary rather than what ships inside it. |
A Project result is reclassified to **Vendored** when [package metadata](#package-metadata-identification) disagrees with the identified product, meaning the component ships inside a package that is not its own.
## Package metadata identification
Where an image carries a package database, the platform reads it. This is the most precise identification available, because the package manager already recorded exactly what was installed and at which version, and no inference from binary contents is required. The databases maintained by dpkg, rpm, and apk are supported, along with standalone rpm packages found in an image. Which of them is read depends on the image type, listed under [Package manager coverage](/resource-center/provenance#package-manager-coverage).
Each package record contributes its name, version, architecture, source package, vendor, and license. The source package matters as much as the name, because advisories are frequently filed against the source rather than the binary package, so a component installed as `libssl3` is still matched against advisories for `openssl`.
A package database also records which files each package owns, which lets the platform attribute a component to its package. This is what identifies a binary that carries no version string at all: a stripped, size-optimized library that no rule can version is still reported with an exact version when its package owns it.
### Operating system and ecosystem detection
The platform reads the image's operating system release metadata and normalizes it into an ecosystem identifier that names the distribution and its release. Alpine, CentOS, Debian, Red Hat Enterprise Linux, Rocky Linux, and Ubuntu are recognized.
The ecosystem is what connects a component to the right advisory stream. Ubuntu Security Notices apply to an Ubuntu image, Red Hat and Rocky advisories to their respective images, and so on. Without it, only upstream version ranges are available.
An image containing several root filesystems can yield more than one ecosystem. In that case the platform records the candidates rather than committing to one.
### When package data takes precedence
Package data and binary-level identification can both describe the same component, so the platform picks one as authoritative rather than reporting both.
Three conditions must hold together for package data to win: the component must be the package itself rather than something vendored inside it, package metadata must be present, and the vulnerability database must carry advisory coverage for the detected ecosystem.
| Situation | Vulnerability matching |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| The component is its package, and the ecosystem has advisory coverage | Package data is authoritative. Version-based matching is skipped for that component. |
| The component is its package, but the ecosystem has no advisory coverage | Falls back to version-based matching. An empty advisory result proves nothing here. |
| The component is a vendored copy inside another package | Version-based matching. A vendored copy is not fixed by the distribution's patches. |
| The component is statically linked, or no package owns it | Version-based matching. |
Skipping the version-based query is deliberate. Matching a distribution's package against upstream version ranges reports vulnerabilities the distribution has already fixed, so where a distribution's own advisories are available they replace that query instead of supplementing it.
Findings record which path produced them, and package-derived findings carry higher [confidence](#confidence) than version-derived ones.
Identification is reported either way. A component that a distribution has patched still appears in the SBOM with its package, version, and license, carrying no findings.
Package data raises precision where it exists. It does not replace binary-level identification, which runs in every case and is the only thing that finds statically linked and vendored components, because a package database records what the distribution installed and never what was compiled into it.
### How backported patches are resolved
A distribution that backports a fix leaves the upstream version number unchanged, so upstream version ranges still mark the package vulnerable. Two mechanisms correct this, and they apply in different situations.
Where package data and advisory coverage are both available, the distribution's own advisories record the fix against the distribution's package version, and matching against those advisories resolves the CVE correctly. The fixed version reported back is the distribution's, not upstream's. This depends on having the package version, which only the package database supplies, so recognizing that an image is Ubuntu 22.04 is not sufficient on its own.
Where they are not, [VulHunt](https://vulhunt-docs.binarly.io/user-guide/get-started/introduction) covers part of the gap. VulHunt reasons about what a component's code actually does rather than what version it claims to be, so a backported fix is visible to it even though the version string is unchanged. These are the **Known (code)** findings in the [analysis capability matrix](/user-guides/about/supported-platforms#analysis-capability-matrix). Coverage extends to the vulnerabilities that have a rule, which narrows the problem rather than removing it.
## Hybrid identification for UEFI components
UEFI firmware modules rarely carry the version banners that userland binaries do, and third-party code in firmware is statically linked into modules that were never packaged separately. Identification for selected UEFI components therefore combines version-string search with code similarity against reference builds of the component.
The version-string branch runs first. Code similarity runs only where that branch does not match, so a firmware image carrying a plain version banner is identified from the banner and never invokes the similarity path.
Version strings give both identity and version. Code similarity gives identity only. Where similarity is the sole evidence, the reported version is a range asserted by the rule, or unknown.
Similarity coverage is targeted rather than exhaustive. It focuses on the third-party code most often found statically linked in firmware: cryptographic and TLS libraries, compression, image parsing, network supplicants, TPM and TCM drivers, and OEM and silicon vendor reference code. Coverage grows with each release.
Third-party code identified in a UEFI module is always recorded as **Embedded**, since a library inside a firmware module is statically linked by definition.
## Confidence
The confidence on a finding reflects which signal produced it.
Findings matched from a distribution's advisories, where package data was authoritative, are the most reliable of the three paths. Findings matched from a version recovered from the binary are less so, and lower again where the component was identified as contained in the scanned file rather than as the file itself, since the version then describes something embedded rather than the file being reported.
Confidence in the identification and confidence in the vulnerabilities inferred from it are recorded separately, because strong evidence that a component is present is not automatically strong evidence about its version. Both map onto the scale described in [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence).
## Limitations
Where neither package data nor a VulHunt rule applies, a version number is all there is to match against, and a vendor that backports a fix without changing that version leaves the component looking vulnerable when it is not. Version matching on its own cannot distinguish a patched build from an unpatched one at the same version. See [How backported patches are resolved](#how-backported-patches-are-resolved) for the cases that are covered.
Package database coverage differs by image type, as set out in [Package manager coverage](/resource-center/provenance#package-manager-coverage). A Debian or Alpine based firmware image falls outside it and is identified from binary contents alone.
Components identified only by code similarity carry a version range or no version at all, which limits how precisely vulnerabilities can be matched to them.
Stripped, renamed, or rebranded builds that retain no version strings and belong to no package are identified without a version. Aggressive size optimization that discards usage text and banners has the same effect.
Obfuscated components, and forks modified far enough from their upstream, may no longer resemble the reference builds closely enough to be identified.
Rule coverage is finite. A component with no rule, no similarity reference, and no owning package is not identified, even when it is present.
## Related
* [Transitive Dependencies](/resource-center/transitive-dependencies) - The eight dependency linkage types and what each one means
* [Vulnerability Data Sources](/resource-center/vdb-sources) - The data the vendor and product identities are matched against
* [Accuracy & Confidence in Findings](/resource-center/accuracy-confidence) - The confidence scale identification and finding confidence map onto
* [Supported Platforms](/user-guides/about/supported-platforms) - Which targets support version-based identification
* [SBOM Export](/user-guides/export/sbom) - Exporting the identified component inventory
* [VulHunt](https://vulhunt-docs.binarly.io/user-guide/get-started/introduction) - Semantic rule-based detection, which finds vulnerabilities in code regardless of the version a component reports