Pre-Scanner

The pre-scanner runs BEFORE the JavaScript parser (acorn) to catch DoS attacks that could crash or hang the parser itself. It enforces mandatory security limits that cannot be disabled.

Basic Usage

import { PreScanner, createPreScannerConfig } from '@enclave-vm/ast';

// Create pre-scanner with AgentScript config (strictest)
const scanner = new PreScanner(createPreScannerConfig('agentscript'));

const result = scanner.scan(userCode);
if (!result.valid) {
  console.log('Pre-scan failed:', result.issues);
  // Don't even attempt to parse - could DoS the parser
}

Why Pre-Scanning?

The JavaScript parser itself can be vulnerable to:

Memory exhaustion - Extremely large files
Stack overflow - Deeply nested expressions
CPU exhaustion - Complex regex patterns
Parsing hangs - Malformed Unicode sequences

Pre-scanning catches these before parsing begins.

Mandatory Limits

These limits protect against parser crashes and cannot be overridden:

Limit	Maximum	Purpose
`ABSOLUTE_MAX_INPUT_SIZE`	100MB	Prevents memory exhaustion
`ABSOLUTE_MAX_NESTING`	200 levels	Prevents parser stack overflow
`ABSOLUTE_MAX_LINE_LENGTH`	100,000 chars	Prevents minified/obfuscated DoS
`ABSOLUTE_MAX_LINES`	1,000,000	Prevents extremely long files
`ABSOLUTE_MAX_STRING`	5MB	Prevents huge embedded strings
`ABSOLUTE_MAX_REGEX_LENGTH`	1,000 chars	Prevents ReDoS via complex patterns

Pre-Scanner Presets

Config	AgentScript	STRICT	SECURE	STANDARD	PERMISSIVE
maxInputSize	100KB	500KB	1MB	5MB	10MB
maxLineLength	2,000	5,000	8,000	10,000	50,000
maxLines	1,000	2,000	5,000	10,000	100,000
maxNestingDepth	20	30	40	50	100
regexMode	`block`	`analyze`	`analyze`	`analyze`	`allow`
blockBidiPatterns	YES	YES	YES	NO	NO
blockInvisibleChars	YES	YES	NO	NO	NO

Using Presets

import { createPreScannerConfig, PreScanner } from '@enclave-vm/ast';

// AgentScript (strictest)
const agentScript = new PreScanner(createPreScannerConfig('agentscript'));

// Other presets
const strict = new PreScanner(createPreScannerConfig('strict'));
const secure = new PreScanner(createPreScannerConfig('secure'));
const standard = new PreScanner(createPreScannerConfig('standard'));
const permissive = new PreScanner(createPreScannerConfig('permissive'));

Regex Handling Modes

The pre-scanner supports three regex handling modes:

Block Mode

Block ALL regex literals (AgentScript default, maximum security):

const scanner = new PreScanner(createPreScannerConfig('agentscript'));
// regexMode: 'block'

// This will fail:
scanner.scan('const pattern = /foo/;');

Analyze Mode

Allow regex but analyze for ReDoS patterns:

const scanner = new PreScanner(createPreScannerConfig('secure'));
// regexMode: 'analyze'

// Safe patterns allowed:
scanner.scan('const pattern = /^[a-z]+$/;'); // OK

// Dangerous patterns blocked:
scanner.scan('const evil = /(a+)+/;'); // Blocked - nested quantifier

Allow Mode

Allow all regex without analysis (Permissive only):

const scanner = new PreScanner(createPreScannerConfig('permissive'));
// regexMode: 'allow'

// All regex allowed (not recommended for untrusted code)
scanner.scan('const pattern = /(a+)+/;'); // OK

ReDoS Detection

The pre-scanner detects dangerous regex patterns that cause exponential backtracking:

Pattern	Score	Example	Risk
Nested quantifier	90	`(a+)+`	Exponential backtracking
Star in repetition	85	`(a+){2,}`	Exponential backtracking
Repetition in star	85	`(a{2,})+`	Exponential backtracking
Overlapping alternation	80	`(a\|ab)+`	Exponential backtracking
Greedy backtracking	75	`(.*a)+`	Polynomial backtracking
Multiple greedy	70	`.foo.bar`	Polynomial backtracking

Manual ReDoS Analysis

import { analyzeForReDoS } from '@enclave-vm/ast';

// Analyze a pattern for ReDoS vulnerabilities
const result = analyzeForReDoS('(a+)+', 'catastrophic');
// {
//   vulnerable: true,
//   score: 90,
//   vulnerabilityType: 'nested_quantifier'
// }

Unicode Security

The pre-scanner detects Unicode-based attacks:

Bidirectional Text (Trojan Source)

const scanner = new PreScanner({
  ...createPreScannerConfig('secure'),
  blockBidiPatterns: true,
});

// Blocks code with BiDi control characters that can
// make code appear different than it executes

Invisible Characters

const scanner = new PreScanner({
  ...createPreScannerConfig('strict'),
  blockInvisibleChars: true,
});

// Blocks zero-width spaces, invisible formatting, etc.

Custom Configuration

const scanner = new PreScanner({
  maxInputSize: 200 * 1024,    // 200KB
  maxLineLength: 3000,
  maxLines: 2000,
  maxNestingDepth: 25,
  regexMode: 'analyze',
  blockBidiPatterns: true,
  blockInvisibleChars: true,
});

Overview - Getting started with ast-guard
AgentScript Preset - LLM code validation
Security Rules - AST validation rules

Get Started

Concepts

@enclave-vm/core

@enclave-vm/browser

@enclave-vm/ast

EnclaveJS Streaming

Guides

Examples

Troubleshooting

Basic Usage

Why Pre-Scanning?

Mandatory Limits

Pre-Scanner Presets

Using Presets

Regex Handling Modes

Block Mode

Analyze Mode

Allow Mode

ReDoS Detection

Manual ReDoS Analysis

Unicode Security

Bidirectional Text (Trojan Source)

Invisible Characters

Custom Configuration

​Basic Usage

​Why Pre-Scanning?

​Mandatory Limits

​Pre-Scanner Presets

​Using Presets

​Regex Handling Modes

​Block Mode

​Analyze Mode

​Allow Mode

​ReDoS Detection

​Manual ReDoS Analysis

​Unicode Security

​Bidirectional Text (Trojan Source)

​Invisible Characters

​Custom Configuration

​Related

Basic Usage

Why Pre-Scanning?

Mandatory Limits

Pre-Scanner Presets

Using Presets

Regex Handling Modes

Block Mode

Analyze Mode

Allow Mode

ReDoS Detection

Manual ReDoS Analysis

Unicode Security

Bidirectional Text (Trojan Source)

Invisible Characters

Custom Configuration

Related