Guarded script evaluator

  • Release version: Yokohama
  • Updated May 5, 2026
  • 6 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Guarded Script Evaluator

    The guarded script evaluator in ServiceNow Yokohama release enhances instance security by executing only a restricted subset of JavaScript server-side scripts that run in a sandbox environment. It supports a limited domain-specific language (DSL) with simple expressions, function calls, and certain approved APIs. This evaluation applies to untrusted server-side scripts but excludes script includes (which run outside the sandbox) and client-side scripts.

    Show full answer Show less

    The evaluator detects and rejects scripts using unsupported JavaScript features, with behavior varying based on the transaction origin (authenticated vs. guest users) and enforcement phase configured on the instance.

    Key Features

    • Restricted JavaScript Support: Only simple expressions, primitive literals, basic operators, array literals, property access, and calls to sandbox-enabled script includes are allowed.
    • Enforcement Phases for Authenticated Traffic:
      • Phase 1 - Detection: Scripts execute normally but incompatible scripts are logged and added to the Incompatible Guarded Scripts list.
      • Phase 2 - Syntax Enforcement: Scripts with incompatible syntax are rejected; scripts with incompatible APIs are detected and logged.
      • Phase 3 - Full Enforcement: All scripts with incompatible syntax or APIs are rejected; manual exemptions can be created.
    • Guest User Enforcement: Incompatible scripts from unauthenticated (guest) users are rejected immediately on all instances.
    • Automatic and Manual Exemptions: During phase transitions, automatic exemptions are created to route incompatible scripts to the script sandbox evaluator, allowing continued execution while remediation occurs.
    • Configurable Enforcement: Administrators can manage enforcement phases and durations via system properties and the GlideGuardedScript script include, allowing control over phase transitions and exemptions.
    • Logging and Script Review: The Incompatible Guarded Scripts list tracks scripts using unsupported features, enabling targeted updates or exemption management.

    Practical Guidance for ServiceNow Customers

    • Regularly review the Incompatible Guarded Scripts list to identify scripts requiring updates or exemptions, especially before advancing enforcement phases.
    • Refactor complex scripts using unsupported syntax (e.g., variables, control flow) into script includes with the Sandbox enabled option to maintain compatibility.
    • Understand that guest user scripts are strictly enforced immediately, so public-facing server-side scripts must conform to guarded script restrictions.
    • Use the provided GlideGuardedScript methods to control enforcement phase transitions on on-premise or upgraded instances that do not auto-advance.
    • Do not disable the guarded script evaluator on production instances, as this reduces security protections.
    • Test infrequently run, business-critical scripts prior to enabling full enforcement to avoid unexpected rejections.

    JavaScript Features and APIs Supported

    Supported features include:

    • Primitive literals: numbers, strings, booleans, null, undefined
    • Common operators: +, -, <, !==, &&, instanceof, typeof
    • Ternary operator (?:)
    • Array literals and indexed access with constant indices
    • Property access via dot notation
    • Calling sandbox-enabled script includes

    Unsupported features include variable and function declarations, assignments, control flow statements, and multiple statements per script.

    Only a restricted list of ServiceNow server-side and built-in JavaScript APIs are allowed; scripts using unsupported APIs will be flagged and may require refactoring or exemption.

    Next Steps and Recommendations

    • Analyze incompatible scripts and update them to use supported syntax and APIs for improved security compliance.
    • Create exemptions for scripts that cannot be immediately updated to avoid service disruption.
    • Leverage GlideGuardedScript script include to manage enforcement phases and exemptions effectively.
    • Maintain awareness of enforcement phases and their durations, especially when managing upgraded or on-premise instances.

    The guarded script evaluator enhances instance security by supporting only a restricted scripting language and detecting or rejecting untrusted scripts that use unsupported JavaScript features.

    The guarded script evaluator uses a domain-specific language (DSL) that permits only a small set of JavaScript syntax, such as simple expressions and function calls, and certain APIs in server-side scripts that run in the script sandbox environment.

    Note:
    Guarded script doesn't apply to script includes, which run in the application scope outside of the sandbox, or client-side scripts.
    When a script that uses only supported features is evaluated by guarded script, it executes successfully. If a script contains unsupported features, guarded script handles it differently depending on the following factors:
    • The origin of the transaction: authenticated user or unauthenticated (guest) user. Guest traffic refers to server-side transactions executed without a logged-in user session, such as interactions coming from public pages.
    • The enforcement phase for authenticated traffic configured for an instance.

    Scripts with a guarded-script exemption bypass guarded script restrictions and are routed to the script sandbox evaluator for execution instead. For more information about the script sandbox evaluator, see Script sandbox evaluator.

    Guarded script enforcement

    Beginning with the Yokohama Patch 13 release, incompatible scripts sent to the server by guest users are rejected on all instances by default. Scripts sent by authenticated users are evaluated differently depending on the instance type.

    Table 1. Default behavior of guarded script
    Transaction type Default behavior
    Unauthenticated (guest) Enforced immediately on all instances. Guarded script rejects incompatible scripts, adds them to the Incompatible Guarded Scripts list, and logs errors.
    Authenticated
    • Upgraded cloud-based instances: Phased enforcement beginning with guarded script detecting but not rejecting incompatible scripts (Phase 1: Detection) and automatically advancing to each subsequent phase (Phase 2: Syntax enforcement and Phase 3: Full enforcement) after two weeks.
    • Upgraded on-premise instances: Not enforced, but guarded script detects and records incompatible scripts (Phase 1: Detection). Administrators can configure when to transition to the subsequent enforcement phases.
    • New instances: Enforced immediately. Guarded script rejects incompatible scripts, adds them to the Incompatible Guarded Scripts list, and logs errors (Phase 3: Full enforcement).

    For authenticated traffic on upgraded instances, guarded script enforcement advances through the following phases to provide time to detect and review incompatible scripts before rejecting them. Before transitioning to Phase 2: Syntax enforcement and Phase 3: Full enforcement, the system creates exemptions for any incompatible scripts detected during each phase automatically. Those exempted scripts bypass guarded script restrictions and run in the script sandbox evaluator. To further secure your instance, you can still review any scripts that have automatic exemptions, update them to be compatible with guarded script, and then remove the exemptions.

    Important:
    Incompatible scripts are only detected and recorded when transactions calling them are sent to the server. You should test business-critical scripts that run infrequently, such as for quarterly or annual processes, before moving to Phase 3: Full enforcement and review the Incompatible Guarded Scripts list regularly to identify any scripts that may need remediation before they could be rejected. For more information, see Update scripts incompatible with guarded script.
    Table 2. Enforcement phases for authenticated traffic
    Phase Description
    Phase 1: Detection
    • Not enforced. Scripts execute regardless of guarded script restrictions.
    • Detects and records only scripts with incompatible syntax in the Incompatible Guarded Scripts list. Scripts with incompatible APIs aren't detected yet.
    • At the end of this phase, exemptions are created automatically for scripts with incompatible syntax, which routes them to the script sandbox evaluator for execution instead.

    Default duration: two weeks
    Phase 2: Syntax enforcement
    • Enforces guarded script syntax restrictions only, rejecting scripts with incompatible syntax and logging errors, but doesn't reject scripts with incompatible APIs.
    • Detects and records scripts with any incompatibilities in the Incompatible Guarded Scripts list.
    • At the end of this phase, exemptions are created automatically for scripts that use incompatible APIs, which routes them to the script sandbox evaluator for execution instead.

    Default duration: two weeks
    Phase 3: Full enforcement
    • Enforces both guarded script syntax and API restrictions. Guarded script rejects all incompatible scripts and logs errors.
    • Detects and records scripts with any incompatibilities in the Incompatible Guarded Scripts list.
    • In this phase, any additional exemptions must be created manually.

    Configuring guarded script

    Beginning with the Yokohama Patch 13 release, administrators can configure the enforcement process for authenticated traffic using the following system properties and script include.

    Table 3. Guarded script properties
    Property Description
    com.glide.script.sandbox.ks.watchdog.phase The current phase of enforcement that the guarded script evaluator applies to untrusted scripts.
    Note:
    Don't update the value of this property manually. Use the following GlideGuardedScript script include methods instead to generate automatic exemptions when transitioning between phases.

    If the com.glide.script.sandbox.ks.watchdog.auto.advance property is set to true, the value of this property is automatically updated according to the duration specified with the com.glide.script.sandbox.ks.watchdog.phase.duration.days property.

    • Type: String
    • Default value:
      • 1 for upgraded instances
      • 3 for new (or zBoot) instances
    • Valid values:
      • 1: Enables Phase 1: Detection.
      • 2: Enables Phase 2: Syntax enforcement.
      • 3: Enables Phase 3: Full enforcement.
    com.glide.script.sandbox.ks.watchdog.phase.duration.days The duration, in days, that each of Phase 1: Detection and Phase 2: Syntax enforcement is in effect.

    To pause automatically advancing between each phase, set the value to -1.

    • Type: Integer
    • Default value: 14
    com.glide.script.sandbox.ks.watchdog.auto.advance An option to control automatically advancing between enforcement phases according to the duration configured with the com.glide.script.sandbox.ks.watchdog.phase.duration.days property.
    • Type: Boolean
    • Default value:
      • true for cloud-based instances
      • false for on-premise instances
    com.glide.script.sandbox.ks.watchdog.enabled An option to turn off the guarded script evaluator and route all untrusted scripts to the script sandbox evaluator instead.
    Warning:
    Don't set this property to false on production instances. Setting this property to false removes the enhanced security protections provided by the guarded script evaluator.
    • Type: Boolean
    • Default value: true

    For information about configuring system properties, see Add a system property.

    The GlideGuardedScript script include supports methods for transitioning between enforcement phases and validates that the transition occurs sequentially. These methods are primarily useful for instances that aren't configured to advance automatically, such as upgraded, on-premise instances. From the Scripts - Background module, you can run the following methods to transition to each phase as needed.

    Table 4. GlideGuardedScript script include methods
    Method Description
    new GlideGuardedScript().resetToPhase1() Resets the instance to Phase 1: Detection for authenticated transactions. Any automatic exemptions created previously remain.
    new GlideGuardedScript().advanceToPhase2() Validates that Phase 1: Detection is complete, creates exemptions for scripts with incompatible syntax, and advances the instance to Phase 2: Syntax enforcement for authenticated transactions.
    new GlideGuardedScript().advanceToPhase3() Validates that Phase 2: Syntax enforcement is complete, creates exemptions for scripts that use incompatible APIs, and advances the instance to Phase 3: Full enforcement for authenticated transactions.

    For information about running background scripts, see Scripts - Background module.

    JavaScript features supported by guarded script

    The following JavaScript features are supported by guarded script. Use this information to analyze scripts in the Incompatible Guarded Scripts list and either rewrite them or create an exemption for them.

    Guarded script supports only a single, simple expression or function call using the following JavaScript syntax:
    • Primitive literals: number, string, boolean, null, undefined
    • Common operators: +, -, <, !==, &&, instanceof, typeof
    • Ternary operator (?:)
    • Array literals ([1, 'x'])
    • Property access using dot notation (a.b)
    • Indexed array access with constant numbers (a[0])
    • Calling script includes that have the Sandbox enabled option selected
    Other JavaScript syntax, including variable and function declarations, assignment operators (=), control flows, and multiple statements, aren't supported by guarded script. For example, guarded script rejects the following script because it contains a variable and control flow logic (if statement):
    javascript:var ret='customer=true';
if (current.relationship_type.to == 'partner')
  ret = 'partner=true';
ret + '^sys_id!=' + current.from_company;
    If you move this logic to a script include and call the script include from the script instead, guarded script executes the updated script:
    javascript:new MyAppUtils().getAccountToFilter(current);

    In addition, guarded script supports only a restricted list of ServiceNow server-side JavaScript APIs and built-in JavaScript APIs. For a list of supported APIs, see JavaScript APIs supported by guarded script.

    You should review the Incompatible Guarded Scripts list regularly and either rewrite scripts to use supported features to further secure your instance or create exemptions for scripts that can't be rewritten. For more information, see Update scripts incompatible with guarded script and the Server-Side Sandbox Runtime Replacement [KB2944435] article on the Now Support Knowledge Base.