Documentation for the Ensure JavaScript Library

Ensure.js is a library that helps you to verify the compliance of a user's device with various security standards. With this library you can invoke the Ensure.run() function, which will return a Promise containing the result of the compliance checks.

Installation

To install this library, include the following script tag in your HTML file:

<script src="https://v2.alertsec.com/assets/js/ensure.js"></script>

Usage

Ensure.run(portalKey, userId)

This function will initiate the compliance check process.

Parameters:

  • portalKey (string) - The public portal ID, you can retreive this in the Ensure web admin.
  • userId (string) - The unique identifier of the user whose device needs to be checked for compliance. This can be any string, email-address, your internal user identifier or a temporary identifier for the user. This parameter is optional and you can pass NULL.

Returns:

A Promise that resolves with the compliance result object, or rejects with an error message if the process encounters any issues.

Example Code

The Ensure library is simple to use, with just one method called run. Here's an example of how to use the run method:

Ensure.run('<portal-key>', '<user-id>')
.then((result) => {
    console.log('Ensure process completed successfully');
})
.catch((error) => {
    console.error('Error:', error.message);
});

Result Object

The result object is passed to the Promise when it resolves and contains the following properties:

  • verification: An object containing the following:
    • status: An array of objects, each representing the compliance status of different security standards. Each object has the following properties:
      • name (string): The name of the security standard.
      • compliant (boolean): A flag indicating whether the user's device is compliant with the respective security standard (true) or not (false).
    • token (string): A unique identifier for the validation process, which can be used for checking the status server side. This token expires after 30 minutes.

Example Result Object

{
  verification: {
    status: [
      {"name":"antivirus","compliant":true},
      {"name":"encryption","compliant":true},
      {"name":"firewall","compliant":true},
      {"name":"passphrase","compliant":true},
      {"name":"updates","compliant":false}
    ],
    token: "04c79172-5267-489e-abe2-15ed61c9ae6b", 
  }
}

In this example, the user's device is compliant with all the security standards except for "updates".

Verify device compliance server side

To verify that the remote device is compliant on the server side, you should pass the token to the server and then validate it.

The example below is a small python server that validates if the device has full disk encryption enabled or not.

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

def check_compliance(json_data, target_name):
    for item in json_data:
        if item.get("name") == target_name:
            return item.get("compliant")
    return None

@app.route('/validate_token', methods=['POST'])
def validate():
    data = request.get_json()
    token = data.get('token', None)

    is_compliant = False

    if token is not None:

        # Perform validation against the Ensure api.
        response = requests.get("https://ensure-agent.alertsec.com/checks/temp/" + token)
        if response.status_code == 200:
          try:
              json_data = response.json()
              if check_compliance(json_data, "encryption"):
                is_compliant = True
          except ValueError:


    if is_compliant:
      return jsonify({"status": "success", "message": "user is compliant"})
    else:
      return jsonify({"status": "error", "message": "user is not"})
if __name__ == '__main__':
    app.run()

Examples