Skip to content

Commit 4ae7c7b

Browse files
authored
Merge pull request #795 from NVIDIA/yashraj/scan-unverified-oms-content
fix(ingest): inspect unverified OMS bundle contents
2 parents e8850a8 + 37a27de commit 4ae7c7b

9 files changed

Lines changed: 785 additions & 128 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -934,13 +934,15 @@ SkillSpector uses a two-stage detection pipeline:
934934
- High recall (catches most issues)
935935
- Moderate precision (some false positives)
936936

937-
A valid, root-level OpenSSF Model Signing signature (`skill.oms.sig`) is retained in the
938-
component inventory as type `oms_signature`, but excluded from static and LLM content analysis.
939-
OMS bundles necessarily contain long base64-encoded payload, signature, and certificate fields;
940-
generic obfuscated-code checks can otherwise misclassify those fields as hidden executable content.
941-
The recognizer checks the minimal OMS DSSE/in-toto structure; it does not verify the signature,
942-
certificate chain, transparency-log entry, or signer identity. Invalid or unrecognized signature
943-
files are scanned normally.
937+
OpenSSF Model Signing / DSSE bundles remain in content analysis, regardless of
938+
filename. Static and LLM analyzers inspect decoded JSON payloads, readable DER
939+
certificate/signature content, and all unknown wrapper fields. Strictly parsed
940+
binary fields are projected rather than treated as executable base64; canonical
941+
bytes remain available to YARA and fingerprints. Unsupported encodings (including
942+
environments without the optional `cryptography` dependency) retain raw fields
943+
and produce an explicit incomplete-analysis warning. Findings in decoded content
944+
point to the original bundle and label their projection in evidence. None of this
945+
verifies signatures, certificate chains, transparency logs, or signer identity.
944946

945947
### Stage 2: LLM Semantic Analysis (Optional)
946948
- Evaluates context and intent
@@ -969,7 +971,7 @@ The tool requires outbound HTTPS access to `api.osv.dev` for live vulnerability
969971
SkillSpector is defense-in-depth, not a sandbox. Know what it does and does not do before relying on it:
970972

971973
- **It never executes the scanned skill.** All analysis is static (regex, Python AST, YARA) plus optional LLM evaluation of file *contents* — the skill's code is never run.
972-
- **LLM analysis sends analyzer-eligible file contents to the configured provider.** When LLM analysis is enabled (the default), file contents are sent to the active `SKILLSPECTOR_PROVIDER` endpoint. Recognized OMS signature files are excluded. Use `--no-llm` to keep contents local (static analysis only).
974+
- **LLM analysis sends analyzer-eligible file contents to the configured provider.** When LLM analysis is enabled (the default), file contents are sent to the active `SKILLSPECTOR_PROVIDER` endpoint. DSSE payloads and readable signing metadata are included. Use `--no-llm` to keep contents local (static analysis only).
973975
- **SC4 sends dependency names to OSV.dev.** The supply-chain check queries [OSV.dev](https://osv.dev) with the package names and versions the skill declares, to look up known CVEs. This is fundamental to the check and runs even with `--no-llm`. It sends dependency coordinates (not file contents), requires no API key, and falls back to a bundled list when OSV.dev is unreachable.
974976
- **It does not sandbox the host.** SkillSpector flags risky patterns *before* you install a skill; it does not contain or isolate a skill you choose to install anyway.
975977

‎docs/DEVELOPMENT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ All targets assume the virtual environment is **already created and activated**.
8181
| `zip_bytes`, `mode` | Optional zip input and scan mode |
8282
| `components` | List of relative file paths in the skill |
8383
| `file_cache` | Map of path → file contents |
84-
| `inspection_ledger` | Structured evidence for files excluded, skipped, or failed during analysis; a recognized OMS signature is recorded as an `oms_signature` scope exclusion. |
84+
| `inspection_ledger` | Structured evidence for files excluded, skipped, or failed during analysis; unsupported DSSE decoding is recorded as an `oms_signature` partial event; successfully projected bundles remain in analysis without a scope exclusion. |
8585
| `ast_cache` | Map of path → AST representation (for future use) |
8686
| `manifest`, `previous_manifest` | Parsed skill metadata (e.g. from SKILL.md) |
8787
| `component_metadata` | List of dicts: path, type, lines, executable, size_bytes (from build_context) |

‎src/skillspector/inspection_ledger.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ class LedgerReason(StrEnum):
156156
LedgerReason.MANIFEST_ABSENT: ("No compatible manifest was present for this analyzer."),
157157
LedgerReason.NO_APPLICABLE_FILES: ("No files matched this analyzer's applicability contract."),
158158
LedgerReason.OMS_SIGNATURE: (
159-
"Recognized OMS signature metadata is excluded from content analysis."
159+
"DSSE content decoding is incomplete or unsupported; raw fields were retained for inspection. Signature authenticity was not verified."
160160
),
161161
LedgerReason.BASELINE_FILE: (
162162
"The explicitly selected suppression baseline is excluded from content analysis."

‎src/skillspector/nodes/analyzers/static_runner.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
observe_analyzer_findings,
5858
)
5959
from skillspector.nodes.deduplicate import classification_metadata_key
60+
from skillspector.oms import project_oms_content
6061
from skillspector.python_ast import (
6162
MAX_PYTHON_AST_SOURCE_CHARS,
6263
ParsedPythonFile,
@@ -2310,9 +2311,46 @@ def _scan_all_views_detailed(
23102311
started_at: float | None = None,
23112312
python_ast: ParsedPythonFile | None = None,
23122313
python_source: bool | None = None,
2314+
_oms_projected: bool = False,
23132315
) -> tuple[list[Finding], LedgerReason | None, dict[str, int | float]]:
23142316
"""Scan bounded raw windows and return any limit with observed/limit metrics."""
23152317
started_at = time.monotonic() if started_at is None else started_at
2318+
runtime_limit = MAX_STATIC_ANALYSIS_SECONDS_PER_ARTIFACT
2319+
if timeout_seconds is not None:
2320+
runtime_limit = min(runtime_limit, max(0.0, timeout_seconds))
2321+
now = time.monotonic()
2322+
if now >= started_at + runtime_limit:
2323+
return (
2324+
[],
2325+
LedgerReason.RUNTIME_LIMIT,
2326+
{
2327+
"observed_seconds": max(0.0, now - started_at),
2328+
"limit_seconds": runtime_limit,
2329+
},
2330+
)
2331+
projection = None if _oms_projected else project_oms_content(content)
2332+
if projection is not None and projection.view.name != "raw":
2333+
findings, reason, metrics = _scan_all_views_detailed(
2334+
path,
2335+
projection.view.text,
2336+
pattern_modules,
2337+
None,
2338+
max_findings=max_findings,
2339+
timeout_seconds=timeout_seconds,
2340+
started_at=started_at,
2341+
# This view is derived JSON metadata, not a Python execution surface.
2342+
python_source=False,
2343+
_oms_projected=True,
2344+
)
2345+
for finding in findings:
2346+
finding.start_line = finding.end_line = 1
2347+
finding.start_column = finding.end_column = None
2348+
finding.evidence["oms_projection"] = (
2349+
"Decoded content in the original DSSE bundle; line 1 identifies the carrier."
2350+
)
2351+
finding.evidence[_SOURCE_START_EVIDENCE] = projection.view.source_offset(0)
2352+
finding.evidence.pop(_SOURCE_END_EVIDENCE, None)
2353+
return findings, reason, metrics
23162354
ast_modules = [module for module in pattern_modules if _uses_python_ast(module)]
23172355
lexical_modules = [module for module in pattern_modules if not _uses_python_ast(module)]
23182356
if python_source is None:

‎src/skillspector/nodes/build_context.py‎

Lines changed: 44 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
is_executable_content,
7777
is_zip_content,
7878
)
79+
from skillspector.oms import project_oms_content
7980
from skillspector.python_ast import (
8081
PythonSourceClassification,
8182
classify_python_source,
@@ -908,7 +909,7 @@ def _decode_base64_json(value: object) -> dict[str, object] | None:
908909

909910

910911
def _is_valid_oms_signature_bytes(data: bytes) -> bool:
911-
"""Recognize the minimal OMS DSSE/in-toto structure from bounded bytes."""
912+
"""Recognize OMS structure only; this does not verify or trust its contents."""
912913
try:
913914
if len(data) > MAX_FILE_BYTES:
914915
return False
@@ -2897,16 +2898,7 @@ def _record_processing_runtime(*, phase: str, path: str, now: float) -> None:
28972898
elif signature_valid:
28982899
recognized_oms_signature_paths.add(_OMS_SIGNATURE_PATH)
28992900
recognized_oms_signatures = frozenset(recognized_oms_signature_paths)
2900-
signature_events = [
2901-
ledger_event(
2902-
outcome=LedgerOutcome.OUT_OF_SCOPE,
2903-
record_type=LedgerRecordType.SCOPE_BOUNDARY,
2904-
phase="discovery",
2905-
path=path,
2906-
reason=LedgerReason.OMS_SIGNATURE,
2907-
)
2908-
for path in sorted(recognized_oms_signatures)
2909-
]
2901+
signature_events: list[InspectionLedgerEvent] = []
29102902
baseline_events = [
29112903
ledger_event(
29122904
outcome=LedgerOutcome.OUT_OF_SCOPE,
@@ -2917,12 +2909,6 @@ def _record_processing_runtime(*, phase: str, path: str, now: float) -> None:
29172909
)
29182910
for path in sorted(selected_baselines)
29192911
]
2920-
for artifact in artifact_inventory:
2921-
if artifact["path"] in recognized_oms_signatures:
2922-
artifact["disposition"] = ArtifactDisposition.OUT_OF_SCOPE
2923-
artifact["reason"] = LedgerReason.OMS_SIGNATURE.value
2924-
llm_file_cache.pop(artifact["path"], None)
2925-
29262912
primary_path = next(
29272913
(path for path in ("SKILL.md", "skill.md") if path in inventoried_components), None
29282914
)
@@ -3090,8 +3076,6 @@ def _record_processing_runtime(*, phase: str, path: str, now: float) -> None:
30903076
ordinary_components: list[str] = []
30913077
for path in cache_candidates:
30923078
ordinary_artifact = inventory_by_path.get(path)
3093-
if path in recognized_oms_signatures:
3094-
continue
30953079
if path in raw_file_cache or (
30963080
ordinary_artifact is not None
30973081
and ordinary_artifact.get("disposition")
@@ -3474,7 +3458,7 @@ def mark_excluded_nested_metadata(
34743458
]
34753459
)
34763460
)
3477-
for path in [*recognized_containers, *recognized_oms_signatures]:
3461+
for path in recognized_containers:
34783462
llm_file_cache.pop(path, None)
34793463

34803464
postprocessing_events: list[InspectionLedgerEvent] = []
@@ -3647,6 +3631,46 @@ def _mark_runtime_partial(affected_paths: list[str], first_limited_path: str) ->
36473631
)
36483632
)
36493633

3634+
for path, content in local_file_cache.items():
3635+
if not content.lstrip().startswith("{"):
3636+
continue
3637+
projection_started = monotonic()
3638+
if projection_started >= processing_deadline:
3639+
_record_processing_runtime(
3640+
phase="signature_projection", path=path, now=projection_started
3641+
)
3642+
continue
3643+
projection = project_oms_content(content)
3644+
if projection is None:
3645+
continue
3646+
projection_finished = monotonic()
3647+
if projection_finished >= processing_deadline:
3648+
_record_processing_runtime(
3649+
phase="signature_projection", path=path, now=projection_finished
3650+
)
3651+
continue
3652+
artifact = inventory_by_path.get(path)
3653+
bounded_provider_view = artifact is not None and (
3654+
artifact.get("disposition") == ArtifactDisposition.PARTIAL
3655+
and artifact.get("reason")
3656+
in {LedgerReason.SIZE_LIMIT.value, LedgerReason.TOTAL_BYTES_LIMIT.value}
3657+
)
3658+
if path in llm_file_cache and projection.view.name != "raw" and not bounded_provider_view:
3659+
llm_file_cache[path] = projection.view.text
3660+
if not projection.complete:
3661+
signature_events.append(
3662+
ledger_event(
3663+
outcome=LedgerOutcome.PARTIAL,
3664+
record_type=LedgerRecordType.SYSTEM,
3665+
phase="discovery",
3666+
path=path,
3667+
reason=LedgerReason.OMS_SIGNATURE,
3668+
)
3669+
)
3670+
if artifact is not None and artifact["disposition"] == ArtifactDisposition.ANALYZED:
3671+
artifact["disposition"] = ArtifactDisposition.PARTIAL
3672+
artifact["reason"] = LedgerReason.OMS_SIGNATURE.value
3673+
36503674
llm_components = sorted(llm_file_cache)
36513675
file_cache = dict(llm_file_cache)
36523676
manifest_events: list[InspectionLedgerEvent] = []

0 commit comments

Comments
 (0)