Security considerations when calculating formulas

Calculating formulas is an active operation that the host application chooses to perform on a specific workbook. Loading or opening a workbook does not calculate anything and does not, on its own, trigger resource-intensive work or network access — those happen only when your application calls Calculate() (on a workbook, worksheet, or range).

Because of this, the security implications of formula calculation depend on how much you trust the workbook you are calculating. This page describes the controls EPPlus provides so you can calculate formulas safely at the trust level that applies to your scenario.

For the overall division of responsibility between EPPlus and the host application, see our Security Profile.

Trust levels

It is useful to think about the origin of a workbook before calculating it, rather than treating every file the same way:

• Trusted — the workbook is produced by your own systems or by a source you fully control. The controls below are generally not needed, though a calculation timeout can still be a reasonable safeguard against unexpected input.
• Partially trusted — the workbook comes from a known but external party (for example, a customer or a partner). You may want to bound calculation time and consider whether network-backed functions should be allowed.
• Untrusted — the workbook is arbitrary, attacker-controllable input (for example, a file uploaded by an anonymous user). We recommend avoiding formula calculation in fully untrusted workbooks where possible. If you must, apply the controls below according to your needs: bound the calculation time, and either restrict or disable network access from IMAGE().

The controls described here are independent and can be combined. Which ones you apply is a decision only the host application can make, because only it knows its own trust boundaries, network topology, and resource limits.

Bounding calculation time

Formula calculation time is not inherently bounded. A workbook can contain formulas — for example, large or deeply chained array formulas — whose evaluation is expensive by design, and in a server-side context that can amount to a resource-exhaustion (denial-of-service) risk if the input is not trusted.

From version 8.5.0, EPPlus lets you cancel a running calculation through the standard .NET CancellationToken mechanism, so you can enforce a timeout or an external cancellation signal. This is the primary control for the resource-consumption dimension of calculating untrusted or complex workbooks. See Cancelling a calculation for usage, threading patterns, and the state rules for a cancelled workbook.

Network access from the IMAGE function

The IMAGE() function, available in EPPlus from version 8, retrieves an image from a URL supplied as its first argument. When a workbook containing IMAGE() formulas is calculated, EPPlus may make an outbound HTTPS request to that URL in order to fetch the image. This is the documented, intended purpose of the function.

The request is only made when the image is not already present in the workbook (or when ParsingConfiguration.AlwaysRefreshImageFunction is set to force a refresh). If the image is already stored in the package, it is used directly and no network call is made.

How downloads are performed

The download itself runs through the IHttpsService interface, exposed on the package settings as ExcelPackageSettings.ImageFunctionService. By default this is set to an internal implementation that downloads the URL using HttpClient.

Before invoking the service, EPPlus verifies only that the argument is a well-formed, absolute HTTPS URL; it does not resolve the host or classify the destination as public, private, or internal. Any such validation is the responsibility of the configured IHttpsService implementation.

This is a deliberate extension point: because the download step is pluggable rather than hardcoded, the host application decides how — and whether — URLs are fetched.

Restricting which URLs may be downloaded

If you want to allow IMAGE() downloads but only to approved destinations, provide your own IHttpsService implementation that validates the URL before fetching it. This lets you apply exactly the policy that fits your environment — for example, allowing only certain hosts, or rejecting internal and link-local addresses — which is a decision that belongs with the host application rather than the library, since the appropriate policy differs between deployments.

public class RestrictedImageService : IHttpsService
{
    public byte[] Download(string url)
    {
        // Apply your own validation here before fetching.
        // Return the image bytes, or throw / return null to reject.
        // ...
    }
}

// Register it on the package:
package.Settings.ImageFunctionService = new RestrictedImageService();

Disabling downloads entirely

If you do not want calculation to make any network requests, set ImageFunctionService to null. With no download service configured, IMAGE() will not perform network access; when an image would otherwise need to be downloaded, the function returns a #NAME? error instead.

package.Settings.ImageFunctionService = null;

Images that are already stored in the workbook are unaffected and continue to be handled normally.

Choosing controls for your trust level

There is no single setting that makes calculation "safe" in the abstract — the right combination depends on your trust level and what you need the calculation to do:

• If you need IMAGE() to fetch from the public internet but the input is not fully trusted, consider a validating IHttpsService together with a calculation timeout.
• If you do not rely on network-backed images, setting ImageFunctionService to null removes the outbound-request surface entirely.
• If the concern is calculation time rather than network access, a CancellationToken timeout is the relevant control.
• For fully untrusted input, we recommend avoiding formula calculation altogether where possible; where it is unavoidable, combine the controls above.

These controls address the library-side surface of formula calculation. Process-level concerns — authentication, authorization, resource limits enforced by the runtime, and the decision of whether a given file is trusted in the first place — remain the responsibility of the host application, as described in our Security Profile.

See also

• Cancelling a calculation
• Formula Calculation