Sandboxing HTML Processing in C#

Use Configuration.Security with Sandbox flags when an HTML document should be processed with restricted capabilities. For example, set Sandbox.Scripts to prevent script execution or Sandbox.Images to disable image loading before creating an HTMLDocument with that configuration.

Aspose.HTML for .NET lets you control document processing behavior through the Configuration class. The Environment Configuration article gives the broader picture: user agent settings, fonts, runtime timeouts, and network services. This article focuses only on sandboxing – using Configuration.Security to mark specific document capabilities or resource types as restricted during HTML parsing, rendering, or conversion.

Sandboxing is useful when your application loads HTML from a source you do not fully control, or when a conversion workflow should deliberately ignore scripts, images, forms, plugins, or navigation behavior. It is not an operating-system or container security boundary; use it as an Aspose.HTML document-processing control, together with your normal application security, file-system, and network restrictions.

Configure HTML Sandboxing in C#

A sandboxing flag set is a set of one or more Sandbox values that restrict selected document capabilities. In Aspose.HTML for .NET, you apply these flags through the Security property of a Configuration instance, then pass that configuration to the HTMLDocument constructor.

The key workflow is the same for each sandbox rule:

1. Create an instance of the Configuration class.
2. Add one or more Sandbox flags to configuration.Security.
3. Create an HTMLDocument with the configured environment.
4. Process, render, or convert the document with the restricted capabilities in effect.

Use bitwise flag composition when more than one restriction is needed, for example configuration.Security |= Sandbox.Scripts | Sandbox.Images.

Disable Script Execution

Scripts are one of the most common capabilities to disable when processing untrusted HTML. Setting Sandbox.Scripts marks scripts as restricted so they are not executed during document processing.

The following C# example disables scripts before converting HTML to PDF. The input HTML file contains scripts, but the document is loaded with a sandboxed configuration.

To disable scripts during HTML to PDF conversion:

1. Create a Configuration instance.
2. Add Sandbox.Scripts to configuration.Security.
3. Create an HTMLDocument with the source file path and configuration.
4. Create PdfSaveOptions for PDF output.
5. Call Converter.ConvertHTML(document, options, outputPath).

// How to disable scripts for HTML to PDF conversion using C#

// Create an instance of the Configuration class
using (Configuration configuration = new Configuration())
{
    // Mark "scripts" as an untrusted resource
    configuration.Security |= Sandbox.Scripts;

    // Initialize an HTML document with specified configuration
    using (HTMLDocument document = new HTMLDocument(Path.Combine(DataDir, "document-with-scripts.html"), configuration))
    {
        // Convert HTML to PDF
        Converter.ConvertHTML(document, new PdfSaveOptions(), Path.Combine(OutputDir, "document-sandbox.pdf"));
    }
}

By applying Sandbox.Scripts before the document is created, the conversion workflow processes the document without executing scripts from the HTML source. If you also need to limit how long scripts may run instead of disabling them completely, see Runtime Service in Environment Configuration.

Disable Image Loading

Images can be disabled when a conversion should ignore remote or local image resources. This is useful for reducing external resource access, testing fallback output, or processing HTML where image URLs are not trusted.

The following C# example creates HTML with a CSS background image and a script, then sets Sandbox.Images before loading the document and converting it to PDF. The image resource is treated as restricted during processing.

To disable image loading in C#:

1. Prepare or load HTML that references image resources.
2. Create a Configuration instance.
3. Add Sandbox.Images to configuration.Security.
4. Create an HTMLDocument with the configured environment.
5. Convert the document to PDF with Converter.ConvertHTML().

// Disable loading images in HTML with sandbox configuration using C#

// Prepare HTML code and save it to a file
string code = "<span style=\"background-image:url('https://docs.aspose.com/html/images/work/lioness.jpg')\">Hello, World!!</span> " +
              "<script>document.write('Have a nice day!');</script>";

File.WriteAllText(Path.Combine(OutputDir, "sandboxing.html"), code);

// Create an instance of Configuration
using (Configuration configuration = new Configuration())
{
    // Mark 'Images' as an untrusted resource
    configuration.Security |= Sandbox.Images;

    // Initialize an HTML document with specified configuration
    using (HTMLDocument document = new HTMLDocument(Path.Combine(OutputDir, "sandboxing.html"), configuration))
    {
        // Convert HTML to PDF
        Converter.ConvertHTML(document, new PdfSaveOptions(), Path.Combine(OutputDir, "sandboxing-out.pdf"));
    }
}

In this workflow, image loading is disabled through the sandbox configuration, while the rest of the document can still be parsed and converted. If you need more detailed control over remote requests, logging, caching, or blocking specific URLs, use Network Service or message handlers instead of sandbox flags alone.

Sandboxing Flags

The Sandbox enumeration contains flags for common document restrictions. Use the smallest set of flags that matches the workflow you want to control.

Sandbox flag	Use it to restrict
None	No sandbox restriction is applied.
Navigation	Navigation from the sandboxed browsing context to other browsing contexts.
Plugins	Plugin instantiation through elements such as embed, object, or applet.
Origin	Access to content from the same origin by forcing a unique origin.
Forms	Form submission.
Scripts	Script execution.
Images	Image loading.

Common Sandboxing Issues

Problem	Cause	Solution
Scripts still affect output	The document was created before Sandbox.Scripts was applied, or the wrong Configuration instance was used.	Set configuration.Security before creating HTMLDocument, and pass that same configuration to the constructor.
Images still appear in the result	Sandbox.Images was not applied before loading the document, or the visual result comes from CSS, text, or cached/local output rather than a loaded image resource.	Apply Sandbox.Images before document creation and verify which resource creates the visual output.
Too many resources are blocked	Multiple sandbox flags were combined without checking whether each restriction is required.	Start with the narrowest flag, test the result, then add more flags only when the workflow needs them.
Remote URLs need selective blocking	Sandbox flags restrict broad capability categories and do not replace URL-level network policy.	Use Network Service or custom message handlers for request-level control.
Sandboxing is treated as full application isolation	Aspose.HTML sandbox flags control document processing behavior; they do not replace OS, container, process, file-system, or network security.	Combine sandbox flags with normal application security controls when processing untrusted input.

FAQ

How do I disable JavaScript in Aspose.HTML for .NET?

Create a Configuration, add Sandbox.Scripts to configuration.Security, and pass that configuration to the HTMLDocument constructor before converting or rendering the document.

How do I disable image loading during HTML conversion?

Add Sandbox.Images to configuration.Security before creating the HTMLDocument. Then process or convert the document with that configured environment.

Can I combine several sandbox flags?

Yes. Sandbox values are flags, so you can combine them, for example Sandbox.Scripts | Sandbox.Images, when the same workflow must restrict more than one capability.

Is Aspose.HTML sandboxing the same as OS-level sandboxing?

No. Aspose.HTML sandboxing controls selected HTML document capabilities during processing. It does not replace operating-system, container, process, file-system, or network isolation.

When should I use Network Service instead of sandboxing?

Use sandboxing for broad capability restrictions such as scripts or images. Use Network Service or message handlers when you need request-level control, logging, caching, timeouts, or URL-specific blocking.

Related Articles

• Environment Configuration – configure user agent settings, fonts, runtime service, and network service.
• Network Timeouts – set network operation timeouts with custom message handlers.
• Check Network Requests – inspect, block, or replace network requests in C# workflows.
• Save HTML Document – save HTML documents after processing or editing.

The complete C# examples and data files are available in the Aspose.HTML for .NET GitHub repository.