Skip to content

Commit 73dd1f1

Browse files
authored
Security fixes (#393)
Signed-off-by: Narendran Raghavan <[email protected]>
1 parent c94b50a commit 73dd1f1

93 files changed

Lines changed: 27597 additions & 2864 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ SkillSpector is part of the [NVIDIA Verified Skills pipeline](https://docs.nvidi
1818

1919
- **[Scan agent skills before installation](https://docs.nvidia.com/skills/scanning-agent-skills)** — Hosted guide: when to scan, how to read a report, and how to gate installs.
2020
- **[Development guide](docs/DEVELOPMENT.md)** — Architecture, package layout, and how to extend the analyzer pipeline.
21+
- **[Analysis resource bounds](docs/ANALYSIS_RESOURCE_BOUNDS.md)** — Fail-closed bundle, parser, nested-artifact, ledger, and finding ceilings.
2122
- **[Pi extension](docs/PI_EXTENSION.md)** — Install SkillSpector as a Pi tool for scanning skills from inside agent sessions.
2223

2324
## Features

‎docs/ANALYSIS_RESOURCE_BOUNDS.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Analysis Resource Bounds
2+
3+
SkillSpector applies deterministic resource ceilings to untrusted skill bundles. A ceiling is a
4+
safety boundary, not an allowlist and not evidence that the portion examined was clean. When a
5+
relevant ceiling is reached, the scanner records the limitation and reports partial analysis.
6+
7+
Values below are implementation defaults. MiB means 1,048,576 bytes.
8+
9+
## Bundle discovery and materialization
10+
11+
| Resource | Ceiling | Scope |
12+
|---|---:|---|
13+
| Discovered entries | 10,000 | One skill bundle |
14+
| Entries materialized from one directory | 10,000 | One directory |
15+
| Filesystem traversal depth | 64 | One skill bundle |
16+
| Discovery time | 30 seconds | One skill bundle |
17+
| Canonical cached source bytes | 64 MiB | Ordinary files and expanded nested members combined |
18+
| Cached bytes from one filesystem artifact | 16 MiB | One artifact |
19+
| End-to-end workflow time | 60 seconds | One graph execution |
20+
| Cache and context-processing time | 60 seconds | One skill bundle, within the workflow deadline |
21+
22+
The 64 MiB ceiling accounts for the canonical raw bytes retained for analysis. Local decoded text
23+
and LLM-safe text are derived only from those bounded bytes; they do not authorize another source
24+
read allowance. Exact raw bytes from readable nested members consume the remaining portion of the
25+
same 64 MiB budget. The byte ceiling is an input-accounting limit, not a promise that Python object
26+
overhead or decoded Unicode storage occupies exactly the same amount of memory.
27+
28+
Files larger than 16 MiB receive a bounded local projection and a `partial` inventory disposition.
29+
They are not sent to an external model. Lexical static analysis uses 256,000-character windows with
30+
an 8,192-character overlap. Unicode-derived security views are re-sliced to the same ceiling before
31+
pattern modules receive them. Whole-file Python AST analysis is limited to 1,000,000 characters, and
32+
the shared parsed-AST cache retains at most 8,000,000 source characters per scan.
33+
34+
## Nested containers
35+
36+
Archive inspection shares the bundle's remaining artifact, byte, and processing-time allowances.
37+
Its additional ceilings are:
38+
39+
| Resource | Ceiling | Scope |
40+
|---|---:|---|
41+
| Recursion depth | 3 | One outer-to-inner provenance chain |
42+
| Members | 1,000 | All outer and nested containers combined |
43+
| Expanded bytes | 25 MiB | All outer and nested containers combined |
44+
| Central-directory bytes | 4 MiB | One container, before ZIP metadata allocation |
45+
| Materialized member | 1,000,000 bytes | One member |
46+
| Compression ratio | 100:1 | One member |
47+
| Archive-inspection time | 5 seconds | All outer and nested containers combined |
48+
49+
The effective member and expanded-byte ceilings are the smaller of these values and the enclosing
50+
bundle's remaining allowances. EOCD and ZIP64 metadata, declared counts, central-directory bytes,
51+
and actual central headers are checked before ZIP metadata objects are created. See
52+
[Nested Artifact Inspection](NESTED_ARTIFACT_INSPECTION.md) for provenance and containment rules.
53+
54+
## Manifest YAML
55+
56+
Only a bounded primary `SKILL.md` frontmatter prefix is eligible for YAML parsing:
57+
58+
| Resource | Ceiling |
59+
|---|---:|
60+
| Frontmatter bytes | 256 KiB |
61+
| YAML nodes | 10,000 |
62+
| YAML nesting depth | 64 |
63+
| Projected manifest records | 1,024 |
64+
| Projected manifest characters | 256 KiB |
65+
| Manifest parse time | 1 second |
66+
67+
The closing frontmatter delimiter must be present inside the bounded prefix. Node, depth, projected
68+
output, and time limits are checked before the bounded document is accepted. YAML aliases are
69+
charged for each projected occurrence, so a compact alias graph cannot amplify the returned
70+
manifest past these limits. A malformed or incomplete claimed frontmatter leaves the manifest
71+
empty, marks the primary artifact `partial`, and records an allowlisted parse error or limit reason.
72+
73+
## Intra-bundle references
74+
75+
Reference extraction from the primary instructions is independently bounded:
76+
77+
| Resource | Ceiling |
78+
|---|---:|
79+
| Source bytes examined | 1,000,000 |
80+
| Raw candidates considered | 4,096 |
81+
| Accepted references | 256 |
82+
| Output records | 1,024 |
83+
| Extraction time | 2 seconds |
84+
85+
Truncated extraction and missing or ambiguous local references are explicit partial-coverage
86+
conditions. A referenced binary, opaque, or otherwise uninspected artifact is not treated as a
87+
successfully analyzed reference.
88+
89+
## Structured skill data
90+
91+
AISOP/AISP structured extraction consumes the already-bounded cache and shares the enclosing
92+
processing deadline. It does not start a second unbounded filesystem traversal.
93+
94+
| Resource | Ceiling | Scope |
95+
|---|---:|---|
96+
| Candidate documents | 64 | One extraction |
97+
| Bytes per document | 256 KiB | One candidate |
98+
| Total structured input | 1 MiB | One extraction |
99+
| Parsed nesting depth | 64 | One extraction |
100+
| Parsed nodes | 4,096 | One extraction |
101+
| Output records | 512 | One extraction |
102+
| Extraction time | 2 seconds | One extraction, constrained by the bundle deadline |
103+
104+
## Recursive and transitive scans
105+
106+
Pre-scan recursive discovery uses bounded `scandir` traversal and does not construct YAML merely to
107+
obtain a display name.
108+
109+
| Resource | Ceiling | Scope |
110+
|---|---:|---|
111+
| Recursive discovery entries | 10,000 | One invocation |
112+
| Recursive entries retained for sorting | 1,024 | One directory |
113+
| Recursive structured candidates | 1,024 | One invocation |
114+
| Recursive structured candidate bytes | 16 MiB | One invocation |
115+
| Recursive discovery time | 2 seconds | One invocation |
116+
| Recursive skills scanned | 32 | One invocation |
117+
| Recursive public finding/occurrence records | 10,000 | One combined report |
118+
| Recursive serialized report characters | 4 Mi characters | One combined report |
119+
120+
All recursively scanned roots share the same artifact, byte, and workflow deadline rather than
121+
receiving a fresh allowance per child. If discovery or scanning reaches a ceiling, the arbitrary
122+
partial skill list is discarded or the unscanned suffix is represented by one sanitized omitted-
123+
scope record. The aggregate JSON, Markdown, and SARIF projections carry partial completeness.
124+
125+
Transitive external-reference scanning adds the following shared ceilings. Root and dependency
126+
work consume the same allowance.
127+
128+
| Resource | Ceiling | Scope |
129+
|---|---:|---|
130+
| External targets | 32 | One traversal |
131+
| Downloaded and cached source bytes | 10 MiB | Root and dependencies combined |
132+
| Discovered and expanded artifacts | 10,000 | Root and dependencies combined |
133+
| Traversal time | 60 seconds | Root and dependencies combined |
134+
| Reference source records | 1,024 | One extraction |
135+
| Reference source bytes | 1,000,000 | One extraction |
136+
| Raw reference candidates | 4,096 | One extraction |
137+
| Accepted references | 256 | One extraction |
138+
| Frontier references | 4,096 | One traversal |
139+
140+
Reference extraction uses the bounded local deterministic cache, including locally inspected hidden
141+
and nested content. Each dependency receives an opaque content-bound identity; display URLs remain
142+
separate from finding, suppression, risk, and SARIF identity. A root baseline cannot glob-suppress a
143+
dependency finding before that provenance is attached.
144+
145+
Remote Git materialization treats partial-clone filters as hints, not enforcement. While Git is
146+
running, SkillSpector repeatedly measures the bounded clone tree, terminates the process when its
147+
entry, byte, or deadline ceiling is crossed, discards subprocess output instead of buffering it, and
148+
removes the rejected partial checkout.
149+
150+
## Ledger, analyzer, and finding output
151+
152+
| Resource | Ceiling | Scope |
153+
|---|---:|---|
154+
| Inspection-ledger events | 10,000 | One graph execution |
155+
| Build-context ledger events | 10,000 | One bundle context |
156+
| Static findings | 10,000 | One artifact |
157+
| Static findings | 10,000 | One analyzer |
158+
| Static-analysis time | 30 seconds | One artifact |
159+
| YARA rule-directory entries | 10,000 | Built-in and optional directories combined |
160+
| YARA rule files | 1,024 | One rule load |
161+
| YARA rule source bytes | 1 MiB | One rule file |
162+
| YARA rule source bytes | 16 MiB | One rule load |
163+
| YARA rule active processing time | 5 seconds | One rule load, within the workflow wall-clock deadline |
164+
| Retained YARA string instances | 4,096 | One matched rule |
165+
| Shipped-bytecode discovery entries | 10,000 | One analyzer execution |
166+
| Shipped-bytecode traversal depth | 64 | One analyzer execution |
167+
| Shipped-bytecode analysis time | 5 seconds | One analyzer execution, within the workflow deadline |
168+
| Dependency manifests | 64 | One analyzer execution |
169+
| Dependency packages | 256 | One manifest |
170+
| Dependency packages | 1,024 | One analyzer execution |
171+
| Dependency findings | 2,048 | One analyzer execution |
172+
| Dependency analysis time | 30 seconds | One analyzer execution, within the workflow deadline |
173+
| OSV packages / query batches / detail requests | 256 / 4 / 64 | One dependency analysis budget |
174+
| OSV response bytes / retained results | 4 MiB / 256 | One dependency analysis budget |
175+
| TP4 source files / batches / findings | 128 / 64 / 64 | One analyzer execution |
176+
| TP4 source and prompt input | 4 MiB each | One analyzer execution |
177+
| TP4 model input | 32,000 tokens | One batch |
178+
| Public finding and occurrence records | 10,000 | One report |
179+
180+
Ledger and public finding/occurrence truncation reserve an explicit `output_limit` record. The public
181+
record cap is applied after severity-ordered deduplication; risk scoring still considers all retained
182+
active findings before report output is bounded. Reaching an output ceiling therefore cannot silently
183+
turn a truncated result into a complete result. Findings already produced by deterministic analyzers
184+
remain primary evidence; optional semantic analysis may enrich them but does not select them out. If
185+
the projection ceiling is reached, the severity-ordered bounded output and its explicit
186+
`output_limit` record apply.
187+
188+
The shared static runner guards both findings constructed inside a pattern module and findings
189+
emitted by returned iterables, so a module cannot first materialize an attacker-sized private list
190+
and rely on later report truncation. Runtime is checked before and after trusted module calls and
191+
during finding construction/emission. YARA uses its engine timeout and fast match mode, applies the
192+
same per-artifact and per-analyzer finding ceilings, and bounds retained string instances per rule.
193+
An overrun is nonfatal incomplete work rather than a clean scan or an execution crash.
194+
195+
## Fail-closed partial behavior
196+
197+
Resource-limit events carry an allowlisted reason and the applicable observed and limit values.
198+
Affected inventory rows become `partial`, `failed`, or opaque as appropriate. Finalization exposes
199+
the result through `analysis_completeness`, including coverage counts, ledger exceptions, analyzer
200+
statuses, references, and limitations.
201+
202+
When relevant analysis is incomplete:
203+
204+
- A recommendation that would otherwise be `SAFE` is raised to at least `CAUTION`.
205+
- Terminal, JSON, Markdown, and SARIF reports expose the incomplete status and its bounded reason.
206+
- `skillspector scan --fail-on-incomplete` exits with status 1. Without this option, the CLI retains
207+
its compatibility behavior and still applies its ordinary risk-score exit policy. Execution
208+
failures exit with status 2.
209+
- MCP responses set `safe_to_install` to `false` when analysis is incomplete, any relevant file is
210+
entirely uninspected, execution failed, or the risk score exceeds the installation threshold.
211+
212+
A low score or zero findings must not be interpreted as complete coverage when
213+
`analysis_completeness.is_complete` is false.

‎docs/NESTED_ARTIFACT_INSPECTION.md‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,26 +23,45 @@ outer-file!/nested.zip!/scripts/setup.sh
2323

2424
## Cumulative bounds
2525

26-
The following fixed limits apply to one outer container and every nested container below it:
26+
Archive inspection uses one shared budget for the whole skill bundle. Opening another outer
27+
container does not reset the member, expanded-byte, or time budget. The bundle scanner may pass a
28+
smaller remaining artifact or byte allowance, and its deadline always takes precedence.
2729

28-
| Bound | Limit |
29-
|---|---:|
30-
| Container depth | 3 |
31-
| Members | 1,000 |
32-
| Declared/uncompressed content | 25 MiB |
33-
| Materialized member | 1 MiB |
34-
| Compression ratio | 100:1 |
35-
| Inspection wall time | 5 seconds |
30+
| Bound | Limit | Scope |
31+
|---|---:|---|
32+
| Container depth | 3 | One outer-to-inner provenance chain |
33+
| Members | 1,000 | All outer and recursively nested containers combined |
34+
| Expanded member bytes | 25 MiB | All outer and recursively nested containers combined |
35+
| Central directory | 4 MiB | Each container, checked before creating ZIP metadata objects |
36+
| Materialized member | 1,000,000 bytes | Each member |
37+
| Compression ratio | 100:1 | Each member |
38+
| Inspection wall time | 5 seconds | All outer and recursively nested containers combined |
39+
40+
The 1,000-member and 25 MiB ceilings are also reduced to the bundle scanner's remaining
41+
10,000-artifact and 64 MiB canonical-byte budgets. Nested members therefore cannot obtain a fresh
42+
allowance after ordinary files have consumed part of the bundle budget.
43+
44+
Before Python's ZIP reader is invoked, SkillSpector validates the terminal EOCD or ZIP64 records,
45+
the declared central-directory count and byte size, and the actual sequence of central-directory
46+
headers. This preflight prevents a forged entry count from causing an unbounded metadata list.
47+
Already-bounded outer bytes are reused from the bundle cache instead of being read a second time.
3648

3749
These are resource-safety limits, not trust configuration. They are intentionally not user-managed
38-
allowlists.
50+
allowlists. See [Analysis Resource Bounds](ANALYSIS_RESOURCE_BOUNDS.md) for the enclosing bundle,
51+
parser, ledger, and finding ceilings.
3952

4053
## Failure and completeness behavior
4154

4255
Malformed, encrypted, truncated, unreadable, unsafe-path, link, unsupported, and over-budget
43-
members are recorded as inspection-ledger exceptions. The scan continues safely when possible, but
44-
the analysis is marked incomplete. Outer and nested paths remain visible in terminal, JSON,
45-
Markdown, and SARIF output.
56+
members are recorded as inspection-ledger exceptions. Readable members retain their exact raw
57+
bytes and a local-only decoded view. Unreadable members retain an opaque inventory record with a
58+
`partial` or `failed` disposition; they are never represented as successfully analyzed.
59+
60+
The scan continues safely when possible, but any relevant omitted or partially inspected content
61+
makes the analysis incomplete. A result that would otherwise be `SAFE` is reported as at least
62+
`CAUTION`; the MCP verdict sets `safe_to_install` to `false`. CLI users can make incomplete analysis
63+
a failing gate with `--fail-on-incomplete`. Inspection exceptions and their affected outer or nested
64+
paths are surfaced in terminal, JSON, Markdown, and SARIF output.
4665

4766
## SC9: Concealed Executable Artifact
4867

0 commit comments

Comments
 (0)