Inspect concealed executables in nested artifacts

Author: rng1995

CHANGELOG.md

@@ -1,3 +1,8 @@
+### Unreleased
+### Features/Bug Fixes
+* Inspect hidden and nested ZIP-compatible artifacts under cumulative safety bounds.
+* Report HIGH SC9 findings for executables concealed in documents or hidden/disguised artifacts.
+---
 ### 2.9.5 (Friday, August 14, 2026)
 ### Features/Bug Fixes
 * Scope the locality guard to the namespace (#365)

README.md

@@ -23,7 +23,7 @@ SkillSpector is part of the [NVIDIA Verified Skills pipeline](https://docs.nvidi
 ## Features
 
 - **Multi-format input**: Scan Git repos, URLs, zip files, directories, or single files
-- **69 vulnerability patterns** across 17 categories: prompt injection, data exfiltration, privilege escalation, supply chain, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, anti-refusal, trigger abuse, dangerous code (AST), taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning
+- **70 vulnerability patterns** across 17 categories: prompt injection, data exfiltration, privilege escalation, supply chain, excessive agency, output handling, system prompt leakage, memory poisoning, tool misuse, rogue agent, anti-refusal, trigger abuse, dangerous code (AST), taint tracking, YARA signatures, MCP least privilege, and MCP tool poisoning
 - **Two-stage analysis**: Fast static analysis + optional LLM semantic evaluation
 - **Live vulnerability lookups**: SC4 queries [OSV.dev](https://osv.dev) for real-time CVE data with automatic offline fallback
 - **Multiple output formats**: Terminal, JSON, Markdown, and SARIF reports
@@ -353,7 +353,7 @@ claude mcp add skillspector -- skillspector mcp
 
 ## Vulnerability Patterns
 
-SkillSpector detects **69 vulnerability patterns** across 17 categories:
+SkillSpector detects **70 vulnerability patterns** across 17 categories:
 
 ### Prompt Injection (6 patterns)
 
@@ -391,7 +391,7 @@ SkillSpector detects **69 vulnerability patterns** across 17 categories:
 | PE2 | Sudo/Root Execution | MEDIUM | Invoking elevated system privileges |
 | PE3 | Credential Access | HIGH | Reading SSH keys, tokens, passwords |
 
-### Supply Chain (7+ patterns)
+### Supply Chain (9+ patterns)
 
 | ID | Pattern | Severity | Description |
 |----|---------|----------|-------------|
@@ -402,6 +402,7 @@ SkillSpector detects **69 vulnerability patterns** across 17 categories:
 | SC5 | Abandoned Dependencies | MEDIUM | Unmaintained packages without security updates |
 | SC6 | Typosquatting | HIGH | Package names similar to popular packages |
 | SC8 | Shipped Python Bytecode | HIGH | `__pycache__` / `.pyc` present (discovery skips; malicious bytecode bypass) |
+| SC9 | Concealed Executable Artifact | HIGH | Executable nested in a document container or hidden/disguised artifact |
 
 ### Excessive Agency (4 patterns)
 

docs/NESTED_ARTIFACT_INSPECTION.md

@@ -0,0 +1,53 @@
+# Nested Artifact Inspection
+
+SkillSpector inventories hidden regular files and inspects ZIP-compatible content locally. The
+container is recognized from its bytes and internal structure rather than its filename extension.
+Supported document containers are DOCX, XLSX, and PPTX; generic ZIP and nested ZIP-compatible
+members use the same traversal policy.
+
+Nested members use a stable virtual path that retains their full provenance:
+
+```text
+outer-file!/nested.zip!/scripts/setup.sh
+```
+
+## Security invariants
+
+- Members are read in memory. SkillSpector never extracts, renders, imports, installs, or executes
+  archive content.
+- Absolute paths, parent traversal, drive-qualified paths, and link members are not followed.
+- Hidden files, recognized containers, and all nested content are local-only and are never included
+  in an external LLM request.
+- Deterministic HIGH findings survive optional LLM meta-analysis.
+- A zero-finding result does not make opaque or uninspected content complete.
+
+## Cumulative bounds
+
+The following fixed limits apply to one outer container and every nested container below it:
+
+| Bound | Limit |
+|---|---:|
+| Container depth | 3 |
+| Members | 1,000 |
+| Declared/uncompressed content | 25 MiB |
+| Materialized member | 1 MiB |
+| Compression ratio | 100:1 |
+| Inspection wall time | 5 seconds |
+
+These are resource-safety limits, not trust configuration. They are intentionally not user-managed
+allowlists.
+
+## Failure and completeness behavior
+
+Malformed, encrypted, truncated, unreadable, unsafe-path, link, unsupported, and over-budget
+members are recorded as inspection-ledger exceptions. The scan continues safely when possible, but
+the analysis is marked incomplete. Outer and nested paths remain visible in terminal, JSON,
+Markdown, and SARIF output.
+
+## SC9: Concealed Executable Artifact
+
+SC9 is a deterministic HIGH finding when executable content is concealed inside an Office document
+container or a hidden/disguised artifact. Executability is established from an executable suffix,
+a shebang, or archive mode bits. A benign document without executable members does not produce SC9.
+
+SC9 reports evidence and risk; it does not execute the member or prescribe an installation decision.

src/skillspector/inspection_ledger.py

@@ -60,6 +60,17 @@ class LedgerReason(StrEnum):
     NO_APPLICABLE_FILES = "no_applicable_files"
     OMS_SIGNATURE = "oms_signature"
     BASELINE_FILE = "baseline_file"
+    ARCHIVE_MALFORMED = "archive_malformed"
+    ARCHIVE_ENCRYPTED = "archive_encrypted"
+    ARCHIVE_TRUNCATED = "archive_truncated"
+    ARCHIVE_UNSAFE_MEMBER_PATH = "archive_unsafe_member_path"
+    ARCHIVE_LINK_MEMBER = "archive_link_member"
+    ARCHIVE_DEPTH_LIMIT = "archive_depth_limit"
+    ARCHIVE_MEMBER_LIMIT = "archive_member_limit"
+    ARCHIVE_SIZE_LIMIT = "archive_size_limit"
+    ARCHIVE_MEMBER_SIZE_LIMIT = "archive_member_size_limit"
+    ARCHIVE_COMPRESSION_RATIO = "archive_compression_ratio"
+    ARCHIVE_TIME_LIMIT = "archive_time_limit"
 
 
 REASON_MESSAGES: Final[dict[LedgerReason, str]] = {
@@ -99,6 +110,21 @@ class LedgerReason(StrEnum):
     LedgerReason.BASELINE_FILE: (
         "The explicitly selected suppression baseline is excluded from content analysis."
     ),
+    LedgerReason.ARCHIVE_MALFORMED: "ZIP-compatible content is malformed or unsupported.",
+    LedgerReason.ARCHIVE_ENCRYPTED: "Archive member is encrypted and could not be inspected.",
+    LedgerReason.ARCHIVE_TRUNCATED: "Archive member is truncated or unreadable.",
+    LedgerReason.ARCHIVE_UNSAFE_MEMBER_PATH: (
+        "Archive member uses an absolute, traversal, or otherwise unsafe path."
+    ),
+    LedgerReason.ARCHIVE_LINK_MEMBER: "Archive link member was not followed or read.",
+    LedgerReason.ARCHIVE_DEPTH_LIMIT: "Nested archive depth limit was reached.",
+    LedgerReason.ARCHIVE_MEMBER_LIMIT: "Cumulative archive member limit was reached.",
+    LedgerReason.ARCHIVE_SIZE_LIMIT: "Cumulative archive content size limit was reached.",
+    LedgerReason.ARCHIVE_MEMBER_SIZE_LIMIT: "Archive member exceeds the per-file analysis limit.",
+    LedgerReason.ARCHIVE_COMPRESSION_RATIO: (
+        "Archive member exceeds the permitted compression ratio."
+    ),
+    LedgerReason.ARCHIVE_TIME_LIMIT: "Cumulative archive inspection time limit was reached.",
 }
 
 

src/skillspector/models.py

@@ -60,6 +60,7 @@ class AnalyzerFinding:
     tags: list[str] = field(default_factory=list)
     context: str | None = None
     matched_text: str | None = None
+    evidence: dict[str, object] = field(default_factory=dict)
 
 
 def _new_finding_id() -> str:
@@ -89,6 +90,7 @@ class Finding:
     tags: list[str] = field(default_factory=list)
     context: str | None = None
     matched_text: str | None = None
+    evidence: dict[str, object] = field(default_factory=dict)
 
     def to_dict(self) -> dict[str, object]:
         """Return a JSON-serializable dict representation (full finding shape)."""
@@ -112,6 +114,7 @@ def to_dict(self) -> dict[str, object]:
             # Tags surface markers like "llm-unconfirmed" (a high-severity static
             # finding the LLM filter did not confirm but which is preserved anyway).
             "tags": list(self.tags),
+            "evidence": dict(self.evidence),
         }
 
     def __str__(self) -> str: