# Protected Evaluator

The **Protected Evaluator** is a custom evaluator offered by Form.io to protect against the execution of unsafe, user-supplied code.

The Protected Evaluator is available for use on the Form.io Github: [**https://github.com/formio/protected-eval**](https://github.com/formio/protected-eval)

The Protected Evaluator is based on the open source [JS Interpreter module.](https://github.com/NeilFraser/JS-Interpreter)

### Why use the Protected Evaluator?

Since many Form.io components can be customized with JavaScript written by Form Builders, application owners may want to evaluate such code in a protected environment by using the Protected Evaluator.

The Evaluator is a static class object that all JavaScript executions pass through to be evaluated, and thus offers a degree of protection against malicious code in component customization.

#### What customizations might require the Protected Evaluator?

Some of the customizations that may require a form to use the Protected Evaluator are:

* Conditional logic
* Calculated fields
* Custom validation
* Custom default values

These customizations often use code introduced by the Form Builder. Security practices may require the use of Protected Eval when such customizations are used.

### How to use the Protected Evaluator

To use the Protected Evaluator:

1. Install the module by using the following command:

```
npm install --save @formio/protected-eval
```

2. Import the Protected Evaluator into the application by adding the following code:

```javascript
import ProtectedEval from '@formio/protected-eval';
import { Formio } from 'formiojs';
Formio.use(ProtectedEval);
```

### Operational Impact

Protected Evaluation executes the user-supplied JavaScript on a line-by-line basis in a sandboxed environment. This necessarily introduces a degree of overhead that can affect the performance of a form. This overhead will scale linearly with the amount of custom code.  As a result, forms that make significant use of calculated values, custom default values, conditional logic, etc. may see a noticeable degradation in performance.

#### Mitigating effect on performance

Every particular use case may need to find a unique balance between security and performance. In cases where performance cannot be sacrificed, some design patterns may be useful when mitigating the impact on performance:

* **Custom evaluator -** The Protected Evaluator takes a blanket approach to sandbox all custom JavaScript. If there are specific concerns that can be addressed with a more targeted evaluator, Form.io makes it easy to develop and integrate a [custom evaluator](https://help.form.io/developers/form-development/form-evaluations/..#custom-evaluators). 
* **Offloading logic** - In some cases, the customization done in the Form.io component can be offloaded to other aspects of the application. This reduces the need to invoke the Protected Evaluator as frequently.