@@ -50,7 +50,8 @@ This guide walks you through both installation and usage.
             2. [Binary Scan Options](#binary-scan-options)
             3. [How Components Are Identified](#how-components-are-identified)
             4. [Unidentified Components](#unidentified-components)
-            5. [Limitations](#binary-scan-limitations)
+            5. [Declared Dependencies](#declared-dependencies)
+            6. [Limitations](#binary-scan-limitations)
         5. [Commit History Scan](#commit-history-scan)
             1. [Commit Range Option (Diff Scanning)](#commit-range-option-diff-scanning)
         6. [Pre-Commit Scan](#pre-commit-scan)
@@ -1051,7 +1052,10 @@ Nested archives are opened recursively, so a JAR inside a WAR inside an EAR is s
 |---|---|---|
 | `--max-depth` | `3` | Nested-archive recursion limit. An EAR containing WARs containing JARs is depth 3. |
 | `--offline` | off | Identify components from embedded metadata only. Acknowledges and silences the partial-results warning. |
-| `--maven-central` | off | Look up archives that embedded metadata cannot identify on Maven Central by SHA-1. Sends only the digest, never the archive. Cannot be combined with `--offline`. |
+| `--maven-central` | off | Consult Maven Central: look up archives that embedded metadata cannot identify by SHA-1, and with `--include-declared` fetch parent poms to pin declared versions. Sends digests and public coordinates, never the archive. Cannot be combined with `--offline`. |
+| `--include-declared` | off | Also report the compile- and runtime-scope dependencies that embedded `pom.xml` files declare but the artifact does not ship. See [Declared Dependencies](#declared-dependencies). |
+| `--include-test-scope` | off | With `--include-declared`: also report test-, provided- and system-scope declarations, which never reach a consuming build. Matches SCA tools that count every declared dependency. |
+| `--include-transitive` | off | With `--include-declared` and `--maven-central`: follow each declared dependency through its own pom to the dependencies it needs in turn, the way a Maven build would. |
 | `--project-name` | inferred | Override the platform identity when the artifact is detached from its source repository. |
 | `--keep-bom` | off | Write the generated component inventory beside each artifact, for inspection or audit. |
 | `--include-binaries` | off | On `scan path` only. Extract any Java archives encountered during the walk. |
@@ -1095,6 +1099,52 @@ We do not guess a component's identity from its filename.
 `internal-shim.jar` is not evidence of anything, and an admitted gap is more useful than an invented coordinate.
 Unidentified components do not set the exit code on their own.
 
+#### Declared Dependencies
+
+By default a binary scan reports what is physically inside the artifact.
+That is the right answer for a deployable, but it is not the only question worth asking of a library JAR.
+A build that consumes that JAR inherits its compile- and runtime-scope dependencies, whether or not the vendor shipped them, and a vulnerability in one of those is real in the consuming build.
+
+`--include-declared` answers that second question from the same embedded metadata:
+
+`cycode scan -t sca --include-declared --maven-central binary ./vendor/woden-core.jar`
+
+Every embedded `pom.xml` is read the way Maven reads it.
+Each dependency it declares at `compile` or `runtime` scope, and which is not already present in the artifact, is added to the component inventory as a **declared** component and scanned like any other.
+Dependencies Maven would never hand to a consumer are left out: `test`, `provided` and `system` scope, and anything marked `optional`.
+
+Some SCA tools count every declared dependency regardless of scope, so their totals include a vendor's own test libraries.
+To compare against such a report, add `--include-test-scope` and those declarations are reported too.
+Each declared component still records its scope, so a `test` finding can be told apart from one that reaches a build.
+
+Versions in a real pom are rarely literal.
+`${property}` references and `${project.version}` are resolved from the pom itself.
+A version managed by a parent pom, or by an imported BOM, lives on Maven Central rather than inside the JAR, so resolving it needs `--maven-central`.
+Without it, or when the parent cannot be fetched, the dependency is listed in its own section with the reason instead of being guessed at:
+
+```
+╭─ 📜 Declared, version unresolved (2) ──────────────────────────────────────────────╮
+│   Dependency                    Version  Declared by                    Why          │
+│   commons-logging:commons-log…  -        woden-core.jar > META-INF/…    no version …  │
+╰────────────────────────────────────────────────────────────────────────────────────╯
+
+1 identified | 0 unidentified | 2 declared (2 unresolved) | 0 vulnerabilities
+```
+
+A finding on a declared component says `Declared by` and the pom that made the claim, rather than `Found in`, and its presence is marked `declared` in the generated BOM.
+Declared components carry no hashes, because there are no bytes to digest.
+`--output json` reports the counts under `binary.declared`.
+
+A declared dependency has dependencies of its own.
+`--include-transitive` follows each one through its pom on Maven Central and reports what it needs in turn, so it requires `--maven-central`.
+The walk follows Maven's rules: the nearest declaration of a coordinate wins, exclusions apply down their branch, optional dependencies are not followed, and a transitive's scope is combined with the scope it was reached through, so a test dependency's tree stays test scope.
+Each transitive component records the dependency that pulled it in as `cycode:via`, and the dependency graph in the BOM links them.
+On a real vendor jar this typically fetches a few dozen poms and adds under a minute to the scan.
+
+> [!NOTE]
+> Version ranges and versions that only a repository's metadata could pin are listed as unresolved, never guessed.
+> Where the consuming build exists, scanning its output or its `pom.xml` remains the most exact answer: a build tool resolves profiles and repository settings this walk cannot see.
+
 #### Binary Scan Limitations
 
 Read this before relying on a binary scan as your only check.
@@ -1702,9 +1752,13 @@ It uses the same extraction as [Binary Scan](#binary-scan), so the [limitations]
 
 The `binary` subcommand supports the following additional option:
 
-| Option        | Description                                                                                  |
-|---------------|----------------------------------------------------------------------------------------------|
-| `--max-depth` | Nested-archive recursion limit. Defaults to 3. An EAR containing WARs containing JARs is depth 3. |
+| Option               | Description                                                                                  |
+|----------------------|----------------------------------------------------------------------------------------------|
+| `--max-depth`        | Nested-archive recursion limit. Defaults to 3. An EAR containing WARs containing JARs is depth 3. |
+| `--maven-central`    | Consult Maven Central to identify archives by SHA-1 and, with `--include-declared`, to fetch parent poms. |
+| `--include-declared` | Also include the compile- and runtime-scope dependencies that embedded `pom.xml` files declare but the artifact does not ship, marked `declared` rather than `shipped`. See [Declared Dependencies](#declared-dependencies). |
+| `--include-test-scope` | With `--include-declared`: also include test-, provided- and system-scope declarations. |
+| `--include-transitive` | With `--include-declared` and `--maven-central`: follow each declared dependency to what its own pom needs. |
 
 # Import Command
 
 
@@ -34,8 +34,34 @@ def binary_command(
         bool,
         typer.Option(
             '--maven-central',
-            help='Look archives that embedded metadata cannot identify up on Maven Central by SHA-1. '
-            'Sends the digest of each such archive, never the archive itself, to search.maven.org.',
+            help='Consult Maven Central: look archives that embedded metadata cannot identify up by SHA-1, and '
+            'with --include-declared fetch parent poms to pin declared versions. Sends digests and public '
+            'coordinates, never the archive itself.',
+        ),
+    ] = False,
+    include_declared: Annotated[
+        bool,
+        typer.Option(
+            '--include-declared',
+            help='Also include the compile- and runtime-scope dependencies that embedded pom.xml files declare '
+            'but the artifact does not ship, marked as declared rather than shipped. '
+            'Versions managed by a parent pom need --maven-central to resolve.',
+        ),
+    ] = False,
+    include_test_scope: Annotated[
+        bool,
+        typer.Option(
+            '--include-test-scope',
+            help='With --include-declared: also include test-, provided- and system-scope declarations, which '
+            'Maven never passes to a consuming build. Each component still records its scope.',
+        ),
+    ] = False,
+    include_transitive: Annotated[
+        bool,
+        typer.Option(
+            '--include-transitive',
+            help='With --include-declared and --maven-central: follow each declared dependency to the '
+            'dependencies its own pom declares, the way a Maven build would, and include those too.',
         ),
     ] = False,
 ) -> None:
@@ -52,8 +78,23 @@ def binary_command(
     Format conversion happens server-side, so every format the path command supports is supported here too.
 
     """
+    if include_test_scope and not include_declared:
+        raise typer.BadParameter(
+            '--include-test-scope widens what --include-declared reports; it does nothing on its own.',
+            param_hint='--include-test-scope',
+        )
+    if include_transitive and not (include_declared and maven_central):
+        raise typer.BadParameter(
+            '--include-transitive follows declared dependencies through their poms on Maven Central; '
+            'it needs both --include-declared and --maven-central.',
+            param_hint='--include-transitive',
+        )
+
     ctx.obj['binary_max_depth'] = max_depth
     ctx.obj['maven_central'] = maven_central
+    ctx.obj['include_declared'] = include_declared
+    ctx.obj['include_test_scope'] = include_test_scope
+    ctx.obj['include_transitive'] = include_transitive
 
     client = get_report_cycode_client(ctx)
     report_parameters = ctx.obj['report_parameters']
 
@@ -129,8 +129,38 @@ def scan_command(
         bool,
         typer.Option(
             '--maven-central',
-            help='Look archives that embedded metadata cannot identify up on Maven Central by SHA-1. '
-            'Sends the digest of each such archive, never the archive itself, to search.maven.org.',
+            help='Consult Maven Central: look archives that embedded metadata cannot identify up by SHA-1, and '
+            'with --include-declared fetch parent poms to pin declared versions. Sends digests and public '
+            'coordinates, never the archive itself.',
+            rich_help_panel=_BINARY_RICH_HELP_PANEL,
+        ),
+    ] = False,
+    include_declared: Annotated[
+        bool,
+        typer.Option(
+            '--include-declared',
+            help='Also report the compile- and runtime-scope dependencies that embedded pom.xml files declare '
+            'but the artifact does not ship: what a build consuming the artifact would pull in. '
+            'Versions managed by a parent pom need --maven-central to resolve.',
+            rich_help_panel=_BINARY_RICH_HELP_PANEL,
+        ),
+    ] = False,
+    include_test_scope: Annotated[
+        bool,
+        typer.Option(
+            '--include-test-scope',
+            help='With --include-declared: also report test-, provided- and system-scope declarations, which '
+            'Maven never passes to a consuming build. Matches SCA tools that count every declared dependency. '
+            'Each component still records its scope.',
+            rich_help_panel=_BINARY_RICH_HELP_PANEL,
+        ),
+    ] = False,
+    include_transitive: Annotated[
+        bool,
+        typer.Option(
+            '--include-transitive',
+            help='With --include-declared and --maven-central: follow each declared dependency to the '
+            'dependencies its own pom declares, the way a Maven build would, and report those too.',
             rich_help_panel=_BINARY_RICH_HELP_PANEL,
         ),
     ] = False,
@@ -211,6 +241,17 @@ def scan_command(
             '--offline identifies from embedded metadata only; it cannot be combined with --maven-central.',
             param_hint='--maven-central',
         )
+    if include_test_scope and not include_declared:
+        raise typer.BadParameter(
+            '--include-test-scope widens what --include-declared reports; it does nothing on its own.',
+            param_hint='--include-test-scope',
+        )
+    if include_transitive and not (include_declared and maven_central):
+        raise typer.BadParameter(
+            '--include-transitive follows declared dependencies through their poms on Maven Central; '
+            'it needs both --include-declared and --maven-central.',
+            param_hint='--include-transitive',
+        )
 
     # _single_value_callback validated exactly one value was provided; unwrap from list
     scan_type = scan_type[0]
@@ -226,6 +267,9 @@ def scan_command(
     ctx.obj['binary_max_depth'] = max_depth
     ctx.obj['offline'] = offline
     ctx.obj['maven_central'] = maven_central
+    ctx.obj['include_declared'] = include_declared
+    ctx.obj['include_test_scope'] = include_test_scope
+    ctx.obj['include_transitive'] = include_transitive
     ctx.obj['project_name'] = project_name
     ctx.obj['keep_bom'] = keep_bom
     ctx.obj['include_binaries'] = include_binaries
 
@@ -231,6 +231,12 @@
 BINARY_MAX_DEPTH = 3
 BINARY_MAVEN_CENTRAL_SEARCH_URL = 'https://search.maven.org/solrsearch/select'
 BINARY_DIGEST_LOOKUP_TIMEOUT_IN_SECONDS = 10
+BINARY_MAVEN_CENTRAL_REPOSITORY_URL = 'https://repo1.maven.org/maven2'
+BINARY_POM_MAX_SIZE_IN_BYTES = 1024 * 1024  # 1 MB; the largest poms on Central are a few hundred KB
+BINARY_POM_FETCH_BUDGET = 32  # parent and imported poms consulted for one embedded pom
+BINARY_POM_PARENT_MAX_DEPTH = 10
+BINARY_TRANSITIVE_MAX_DEPTH = 10  # hops from a declared dependency; Maven trees are rarely deeper than 6
+BINARY_TRANSITIVE_FETCH_BUDGET = 250  # poms consulted for one embedded pom's whole tree, parents included
 BINARY_MAX_ENTRY_COUNT = 100_000
 BINARY_MAX_ENTRY_SIZE_IN_BYTES = 512 * 1024 * 1024  # 512 MB
 BINARY_MAX_TOTAL_SIZE_IN_BYTES = 2 * 1024 * 1024 * 1024  # 2 GB
 
@@ -15,6 +15,11 @@
 EVIDENCE_POM_PROPERTIES = 'pom.properties'
 EVIDENCE_DIGEST = 'digest'
 EVIDENCE_MANIFEST = 'manifest.mf'
+EVIDENCE_POM_XML = 'pom.xml'  # declared by an embedded pom, not found as bytes; only with --include-declared
+
+# whether the component's bytes are in the artifact, or an embedded pom merely says a consumer will need it
+PRESENCE_SHIPPED = 'shipped'
+PRESENCE_DECLARED = 'declared'
 
 CONFIDENCE_EXACT = 'exact'
 CONFIDENCE_AMBIGUOUS = 'ambiguous'
@@ -49,12 +54,26 @@ class IdentifiedComponent:
     group: str
     artifact: str
     version: str
-    sha1: str
-    logical_path: str
+    sha1: Optional[str]  # None only for a declared component: there are no bytes to digest
+    logical_path: str  # for a declared component, the pom that declares it
     parent: Optional[str]
     evidence: str  # one of the EVIDENCE_* constants
     confidence: str  # one of the CONFIDENCE_* constants
     sha256: Optional[str] = None
+    declared_scope: Optional[str] = None  # the Maven scope a declared component was declared with; None if shipped
+    declared_via: Optional[str] = None  # 'group:artifact' that pulled a transitive in; None for a direct declaration
+
+    @property
+    def is_declared(self) -> bool:
+        return self.declared_scope is not None
+
+    @property
+    def is_transitive(self) -> bool:
+        return self.declared_via is not None
+
+    @property
+    def presence(self) -> str:
+        return PRESENCE_DECLARED if self.is_declared else PRESENCE_SHIPPED
 
     @property
     def purl(self) -> str:
@@ -73,6 +92,21 @@ class UnidentifiedArtifact:
     size: int
 
 
+@dataclass(frozen=True)
+class UnresolvedDeclaration:
+    """A declared dependency whose version could not be established. Listed, never guessed."""
+
+    group: str
+    artifact: str
+    version_expression: Optional[str]
+    declared_by: str  # logical path of the pom
+    reason: str
+
+    @property
+    def coordinate_key(self) -> str:
+        return f'{self.group}:{self.artifact}'
+
+
 @dataclass
 class ExtractionResult:
     components: list[IdentifiedComponent] = field(default_factory=list)
@@ -84,6 +118,20 @@ class ExtractionResult:
     # bom-ref -> the refs it depends on, containment overlaid with real edges recovered from embedded poms
     dependency_edges: dict[str, list[str]] = field(default_factory=dict)
     has_real_edges: bool = False
+    # --include-declared only: declared dependencies whose version could not be established
+    declared_unresolved: list[UnresolvedDeclaration] = field(default_factory=list)
+
+    @property
+    def declared_components(self) -> list[IdentifiedComponent]:
+        return [component for component in self.components if component.is_declared]
+
+    @property
+    def transitive_components(self) -> list[IdentifiedComponent]:
+        return [component for component in self.components if component.is_transitive]
+
+    @property
+    def shipped_components(self) -> list[IdentifiedComponent]:
+        return [component for component in self.components if not component.is_declared]
 
 
 class BinaryExtractor(ABC):