Basic Usage
PreScanner takes a preset name and, optionally, overrides of single settings:
scan() returns:
Why Pre-Scanning?
A parser works on whatever it is given, and some inputs cost it far more than their size suggests:- Memory exhaustion - Extremely large files and string literals
- Stack overflow - Deeply nested expressions
- CPU exhaustion - Very long lines, and regular expressions that backtrack
Where It Runs
-
JSAstValidator.validate()runs the pre-scanner first, by default with thestandardpreset, whatever rules or rule preset the validator was built with. Select another pre-scanner preset per validation with thepreScanoption, or switch the pre-scan off: -
Enclave(@enclave-vm/core) andBrowserEnclave(@enclave-vm/browser) run the pre-scanner themselves, on the script as it was written and before anything parses it, with the pre-scanner preset named like their AST preset:agentscriptby default (thebabelpreset of the core enclave runs withstandard). TheirpreScanoption picks another preset or changes single limits:new Enclave({ preScan: { preset: 'standard' } }),new Enclave({ preScan: { config: { maxInputSize: 1024 * 1024 } } }). Withvalidate: falsethe pre-scanner does not run.
Mandatory Limits
No configuration can raise a limit above these maxima. A limit given throughconfig (or createPreScannerConfig) that is higher is lowered to the maximum:
A null byte in the source is refused by every preset.
Pre-Scanner Presets
Using Presets
preScan(source, preset?) scans once without creating a scanner, and isPreScanValid(source, preset?) runs only the size, Unicode and nesting checks and returns a boolean.
Regex Handling Modes
The pre-scanner supports three regex handling modes:Block Mode
Block ALL regex literals (AgentScript default, maximum security):Analyze Mode
Allow regex literals but analyze them for ReDoS patterns:strict, 20 of 200 for secure, 30 of 500 for standard).
Allow Mode
Allow all regex without analysis (Permissive only):ReDoS Detection
Inanalyze mode each regex literal gets a score from 0 to 100. A score of 80 or more fails the scan; a score from 50 to 79 is reported as a warning and the scan goes on.
The last two rows are looked for only at the analysis level
polynomial, which the standard preset uses; strict and secure use catastrophic. The analysis is a set of heuristics over the text of a pattern: it finds the common shapes of a backtracking pattern, not every one.
Manual ReDoS Analysis
@enclave-vm/ast/redos exports the analyzer on its own: it loads none of the parser (acorn, acorn-walk, astring) that the package root loads. The package root exports the same functions.
Unicode Security
WithunicodePreCheck on (every preset except permissive), the pre-scanner runs up to three checks on the whole source text, string literals and comments included:
Bidirectional Text (Trojan Source)
WithblockBidiPatterns (on in agentscript, strict and secure), a bidirectional control character (U+202A to U+202E, U+2066 to U+2069) fails the scan. These characters can make code look different from what it does.
Invisible Characters
WithblockInvisibleChars (on in agentscript and strict), zero-width and other invisible characters are reported: up to three as a warning, more than three fail the scan. A byte-order mark at the very start is allowed.
Look-Alike Letters
WheneverunicodePreCheck is on, a letter from a fixed list of look-alikes of ASCII letters fails the scan: the Cyrillic а, е, о, р, с, х, у, the Greek α and ο, and the full-width a and e. The check is on the whole text, so it also refuses these letters in a string literal. It is the one Unicode check of the standard preset.
Custom Configuration
Overrides go inconfig, on top of a preset:
createPreScannerConfig(preset, overrides) returns the merged configuration object (with the limits clamped to the mandatory maxima), for inspection or to pass as config:
Related
- Overview - Getting started with ast-guard
- AgentScript Preset - LLM code validation
- Security Rules - AST validation rules