|
| 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. |
0 commit comments