GuideUsing Fluid in .NET
Security
How to render templates written by users safely, and the limits Fluid applies while rendering.
Model securityLink to this heading
Fluid templates can read public properties and fields from the model and from objects reachable through it. This is by design; a model passed to TemplateContext should be treated as the template's readable data boundary.
When rendering an untrusted template, pass a dedicated model that contains only the data the template is allowed to read. Do not pass domain entities, service objects, configuration objects, or other object graphs that may expose sensitive data through public members.
Outputting an object itself, as in {{ obj }} or with the format_string filter, writes its ToString() result, which the member access strategy doesn't control. What ToString() returns is up to the application.
Execution limitsLink to this heading
Limiting template recursionLink to this heading
When invoking {% include 'sub-template' %} statements, it is possible that some templates create an infinite recursion that could block the server.
To prevent this, the TemplateOptions class defines a default MaxRecursion = 100 that prevents templates from having a depth greater than 100.
Limiting template nestingLink to this heading
Nested blocks and expressions are parsed and rendered recursively. FluidParserOptions.MaxRecursionDepth limits how deeply a template can nest, so that it can't exhaust the stack: nested blocks, nested expressions like parentheses and indexers, and the number of filters or and/or operators of an expression. Parsing a template that goes deeper fails with The maximum parser recursion depth of 200 was exceeded. The default, FluidParserOptions.DefaultMaxRecursionDepth = 200, allows about 100 nested blocks, and 0 removes the limit.
var parser = new FluidParser(new FluidParserOptions { MaxRecursionDepth = 100 });
Independently of this limit, Fluid checks the remaining stack while parsing and rendering. When too little is left, like on a thread with a small stack, parsing fails with an error saying the template is nested too deeply to be parsed, and rendering throws an InsufficientExecutionStackException.
Limiting template executionLink to this heading
A template can inadvertently perform enough work to block the server. MaxSteps limits statements, loop iterations, range construction, and built-in collection enumeration. String filters are not counted per character; their cost follows the length of their input, and MaxOutputSize bounds what they produce. MaxOutputSize limits cumulative rendered output, captured blocks, macro results, and amplified string operations. MaxCollectionSize limits ranges and collections materialized by built-in operations.
MaxSteps, MaxOutputSize, and MaxCollectionSize are unlimited by default to preserve compatibility. Set all of them when rendering untrusted templates. TemplateContext.CancellationToken complements these limits and should also be set.
Rendering user-provided templates safelyLink to this heading
Fluid is a template engine, not a security sandbox. An application that accepts templates from users should apply all of the following controls:
- Limit the template source length before parsing. Render limits do not limit parsing.
- Pass a dedicated model containing only data the user is allowed to read. Templates can read public properties and fields from every object reachable through the model. Do not pass domain entities, services, dependency-injection containers, configuration, or secrets.
- Configure recursion, work, output, and collection limits. The appropriate values depend on the templates and capacity of the application; start conservatively and adjust using representative load tests.
- Set a per-render cancellation deadline in addition to the request cancellation token.
- Keep the default null file provider unless user templates need
include,render, orfrom. If they do, use a tenant-scoped or allow-listed provider that cannot access application files or another tenant's templates. - Expose only trusted custom filters, tags, values, and file providers. Extension code executes with the permissions of the application and must honor cancellation and equivalent resource limits.
- Apply normal service protections such as request-size limits, authentication, rate limits, bounded concurrency, and memory or process isolation where the threat model requires it.
The following is an example starting point. The numerical limits are illustrative and should be tuned for the application:
private const int MaxTemplateLength = 100_000;
private static readonly FluidParser Parser = new FluidParser();
// The file provider retains its default NullFileProvider.
private static readonly TemplateOptions UserTemplateOptions = new TemplateOptionsBuilder()
.WithMaxRecursion(20)
.WithMaxSteps(10_000)
.WithMaxOutputSize(1_000_000)
.WithMaxCollectionSize(10_000)
.Build();
public static async ValueTask<string> RenderUserTemplateAsync(
string source,
SafeTemplateModel model,
CancellationToken requestAborted)
{
if (source.Length > MaxTemplateLength)
{
throw new ArgumentException("The template is too large.", nameof(source));
}
if (!Parser.TryParse(source, out var template, out var error))
{
throw new ArgumentException(error, nameof(source));
}
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(requestAborted);
timeout.CancelAfter(TimeSpan.FromSeconds(2));
var context = new TemplateContext(model, UserTemplateOptions)
{
CancellationToken = timeout.Token
};
return await template.RenderAsync(context);
}
TemplateOptions, FluidParser, and parsed templates can be shared. Create a new TemplateContext for every render because it is not thread-safe and owns the execution counters and cancellation token.
When a file provider can return different content for the same path in different tenants or security scopes, set TemplateSourceInfo.CacheKey to a stable value that includes that scope. This prevents a cached parsed template from crossing the same boundary enforced by the provider.
MaxOutputSize counts UTF-16 characters written through Fluid's output abstraction. If the rendered result is encoded to a response with a separate byte limit, enforce that transport limit as well. Custom filters, values, tags, and output implementations are responsible for enforcing equivalent limits for work they perform outside Fluid's built-in operations.