Protecting Python Applications Using Script Envelope

You can protect Python applications using the Script Envelope command-line tool (scriptenv.exe). This tool uses automated processes to apply advanced Sentinel LDK Envelope protection to a Python application.

NOTE   Script Envelope supports model file protection for Pytorch and TensorFlow models. For details, see Protecting Model Files for Python.

NOTE   Project files (.sprjx) are human-editable YAML files. While the legacy JSON format is still supported for backward compatibility, YAML is the preferred and recommended format.

You can perform the protection process under Windows (x64) or Linux (Intel). The protected application can run under Windows (32-bit or x64) or Linux (Intel 64 or ARM 64). Script Envelope automatically places the required runtime library under output_root\sntlruntime. For information on using Script Envelope under Linux, see Sentinel LDK Envelope for Linux.

Using Script Envelope consists of the following steps:

1. Prepare a project file that contains all the required information for protecting your Python application, including the location of the source files and the target location for the protected files.

2.Run Script Envelope, passing the project file path as a parameter to the tool.

NOTE   You must connect a Sentinel Vendor key to the machine that you use to run Script Envelope.

Prepare the Project File

Perform the following steps on a machine where Sentinel LDK Vendor Tools are installed.

1.Create or select a project folder to contain the project file for the Python application to be protected.

2.Copy a project file from any sample under %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\Envelope\Python\ to the project folder. For starting with Script Envelope, consider using simple.sprjx (standard encryption) or simple_native.sprjx (native compilation) from the simple_sample directory. For details, see Sample Projects. Rename the new project file to a relevant name for your application.

3.Open your project file in a text editor.

4.Modify the parameters in your project file as described in the table below.

entry_scripts_glob: main.py

entry_scripts_glob:
  - file.py
  - file2.py

to_be_protected:
  - input_glob: "*.*"
    ignore_glob: moduleC.py
    feature_id: 4
  - input_glob: "CD/*.py"
    feature_id: 14
  - input_glob:
      - "EF/*.py"
      - "GH/*.py"

  - input_glob: model.keras
    ignore_glob: ""
    feature_id: 0

  - input_glob: model.pt
    ignore_glob: ""
    feature_id: 0

input_glob: "**/*.py"
ignore_glob: fileA.py

symbols:
  external: protection/crypto-symbols.yaml
  "crypto.derive_key": ["obfuscation.level=3"]
  "crypto.SecureChannel.connect": ["obfuscation.level=2"]
  "crypto.*": ["anti-trace.off"]

custom_scope: '<haspscope><hasp type="HASP-HL" /></haspscope>'

5.Save the project file.

Run Script Envelope

Perform the following steps on the machine where your project file is located and Sentinel LDK Vendor Tools are installed.

1.Open a Windows command-line prompt.

2.In the command-line prompt, change to the following path:

%ProgramFiles(x86)%\Thales\Sentinel LDK\VendorTools\VendorSuite\

3.Enter the following command:

 scriptenv.exe projectFile [-q] [-v]

where:

NOTE   You can enter scriptenv.exe -h or scriptenv.exe --help to display help for scriptenv.

Envelope protects the Python application that you specified in the input_root parameter and writes the application to the path that you specified in the output_root parameter.

Migrating Legacy JSON Project Files to YAML

The convert command allows you to convert your legacy JSON project file to YAML while preserving duplicate __Comment keys as standard YAML comments (#).

NOTE   The hyphen (-) in YAML represents array items. When converting JSON to YAML, map each left bracket ([) to a hyphen and omit hyphens for properties inside the item.

1.Open a Windows command-line prompt.

2.Change to the directory containing scriptenv.

3.Run either of the following commands:

scriptenv.exe convert input.sprjx output.sprjx

or

scriptenv.exe --convert input.sprjx output.sprjx

where input.sprjx is your legacy JSON project file, and output.sprjx is the name of the new YAML-formatted project file to be created.

NOTE   The tool only processes and validates files with the .sprjx extension.

Syntax Error Handling and Validation

Script Envelope validates the project file and displays syntax suggestions if validation fails.

>YAML files: The tool checks for correct indentation with spaces.

>Legacy JSON files: The tool checks for missing commas, trailing commas, and unescaped quotes.

Native Protection with Script Envelope

Native protection enables you to protect proprietary Python application code by compiling selected Python modules into native machine code. This approach reduces exposure of Python bytecode because the protected application logic is delivered and executed as native binary modules rather than as encrypted Python bytecode.

You can use native protection alongside other Script Envelope protection mechanisms, allowing you to select the appropriate protection method for different parts of your application.

Native compilation and Script Envelope Plus hardening are separate capabilities. Native compilation converts selected Python source files into native extension modules. Script Envelope Plus adds advanced protection techniques, such as code obfuscation, anti-tamper protection, and anti-trace protection. To enable Script Envelope Plus protection, configure plus: true in the project file. The developer key used during protection must contain the Script Envelope Plus entitlement, Feature 302.

How Native Protection Works

Native protection operates in two stages: protection time and runtime.

Protection Time (Building the Protected Application)

During the protection process, Script Envelope automates the following sequence:

>Discover application modules and dependencies: The tool inspects your source directory, maps module dependencies, excludes __pycache__ bytecode directories, and reads protection settings from the .sprjx file.

>Generate native code: The tool translates designated .py and typed .pyx source files into optimized C code using Cython against the standard CPython C-API.

>Compile and harden the native modules: The native protection backend compiles the C code into optimized, target-specific machine code extension modules (.pyd on Windows and .so on Linux). When you specify plus: true with a licensed developer key (Feature 302), the backend injects requested code protection passes (obfuscation, anti-tamper, and anti-trace) directly into the compiled machine code.

>Build self-contained binaries: The compiled modules are self-contained without dynamic Microsoft Visual C++ redistributable dependencies on Windows and without restrictive GNU C Library (glibc) version dependencies on Linux, allowing modules to run portably across supported distributions.

>Package the protected application: The tool bundles modules according to your bundle_mode selection, generates cleartext bootstrap loader stubs for entry points, constructs the multi-architecture routing bridge (for example, sntlbundles.py) for multi-target builds, and encrypts non-Python resource data files.

Runtime (Running the Protected Application)

When an end user executes your protected application, the execution flow proceeds as follows:

>Initialize the protection runtime: The end user launches the application using standard Python. The generated entry loader script executes first, initializes the Script Envelope Runtime, and verifies the license for the configured Feature ID against the connected Sentinel protection key.

>Select the appropriate native module: For multi-architecture distributions, the routing bridge detects the platform architecture of the active Python interpreter (such as windows-x64 or linux-arm64) and dynamically imports the matching binary extension module from the sntlnative/ directory.

>Validate protected modules at load time: As the Python interpreter imports each compiled native module, the module performs a fast validation against the active licensing session in the Script Envelope Runtime. The module does not start background timers or additional threads.

>Execute protected logic as native code: Protected logic executes directly on the processor as machine code. Encrypted resource data files are decrypted on demand when the application accesses them.

>Maintain the licensing session: The Script Envelope Runtime maintains the active licensing session in a separate background thread, performing periodic checks on the schedule defined in background_check and displaying interactive grace dialogs if the protection key disconnects.

Protected Output Structure

When you use native protection (protection method set to native), Script Envelope compiles your application Python source modules into native binary modules and creates the following output structure:

>Entry Scripts: For each script specified in the entry_scripts_glob parameter, the tool generates a small, cleartext bootstrap loader script (for example, main.py) and compiles the actual protected application logic into a separate native module (such as main_r.pyd on Windows or main_r.abi3.so on Linux). The bootstrap loader script automatically initializes the licensing session and imports the native module.

>Non-Entry Scripts: Other protected scripts are natively compiled directly into standard native extension binaries (for example, moduleA.pyd or moduleA.abi3.so). No cleartext Python files remain in the output directory for these modules.

>Runtime Files: Required runtime libraries are placed in the sntlruntime/ directory under output_root.

Multi-Architecture Packaging Layout

If your targets list contains more than one platform architecture, Script Envelope automatically reorganizes the natively compiled modules into target-specific subdirectories under a shared sntlnative/ directory (for example, sntlnative/windows-x64/ and sntlnative/windows-x86/). The generated loader stub in the root directory contains an architecture-detecting routing mechanism that dynamically imports the correct native module matching the running Python interpreter's architecture.

Licensing Behavior and Failure Policies

Developer Key Entitlement (Feature 302)

Script Envelope Plus hardening is licensed by a dedicated feature on the developer key connected to your build machine. A project opts in to hardening passes by setting plus: true in the project file.

The developer key connected during protection must contain the Script Envelope Plus entitlement (Feature 302). If you specify plus: true with demo vendor code (DEMOMA), the build succeeds without code hardening passes and logs warning C0057. If you specify plus: true without a valid Feature 302 license on the developer key, the build stops with error C0062.

NOTE   Feature 302 applies only to Script Envelope Plus for Python. Verify that your developer key holds Feature 302 for Python hardening.

Evaluation Entitlement

You can request a temporary evaluation entitlement (for example, a 30-day evaluation) for Script Envelope Plus. Thales provides the entitlement as a remote license update to your existing developer key.

To activate the evaluation entitlement:

1.Generate a machine fingerprint (C2V file) from your developer key.

2.Send the C2V file to Thales support.

3.Apply the returned V2C license update to activate the evaluation entitlement on your developer key.

The evaluation entitlement produces fully hardened native extension modules. Each module includes the trial expiration date. At run time, the module displays a warning that indicates the number of trial days remaining and stops running after the trial expires.

Use evaluation builds only for evaluation. The trial expiration prevents you from distributing these builds to end users.

Startup and Runtime Licensing Failure Policies

You can configure how the application reacts when a license check fails:

>Startup Login Failure (license_startup_failure_policy): Configures application behavior when the initial application startup login fails (exit_process, fail_init, or retry_infinite).

>Mid-Run Module Import Failure (global_license_failure_policy): Configures behavior when a module is imported mid-run and the Feature ID assigned to that module is unentitled (retry_infinite, fail_load [Windows only], or exit_process).

For parameter options and defaults, see the property table above. For details on configuring end-user licensing models in Sentinel EMS and distributing customer licenses (C2V and V2C remote updates), see the Sentinel LDK Software Protection and Licensing Guide (for Sentinel EMS or Sentinel LDK-EMS).

Advanced Technical Configurations

Linking External C Libraries and Real Platform CRT Overrides

When you protect natively compiled Python (.py) scripts or typed Cython (.pyx) modules (including modules that use cdef extern statements to statically link external C functions), configure compiler and linker options under the native_settings block within the file_entries.to_be_protected section. This block accepts include_dirs, library_dirs, libraries, compiler_flags, and linker_flags definitions mapped per target platform. Paths resolve relative to input_root.

By default, natively compiled modules link against a minimal self-contained runtime layer that eliminates dynamic glibc or Microsoft Visual C++ redistributable dependencies. If an external C library requires functions from the standard platform C runtime (such as printf, malloc, or fopen), you can opt into the real platform runtime:

>Windows: Specify libcmt.lib or msvcrt.lib in libraries or linker_flags to link against the standard Microsoft Visual C++ runtime.

>Linux: Specify -lc, libc.so, or libc.a in libraries or linker_flags to link against standard Linux glibc.

For example:

to_be_protected:
  - input_glob: "fast_math.pyx"
    method: native
    native_settings:
      include_dirs: ["include"]
      library_dirs: ["lib"]
      libraries: ["vendor_math"]
      linker_flags: ["libcmt.lib"]

External Message Sets (.smsgx) and Multi-Language Runtime Fallback

To simplify localization across multiple projects, you can store message sets in standalone YAML files with the .smsgx extension. Reference these external files under settings.message_sets using the external key.

To avoid hard-coded file paths, you can use two built-in path tokens:

>${MESSAGE_SETS}: Resolves to the pre-delivered message sets provided with Sentinel LDK in the VendorTools\toolchain\message_sets directory on Windows (toolchain/message_sets on Linux).

>${SCRIPTENV}: Resolves to the Script Envelope installation directory.

NOTE   An external .smsgx file cannot reference another external file.

For example:

settings:
  message_sets:
    - external: ${MESSAGE_SETS}/de-DE.smsgx
    - external: ${MESSAGE_SETS}/fr-FR.smsgx
    - language: en-US
      caption: Sentinel LDK Protection System
      messages:
        - id: 7
          text: Sentinel protection key was not found

You can reference the pre-delivered message sets directly, or copy the files to your project folder and customize the text according to your requirements.

Automatic Language Selection and Fallback

At run time, the application detects the operating system user locale and selects the message set using the following sequence:

1.Exact locale match: Matches both language and region (for example, de-AT matches a de-AT set).

2.Language match, any region: If no exact match is found, selects the first message set matching the primary language code (for example, the first available de-* set).

3.Default set fallback: If no matching language is found, falls back to the first message set in the list (typically en-US).

Within the selected set, if an individual message ID is not defined, execution falls back per message to the text in the first message set in the list. In addition, evaluation notices resolve through localized message set codes: 5020 (Demo key notice), 5021 (evaluation trial warning with remaining days), and 5022 (evaluation trial expired error).

Overriding the Locale (ENVELOPE_LOCALE)

Set the ENVELOPE_LOCALE environment variable (for example, ENVELOPE_LOCALE=de-DE, or ENVELOPE_LOCALE=he-IL for right-to-left layout) to override the operating system locale without modifying operating system language settings.

Best Practices and Performance Optimization

Recommended Setup for Most Applications

For optimal security and performance, Thales recommends compiling your Python source files into native machine code and bundling all modules into a single binary extension module (method: native and bundle_mode: single):

>Native Compilation Over Encryption: Natively compiled modules eliminate recoverable bytecode from disk and memory. Bytecode encryption decrypts code into memory at run time, leaving cleartext code objects vulnerable to memory extraction.

>Single Bundle Packaging: Merging all modules into a single compiled binary removes cleartext Python file structures, eliminates cross-module import visibility, and maximizes cross-function code hardening passes.

CPython Stable ABI (abi3) Compatibility

Native compilation targets CPython's stable Application Binary Interface (abi3) by default. A module compiled at the 3.9 floor runs across CPython 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14+, allowing you to distribute and test a single compiled binary artifact per platform architecture. If your application relies on features introduced in later Python versions, such as Python 3.11 exception groups (except* syntax), set min_python_version to "3.11".

Performance Characteristics and Hardening Impact

Protection methods and code protection levels influence execution speed and binary size:

>Native Compilation Speedup: Natively compiled modules execute directly as machine code, providing faster execution than interpreted Python bytecode for CPU-bound routines.

>Typed Cython Speedup: Providing type annotations in .pyx files yields significant speedups by eliminating CPython dynamic object lookups.

>Effect of Obfuscation Levels: Code protection Level 0 provides baseline performance and compact binary sizes. Increasing protection levels (1 through 3) applies control-flow transformations and integrity guards, trading execution speed and binary size for enhanced resistance to reverse engineering.

NOTE   Rule: Anti-Tamper and Anti-Trace Require Obfuscation: In any scope where anti-tamper or anti-trace is set above 0, obfuscation must also be set above 0 in that same scope, or the build terminates with an error. In addition, anti-trace protection is supported on x86 and x86-64 architectures (Windows and Linux); on ARM64 architectures, anti-trace is skipped with a diagnostic warning.

Build Diagnostics and Troubleshooting

Command-Line Interface (CLI) Diagnostic Options

Script Envelope provides command-line flags to inspect developer key entitlements and troubleshoot build steps:

>scriptenv --license-info <vendor_id | file.hvc | project.sprjx>: Reports whether the developer key connected to the build machine contains a valid Feature 302 entitlement, an active evaluation license, or no license. You can pass a Vendor ID, a Vendor Code file (.hvc), or a project file (.sprjx). For example:

•scriptenv --license-info 37517 (passes a Vendor ID)

•scriptenv --license-info DemoMB.hvc (passes a Vendor Code file)

•scriptenv --license-info test.sprjx (passes a project file)

>scriptenv -v (or --verbose): Enables verbose compiler and linker diagnostic logs during protection runs.

Resource File Protection and Warning C0071

A section configured with method: native compiles only Python and typed Cython source files (.py and .pyx). If non-Python data files (such as .json or .dat) match the section input_glob, Script Envelope does not fail the build. Instead, the tool automatically encrypts the resource file and logs diagnostic warning C0071:

>warning C0071: resource file '<filename>' matches a native section (glob '<pattern>') but cannot be compiled; the file will be encrypted instead

The encrypted resource file decrypts transparently on read at run time through the runtime hook. To prevent this warning, declare non-Python resource files in a separate section with method: encrypt.

Cython .pyx Protection and Warning C0069

Cython source files (.pyx) require compilation to native C extensions and cannot run as interpreted bytecode. If you specify method: encrypt (or declare global_method: encrypt) on a section matching .pyx files, Script Envelope automatically overrides the protection method to native and logs diagnostic warning C0069:

>warning C0069: method 'encrypt' does not apply to Cython source (.pyx); '<filename>' will be compiled natively instead

Common Build Warnings

>error C0048: anti-tamper and anti-trace require obfuscation to be enabled in the same scope (obfuscation level > 0): Indicates that anti-tamper or anti-trace protection is active while obfuscation is set to 0. When you set obfuscation_level: 0 (or global_obfuscation_level: 0) with plus: true, you must also set anti_tamper_level: 0 and anti_trace_level: 0 in that scope. Anti-tamper and anti-trace mechanisms cannot operate without code obfuscation.

>warning C0056: obfuscation / anti-tamper / anti-trace levels are set but `plus` is not enabled; they have no effect: Indicates that code hardening levels are configured in the project, but plus is set to false (or omitted). The application builds without code hardening.

>warning C0057: Demo vendor code is in use. `plus` protection features are disabled: Indicates that plus: true is specified with the DEMOMA demo vendor code. The application builds without code hardening.

>error C0062: `plus` is enabled but no license for it is present; run --license-info to check: Indicates that plus: true is configured in the project file, but the connected developer key does not license Feature 302 (Script Envelope Plus). Connect a developer key programmed with Feature 302, run scriptenv --license-info to inspect entitlements on your key, or set plus: false when machine code hardening is not required.

>warning C0074: `<function>`: `<family>` set by pattern `<pattern2>` overrides the value from pattern `<pattern1>`: Indicates that a pattern listed later in the symbols map has overridden a setting from an earlier pattern. Reorder the map so that broad patterns (such as module.*) precede specific function entries.

>warning C0080: section '<glob>' sets per-function protection in `symbols` but `plus` is not enabled; the `symbols` map has no effect: Indicates that a section defines per-function protection overrides in the symbols map, but plus is set to false (or omitted). Set plus: true under settings to apply per-function protection.

>warning C0081: symbols key '<key>' in section '<section>' matched no function: Check for spelling errors or unsupported nested class paths in the symbols map.

>error C0083: symbols key '<key>' in section '<section>': '<level>' is not a valid level; the level must be 1, 2 or 3: Indicates that a directive in the symbols map specifies a protection level outside the supported 1..3 range (for example, obfuscation.level=4). Set the protection level to 1, 2, or 3, or use .off to disable that protection family.

>warning C0051: Skipping __pycache__ directory '<path>': Normal notification confirming bytecode caches were excluded from native compilation.

Sample Projects

Sentinel LDK provides sample projects under the %ProgramFiles(x86)%\Thales\Sentinel LDK\Samples\Envelope\Python\ directory to demonstrate protection configurations:

>simple_sample: The recommended starting point for customizing a project file for your own application. Includes two sample project files: simple.sprjx (standard encryption) and simple_native.sprjx (native compilation). Most settings are explicitly defined with comments explaining their default values and usage.

>pyx_bounce: Demonstrates a cross-platform bouncing-ball GUI application built using typed Cython (.pyx), single bundling, and Script Envelope Plus hardening. Designed for validating background licensing checks, thread suspension, grace prompts, and multi-language message sets (configured through message_sets and the ENVELOPE_LOCALE environment variable).

>native_sample: Demonstrates basic native compilation of a multi-module Python application end-to-end, including an x86 build variant.

>pyx_sample: Demonstrates protecting a typed Cython (.pyx) module alongside standard Python scripts, showcasing per-file and single-bundle compilation speedups.

>complex_sample: Demonstrates bundling multiple cross-importing modules into a single binary, plus multi-architecture packaging with dynamic routing.

>pkg_sample: Demonstrates packaging multiple Python packages using bundle_mode: per_package.

>resource_sample: Demonstrates scoping non-Python resource files (such as configuration JSON files) into explicit encryption sections to decrypt transparently on read at run time.

>obfuscation_sample: Demonstrates module and package folder name obfuscation under encryption, replacing module and folder names with randomized identifiers while preserving application import logic.

>symbol_protection_sample: Demonstrates tuning protection for individual functions using an inline symbols map and an external shared profile file (requires Feature 302).

>traceback_sample: Demonstrates comparing error tracebacks when preserve_tracebacks is enabled versus disabled.

>license_sample: Demonstrates handling mid-run module license failures using global_license_failure_policy: fail_load and localized runtime error dialogs.

>startup_policy_demo: Demonstrates testing the three startup licensing policies (exit_process, fail_init, and retry_infinite) against a failing license key.

>linklib_sample: Demonstrates statically linking external vendor C libraries into typed Cython modules using native_settings.

>libc_override_sample: Demonstrates opting into the real platform C runtime (libc/MSVCRT) on Windows and Linux for external libraries that require standard C runtime functions.

Related Topics

Protecting Python Applications

Protecting Model Files for Python