Skip to main content
The pre-scanner runs on the source text before the JavaScript parser (acorn) sees it, so that the parser is not handed input that could exhaust it: text that is too large, nested too deep, or made of very long lines and strings. Depending on the preset it also checks regular-expression literals and Unicode characters.

Basic Usage

PreScanner takes a preset name and, optionally, overrides of single settings:
The constructor takes { preset, config }. Without a preset it uses standard. In particular new PreScanner(createPreScannerConfig('agentscript')) does not select the AgentScript preset: a configuration object passed in the place of the options has no preset key, so the scanner is built with standard. Pass { preset: 'agentscript' }, or use PreScanner.forAgentScript().
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
Pre-scanning refuses these before parsing begins.

Where It Runs

  • JSAstValidator.validate() runs the pre-scanner first, by default with the standard preset, whatever rules or rule preset the validator was built with. Select another pre-scanner preset per validation with the preScan option, or switch the pre-scan off:
  • Enclave (@enclave-vm/core) and BrowserEnclave (@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: agentscript by default (the babel preset of the core enclave runs with standard). Their preScan option picks another preset or changes single limits: new Enclave({ preScan: { preset: 'standard' } }), new Enclave({ preScan: { config: { maxInputSize: 1024 * 1024 } } }). With validate: false the pre-scanner does not run.

Mandatory Limits

No configuration can raise a limit above these maxima. A limit given through config (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:
In this mode the number of regex literals and the length of each are limited as well (10 of 100 chars for strict, 20 of 200 for secure, 30 of 500 for standard).

Allow Mode

Allow all regex without analysis (Permissive only):

ReDoS Detection

In analyze 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

With unicodePreCheck 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)

With blockBidiPatterns (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

With blockInvisibleChars (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

Whenever unicodePreCheck 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 in config, 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: