Skip to content

Commit ec25931

Browse files
fix(report): preserve archive member provenance in JSON
Signed-off-by: Mohit Gupta <[email protected]>
1 parent 5edc347 commit ec25931

4 files changed

Lines changed: 248 additions & 13 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -835,6 +835,9 @@ The top-level shape is (this example shows a full LLM-backed scan; with `--no-ll
835835
- `risk_assessment.severity` ∈ `LOW | MEDIUM | HIGH | CRITICAL`.
836836
- `risk_assessment.recommendation` ∈ `SAFE | CAUTION | DO_NOT_INSTALL`, mapped from severity: `LOW → SAFE`, `MEDIUM → CAUTION`, `HIGH`/`CRITICAL → DO_NOT_INSTALL`.
837837
- `metadata.llm_error` appears only when LLM analysis was requested but unavailable.
838+
- Archive-member components retain their virtual `path` and include `outer_path`, `nested_path`,
839+
and container provenance. Virtual paths identify in-memory members, not on-disk files; see
840+
[JSON component locations](docs/NESTED_ARTIFACT_INSPECTION.md#json-component-locations).
838841
- AE1 findings use **Incomplete referenced artifact analysis**. Their source
839842
location identifies the reference; `evidence` identifies the affected target,
840843
analyzer reasons, and available bounds. Review the target's completeness

‎docs/NESTED_ARTIFACT_INSPECTION.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,37 @@ Nested members use a stable virtual path that retains their full provenance:
1111
outer-file!/nested.zip!/scripts/setup.sh
1212
```
1313

14+
## JSON component locations
15+
16+
JSON component rows preserve this virtual path in `path`, matching finding locations and
17+
inspection-ledger entries. Archive members also expose their existing inventory provenance:
18+
19+
```json
20+
{
21+
"path": "bundle.whl!/package/module.py",
22+
"type": "python",
23+
"executable": true,
24+
"outer_path": "bundle.whl",
25+
"nested_path": "package/module.py",
26+
"container_type": "zip",
27+
"container_ancestry": ["zip"],
28+
"container_depth": 1
29+
}
30+
```
31+
32+
`outer_path` names the physical container relative to that component's source root. `nested_path`
33+
retains the full member chain inside it, including any nested `!/` boundaries. Each member keeps
34+
its own component row, executable flag, type, line count, and byte size. Ordinary files do not gain
35+
archive fields merely because their names contain `!/`.
36+
37+
Consumers must distinguish a virtual member from an on-disk file: `executable: true` describes
38+
the member's content, not the existence of its virtual path on disk. Use the source identity and
39+
full `path` to join components with findings; do not collapse members by `outer_path`. When
40+
validating a report, check archive provenance and containment within the corresponding source
41+
root, and retain incomplete-inspection failures. These additive fields do not change existing
42+
consumer validators automatically, prove that every member was inspected, or justify extracting
43+
or executing archive content.
44+
1445
## Security invariants
1546

1647
- Members are read in memory. SkillSpector never extracts, renders, imports, installs, or executes

‎src/skillspector/nodes/report.py‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1370,6 +1370,43 @@ def _build_metadata(
13701370
return meta
13711371

13721372

1373+
def _json_component(component: Mapping[str, object]) -> dict[str, object]:
1374+
"""Preserve component identity and expose structured archive provenance."""
1375+
result = {
1376+
key: component.get(key)
1377+
for key in (
1378+
"path",
1379+
"type",
1380+
"lines",
1381+
"executable",
1382+
"size_bytes",
1383+
"source_url",
1384+
"source_identity",
1385+
"source_digest",
1386+
)
1387+
}
1388+
outer_path = component.get("outer_path")
1389+
nested_path = component.get("nested_path")
1390+
if (
1391+
isinstance(outer_path, str)
1392+
and outer_path
1393+
and isinstance(nested_path, str)
1394+
and nested_path
1395+
and component.get("path") == f"{outer_path}!/{nested_path}"
1396+
):
1397+
result.update(outer_path=outer_path, nested_path=nested_path)
1398+
container_type = component.get("container_type")
1399+
if isinstance(container_type, str) and container_type:
1400+
result["container_type"] = container_type
1401+
depth = component.get("container_depth")
1402+
if isinstance(depth, int) and not isinstance(depth, bool) and depth > 0:
1403+
result["container_depth"] = depth
1404+
ancestry = component.get("container_ancestry")
1405+
if isinstance(ancestry, list) and all(isinstance(item, str) and item for item in ancestry):
1406+
result["container_ancestry"] = list(ancestry)
1407+
return result
1408+
1409+
13731410
def _format_json(
13741411
findings: list[Finding],
13751412
component_metadata: list[dict[str, object]],
@@ -1410,19 +1447,7 @@ def _format_json(
14101447
"recommendation": risk_recommendation,
14111448
"max_issue_severity": _max_issue_severity(findings),
14121449
},
1413-
"components": [
1414-
{
1415-
"path": c.get("path"),
1416-
"type": c.get("type"),
1417-
"lines": c.get("lines"),
1418-
"executable": c.get("executable"),
1419-
"size_bytes": c.get("size_bytes"),
1420-
"source_url": c.get("source_url"),
1421-
"source_identity": c.get("source_identity"),
1422-
"source_digest": c.get("source_digest"),
1423-
}
1424-
for c in component_metadata
1425-
],
1450+
"components": [_json_component(component) for component in component_metadata],
14261451
"structured_summaries": structured_summaries or [],
14271452
"issues": [f.to_dict() for f in findings],
14281453
"suppressed_count": len(suppressed),
Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
"""Archive provenance remains available without changing reported member identity."""
5+
6+
from __future__ import annotations
7+
8+
import io
9+
import json
10+
import zipfile
11+
from pathlib import Path
12+
from typing import cast
13+
14+
import pytest
15+
16+
from skillspector.models import Finding
17+
from skillspector.nodes.analyzers.static_patterns_supply_chain import (
18+
_analyze_concealed_executables,
19+
)
20+
from skillspector.nodes.build_context import build_context
21+
from skillspector.nodes.finalize_inspection_ledger import finalize_inspection_ledger
22+
from skillspector.nodes.report import report
23+
from skillspector.state import SkillspectorState
24+
25+
PROVENANCE_FIELDS = (
26+
"outer_path",
27+
"nested_path",
28+
"container_type",
29+
"container_ancestry",
30+
"container_depth",
31+
)
32+
33+
34+
@pytest.fixture(autouse=True)
35+
def disable_provider_probe(monkeypatch: pytest.MonkeyPatch) -> None:
36+
monkeypatch.setattr(
37+
"skillspector.nodes.report.is_llm_available", lambda **_: (False, "Disabled in test")
38+
)
39+
40+
41+
def _zip_bytes(members: dict[str, bytes]) -> bytes:
42+
buffer = io.BytesIO()
43+
with zipfile.ZipFile(buffer, "w") as archive:
44+
for name, content in members.items():
45+
archive.writestr(name, content)
46+
return buffer.getvalue()
47+
48+
49+
def _json_report(context: dict[str, object], findings: list[Finding] | None = None) -> dict:
50+
state = cast(
51+
SkillspectorState,
52+
{**context, "findings": findings or [], "output_format": "json", "use_llm": False},
53+
)
54+
return json.loads(report(state)["report_body"])
55+
56+
57+
def test_wheel_and_recursive_zip_keep_complete_member_identity(tmp_path: Path) -> None:
58+
(tmp_path / "package.whl").write_bytes(
59+
_zip_bytes({"package/__init__.py": b"VALUE = 1\n", "package/data.txt": b"data\n"})
60+
)
61+
(tmp_path / "outer.zip").write_bytes(
62+
_zip_bytes({"inner.zip": _zip_bytes({"run.sh": b"#!/bin/sh\necho hello\n"})})
63+
)
64+
context = build_context({"skill_path": str(tmp_path)})
65+
metadata = context["component_metadata"]
66+
source = {
67+
"source_url": "https://example.com/package.zip",
68+
"source_identity": "source-sha256:" + "a" * 64,
69+
"source_digest": "b" * 64,
70+
}
71+
for component in metadata:
72+
component.update(source)
73+
74+
payload = _json_report(context)
75+
rows = {row["path"]: row for row in payload["components"]}
76+
77+
assert len(payload["components"]) == len(metadata) == len(rows)
78+
assert rows.keys() == {component["path"] for component in metadata}
79+
for component in metadata:
80+
row = rows[component["path"]]
81+
for field in ("path", "type", "lines", "executable", "size_bytes"):
82+
assert row[field] == component[field]
83+
assert {field: row[field] for field in source} == source
84+
for path, outer, nested, depth in (
85+
("package.whl!/package/__init__.py", "package.whl", "package/__init__.py", 1),
86+
("package.whl!/package/data.txt", "package.whl", "package/data.txt", 1),
87+
("outer.zip!/inner.zip", "outer.zip", "inner.zip", 1),
88+
("outer.zip!/inner.zip!/run.sh", "outer.zip", "inner.zip!/run.sh", 2),
89+
):
90+
row = rows[path]
91+
assert row["outer_path"] == outer
92+
assert row["nested_path"] == nested
93+
assert row["container_type"] == "zip"
94+
assert row["container_ancestry"] == ["zip"] * depth
95+
assert row["container_depth"] == depth
96+
assert rows["package.whl!/package/__init__.py"]["executable"] is True
97+
assert rows["outer.zip!/inner.zip!/run.sh"]["executable"] is True
98+
assert rows["package.whl!/package/data.txt"]["executable"] is False
99+
assert not any(field in rows["package.whl"] for field in PROVENANCE_FIELDS)
100+
101+
102+
def test_concealed_member_keeps_security_finding_and_risk(tmp_path: Path) -> None:
103+
(tmp_path / ".hidden.zip").write_bytes(_zip_bytes({"run.sh": b"#!/bin/sh\necho hello\n"}))
104+
context = build_context({"skill_path": str(tmp_path)})
105+
findings = _analyze_concealed_executables(context["component_metadata"])
106+
finding = next(item for item in findings if item.rule_id == "SC9")
107+
original_fingerprint = finding.fingerprint()
108+
109+
payload = _json_report(context, findings)
110+
issue = next(item for item in payload["issues"] if item["id"] == "SC9")
111+
member = next(row for row in payload["components"] if row["path"] == finding.file)
112+
113+
assert issue["location"]["file"] == member["path"] == ".hidden.zip!/run.sh"
114+
assert member["outer_path"] == issue["evidence"]["outer_path"] == ".hidden.zip"
115+
assert member["nested_path"] == issue["evidence"]["nested_path"] == "run.sh"
116+
assert member["executable"] is True
117+
assert issue["severity"] == "HIGH"
118+
assert issue["match_fingerprint"] == original_fingerprint
119+
assert payload["risk_assessment"]["score"] > 0
120+
assert payload["risk_assessment"]["recommendation"] != "SAFE"
121+
122+
123+
def test_truncated_nested_archive_preserves_incomplete_verdict(tmp_path: Path) -> None:
124+
(tmp_path / "outer.zip").write_bytes(_zip_bytes({"broken.zip": b"PK\x03\x04truncated"}))
125+
context = build_context({"skill_path": str(tmp_path), "use_llm": False})
126+
finalized = finalize_inspection_ledger(cast(SkillspectorState, {**context, "use_llm": False}))
127+
128+
payload = _json_report({**context, **finalized})
129+
completeness = payload["analysis_completeness"]
130+
member = next(row for row in payload["components"] if row["path"] == "outer.zip!/broken.zip")
131+
132+
assert member["outer_path"] == "outer.zip"
133+
assert member["nested_path"] == "broken.zip"
134+
assert completeness == finalized["analysis_completeness"]
135+
assert completeness["is_complete"] is False
136+
assert any(
137+
row["path"] == member["path"] and row["reason_code"] == "archive_truncated"
138+
for row in completeness["ledger_exceptions"]
139+
)
140+
assert payload["execution_successful"] == completeness["execution_successful"]
141+
assert payload["risk_assessment"]["recommendation"] != "SAFE"
142+
143+
144+
def test_literal_archive_separator_in_physical_path_has_no_provenance(tmp_path: Path) -> None:
145+
directory = tmp_path / "notes!"
146+
directory.mkdir()
147+
(directory / "run.py").write_text("VALUE = 1\n", encoding="utf-8")
148+
context = build_context({"skill_path": str(tmp_path)})
149+
150+
payload = _json_report(context)
151+
row = next(item for item in payload["components"] if item["path"] == "notes!/run.py")
152+
153+
assert row["executable"] is True
154+
assert not any(field in row for field in PROVENANCE_FIELDS)
155+
156+
157+
@pytest.mark.parametrize(
158+
("outer_path", "nested_path"),
159+
[("other.zip", "run.py"), ("bundle.zip", "other.py"), ("", "run.py"), (None, "run.py")],
160+
)
161+
def test_inconsistent_provenance_is_not_exported(outer_path: str | None, nested_path: str) -> None:
162+
component = {
163+
"path": "bundle.zip!/run.py",
164+
"executable": True,
165+
"outer_path": outer_path,
166+
"nested_path": nested_path,
167+
"container_type": "zip",
168+
"container_ancestry": ["zip"],
169+
"container_depth": 1,
170+
}
171+
172+
row = _json_report({"component_metadata": [component]})["components"][0]
173+
174+
assert row["path"] == component["path"]
175+
assert row["executable"] is True
176+
assert not any(field in row for field in PROVENANCE_FIELDS)

0 commit comments

Comments
 (0)