Scan forward (truncated / unseekable streams — NOT authoritative)
scan_zip_forwardScan ZIP local headers in stream order with bounded memory to inventory truncated or mid-stream archives; use tolerateTruncation for partial forensic results when the central directory is missing.
Instructions
Walk LOCAL headers in stream order with bounded memory (zipnative's central-directory-less reader). The only tool that works on a truncated archive or a stream cut mid-way (it cannot skip an SFX prefix: the stream must start at a local header) — and the only one whose result is NOT authoritative: forward iteration trusts local headers ALONE, so a hostile archive can present different content here than inspect_zip / list_zip_entries report (the upload-scanner differential). Prefer those tools whenever the whole archive is available; use this one for forensics (tolerateTruncation:true returns the partial inventory + error). data 'none' skips payloads, 'verify' decompresses to check CRCs, 'include' returns them (inline caps). stoppedAt tells you whether a central directory was reached. Names are NOT sanitized — sanitizedPath shows what the extraction gate would use.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "scan_zip_forward"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | 'none' (default): skip payloads (a data-descriptor entry still costs a full decompress-and-discard); 'verify': decompress every kept entry so CRC and sizes are checked; 'include': also return the content as base64 (inline caps apply). | none |
| fields | No | Dot-paths to keep, after verbosity (e.g. ['entryCount', 'entries.name']); unmatched ones are listed in _meta.unmatchedFields. | |
| filter | No | Select entries: `names` (exact), `prefix`, `glob` (`*` in a segment, `**` across, `?`, `[a-z]`; no `/` = any depth, trailing `/` = subtree), ANDed; `includeDirectories` (default false). | |
| limits | No | Per-call override of zipnative's security bounds (CWE-400/409); absent keys keep the engine defaults (describe_engine.defaultLimits). A value above its operator ceiling is LIMIT_CEILING_EXCEEDED. Raise only for trusted input. | |
| strict | No | Turn the first engine diagnostic into a ZIP_STRICT_DIAGNOSTIC error. | |
| zipPath | No | Archive path relative to the ZIPNATIVE_MCP_OUTPUT_DIR sandbox (container extensions: .zip .jar .docx .epub …). Exclusive with zipBase64; saves re-sending bytes between calls. | |
| verbosity | No | 'summary': scalar verdict fields only (the token-frugal form). | full |
| zipBase64 | No | Archive bytes, base64 (≤ 128 MiB decoded). Exclusive with zipPath. | |
| maxEntries | No | Stop after this many local headers (bounded work on an unbounded stream). Default 10000, clamped to the operator ceiling ZIPNATIVE_MCP_MAX_ENTRIES; an explicit value above the ceiling is refused (LIMIT_CEILING_EXCEEDED). | |
| tolerateTruncation | No | true: a truncated / corrupt stream ends the scan with `stoppedAt:"error"` and the partial inventory (forensics) instead of failing the call. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| names | No | summary only: the kept entry names. | |
| trust | No | Constant reminder: nothing here was cross-checked against a central directory. | |
| entries | No | ||
| keptCount | No | ||
| stoppedAt | No | 'central-directory' is the normal end of a complete archive; 'eof' means the stream ended before any central directory (truncated or CD-less); 'max-entries' means more local headers remained. | |
| truncated | No | true when the stream ended without reaching a central directory. | |
| entryCount | No | Local headers seen (before the filter). | |
| inputBytes | No | ||
| maxEntries | No | The header budget in force (after clamping to the operator ceiling). | |
| diagnostics | No | Non-fatal engine concerns (de-duplicated by code + entry, ≤ 200; codes in describe_engine.diagnosticCodes). Empty for a clean archive. | |
| bytesDelivered | No | Bytes handed to the forward reader. | |
| diagnosticCount | No | summary only: number of distinct diagnostics. | |
| diagnosticCounts | No | Occurrences per code, duplicates included. | |
| diagnosticsTruncated | No | true when rows beyond 200 were dropped. |