GuardRails Installation Guide

This page contains all the files and detailed instructions to install GuardRails on your instance.

For our latest user guide, please follow this link:

GuardRails First-Time Install Guide

First Time Installation Instructions

You must install GuardRails in production first. Please follow the instructions below to complete the production installation before beginning installation on sub-production. The order of instructions must be followed in sequence. If you do not follow these instructions in sequence, unexpected behaviour will occur.

GuardRails Production Installation Instructions

The following instructions only need to be completed once on your production instance. To deploy GuardRails into production, you must create a Service Account with an Admin role. We have streamlined this account creation process below with an automated script that will generate the account with the required role(s). To run this automated script:

  1. Change your application scope to Global.
  2. In the Filter navigator field, type Scripts – Background. A console will be displayed.
  3. Copy and paste the code below into the console and click Run script.
  4. A runtime log will be displayed. Copy the generated password as you will need it later.
				
					/* Function to generate combination of password */
function generatePass() {
    var pass = '';
    var str =
        'ABCDEFGHIJKLMNOPQRSTUVWXYZ' +
        'abcdefghijklmnopqrstuvwxyz0123456789@#$';

    for (var i = 1; i <= 20; i++) {
        var ch = Math.floor(Math.random() * str.length + 1);

        pass += str.charAt(ch);
    }

    return pass;
}
var scope = gs.getCurrentScopeName();

gs.info('GuardRails Installer Starting...');

try {
    if (scope != 'rhino.global') {
        throw 'Current scope is not Global. Please change application scope to Global before running installer.';
    }

    gs.info('Setting Table Flags...');

    var gr = new GlideRecord('sys_db_object');

    gr.addQuery('name', 'sys_upgrade_history_log');

    gr.query();

    if (gr.next()) {
        gr.access = 'public';
        gr.read_access = true;

        if (gr.update()) {
            gs.info('Successfully updated sys_upgrade_history_log.');
        }
    }

    var gr = new GlideRecord('sys_db_object');

    gr.addQuery('name', 'sys_update_version');

    gr.query();

    if (gr.next()) {
        gr.read_access = true;

        if (gr.update()) {
            gs.info('Successfully updated sys_update_version.');
        }
    }

    

    gs.info('Installing GuardRails Pipelines dependencies...');
} catch (err) {
    gs.error('GuardRails Installer Error: ' + err);
}
//Create Service Account
gs.info('GuardRails Production Installer Starting...');
var gr = new GlideRecordSecure('sys_user');
gr.initialize();
var password = generatePass();
var username = 'GuardRailsSvcAccount';
gr.user_name = 'GuardRailsSvcAccount';
gr.web_service_access_only = true;
gr.user_password.setDisplayValue(password);
gr.active = true;
var user = gr.insert();
gs.warn(
    'WARNING: THIS PASSWORD WILL ONLY BE DISPLAYED ONCE. PLEASE COPY AND STORE IN CLIPBOARD FOR FUTURE REFERENCE'
);
gs.info('Service Account Created with Password:' + password);
gs.info('Granting Service Account Admin...');
var nr = new GlideRecordSecure('sys_user_has_role');
nr.initialize();
nr.user = user;
nr.role = '2831a114c611228501d4ea6c309d626d'; //admin
nr.insert();
gs.info('Granted Admin role.');

gs.info('Setting GuardRails Properties...');
var produrl =
    'https://' + gs.getProperty('instance_name') + '.service-now.com/';
//set properties

gs.setProperty('x_dynas_guardrails.dev.password', password);

gs.setProperty('x_dynas_guardrails.dev.username', username);

gs.setProperty('x_dynas_guardrails.production.url', produrl);

gs.setProperty('x_dynas_guardrails.production.username', username);

gs.setProperty('x_dynas_guardrails.production.password', password);

gs.info('Completed setting properties.');
				
			

Complete the Installation for Production

 

  1. Change your Application Scope to GuardRails.
  2. In the Filter navigator field, type GuardRails Properties.
  3. Enter your license key in the field License Key for GuardRails.
  4. In the Filter navigator field, type GuardRails Debug.
  5. Ensure that none of the stages contain ERROR. If you encounter issues, follow troubleshooting steps in section below.
  6. In the Filter navigator field, type Download Definition Updates.
  7. In the Filter navigator field, type Set Instance Version.

GuardRails Pipeline Installation Instructions

The following instructions must be completed in each sub-production instance. To deploy GuardRails into sub-production, you must create a Service Account with an Admin role. We have streamlined this account creation process below with an automated script that will generate the account with the required role(s). To run this automated script:
  1. Change your application scope to Global.
  2. In the Filter navigator field, type Scripts – Background. A console will be displayed.
  3. Copy and paste the code below into the console and click Run script.
  4. A runtime log will be displayed. Copy the generated password as you will need it later.
				
					/* Function to generate combination of password */
function generatePass() {
    var pass = '';
    var str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' +
        'abcdefghijklmnopqrstuvwxyz0123456789@#$';
  
    for (var i = 1; i <= 20; i++) {
      var ch = Math.floor(Math.random()
            * str.length + 1);
  
        pass += str.charAt(ch)
    }
  
    return pass;
  }
  var scope = gs.getCurrentScopeName();
  
  gs.info("GuardRails Installer Starting...");
  
  try {
  
    if (scope != "rhino.global") {
  
      throw "Current scope is not Global. Please change application scope to Global before running installer.";
  
    }
  
    gs.info("Setting Table Flags...");
  
    var gr = new GlideRecord("sys_db_object");
  
    gr.addQuery("name", "sys_upgrade_history_log");
  
    gr.query();
  
    if (gr.next()) {
  
      gr.access = "public";
  
      gr.read_access = true;
  
      if (gr.update()) {
  
        gs.info("Successfully updated sys_upgrade_history_log.");
  
      }
  
    }
  
    var gr = new GlideRecord("sys_db_object");
  
    gr.addQuery("name", "sys_update_version");
  
    gr.query();
  
    if (gr.next()) {
  
      gr.read_access = true;
  
      if (gr.update()) {
  
        gs.info("Successfully updated sys_update_version.");
  
      }
  
    }
  
    gs.info("Installing GuardRails Pipelines dependencies...");
  
  } catch (err) {
  
    gs.error("GuardRails Installer Error: " + err);
  
  }
  //Create Service Account 
  gs.info('GuardRails Sub Production Installer Starting...'); 
  var gr = new GlideRecordSecure('sys_user'); gr.initialize(); 
  var password = generatePass(); 
  var username = "GuardRailsSvcAccount"; 
  gr.user_name = "GuardRailsSvcAccount"; 
  gr.web_service_access_only = true; 
  gr.user_password.setDisplayValue(password); 
  gr.active = true; var user = gr.insert() 
  gs.warn('WARNING: THIS PASSWORD WILL ONLY BE DISPLAYED ONCE. PLEASE COPY AND STORE IN CLIPBOARD FOR FUTURE REFERENCE'); 
  gs.info('Service Account Created with Password:'+password); 
  gs.info('Granting Service Account Admin...'); 
  var nr = new GlideRecordSecure('sys_user_has_role'); 
  nr.initialize(); 
  nr.user = user; 
  nr.role = '2831a114c611228501d4ea6c309d626d'; //admin 
  nr.insert(); 
  gs.info('Granted Admin role.'); 
  gs.info('Setting GuardRails Properties...'); 
  //set properties 
  gs.setProperty("x_dynas_guardrails.dev.password", password); 
  gs.setProperty("x_dynas_guardrails.dev.username", username); 
  gs.info('Completed setting properties.');
				
			

Complete the Installation for Sub-Production

 

  1. Change your Application Scope to GuardRails.
  2. In the Filter navigator field, type GuardRails Properties.
  3. Enter the Production URL in the field Enter the production URL that was used for the production installation.
  4. Enter the Production Credentials you generated earlier in the production installation into Production Credentials fields.
  5. Enter your license key in the field License Key for GuardRails.
  6. In the Filter navigator field, type GuardRails Debug.
  7. Ensure all stages do not show “ERROR”. If you encounter issues, follow troubleshooting steps in section below.
  8. In the Filter navigator field, type Download Definition Updates.
  9. In the Filter navigator field, type Set Instance Version.

GuardRails Pipeline Installation Instructions

The following instructions must be completed in every instance. To begin the installation, you must install ALL of the required files in Installing GuardRails Files section. Follow the instructions carefully.
  1. Install all required files for Pipelines. Files can be found above at the top of this page. Follow installation instructions carefully.
  2. In the Filter navigator field, type Update Sources. A list of results is displayed.
  3. In each entryensure the URL follow this exact format including the forward slash: https://yourinstance.service-now.com/
  4. Each instance must have entries for your development instance(s).
  5. Follow user guide on how to configure your first Pipeline.

How to Install GuardRails Files (Mandatory)

File Downloads

GuardRails Pipelines Files

Download all file(s) from the links above. These files are XML Update Sets. The following instructions will walk you through how to install these files.

Installation Instructions

To complete the following instructions, ensure you are logged in with [‘Admin’] role. Install these files after you have installed GuardRails or have updated GuardRails to the latest version on the instance.

  1. In the Filter navigator field, type Retrieved Update Sets. A list of results is displayed.
  2. Click Retrieved Update Sets.
  3. On the Retrieved Update Sets screen, in the Related Links section, click Import Update Set from XML.
  4. On the Import XML window, click Choose File. Navigate to the update set and attach it.
  5. Click Upload. The update set is displayed in the Retrieved Update Sets window in Loaded state.
  6. Click Update set record.
  7. On the update set record, click Preview Update Set to preview the changes that are captured in the update set. During the update, you may get an error because of the conflicts between the files present in updates set and the files which are already present in the ServiceNow.
  8. Click Commit Update Set.

Troubleshooting using GuardRails Debug

GuardRails Requires cross scope access to applications in order to monitor and scan those applications. As a result, cross-scope access must be granted to GuardRails in order for the application to function. To grant access please follow these steps:

  1. Change your Application Scope to GuardRails.
  2. In the Filter navigator field, type Application Cross-Scope Access.
  3. Click on New. Please note the scope/target that was displayed in GuardRails Debug. (This is typically a table).
  4. In a new browser tab for the same instance, in the Filter navigator field, type Tables. (Sys Definition > Tables)
  5. Search for the table name affected as described in the GuardRails Debug. Open the record and copy the table name and scope.
  6. Return to the Application Cross-Scope Access tab you opened earlier and fill in the Target Scope, Target Name, and set Status to Allowed.
  7. Save the record and re-run debug. The affected cross-scope should no longer be displayed in debug.
  8. Repeat as necessary until ALL cross-scope errors in debug are resolved.

GuardRails Requires Table read access to tables, if the above debugging rules do not work, perform the following steps:

  1. In the Filter navigator field, type Tables and navigate to System Definition > Tables.
  2. Perform a search filter on the name of the table identified by the debug and open the record.
  3. On the table record, navigate to the Application Access form tab.
  4. Ensure that Can Read is selected. (You may need to change your application scope to save the change).
  5. Refresh the form and validate that the check box is still checked off.
  6. Re-run debug. The affected cross-scope should no longer be displayed in debug.
  7. Repeat as necessary until ALL cross-scope errors in debug are resolved.

Sometimes, the cross-scope issue cannot be resolved because ServiceNow has a known error because of the access cache in the application node. The only methods to resolve this are:

  1. Request ServiceNow HI Support to restart application nodes for affected instance(s).
  2. Wait for a Clone on affected instance(s).
  3. Wait for an Upgrade on affected instance(s).
Ensure your service account credentials are entered correctly in GuardRails Properties. Service Accounts must have the admin role.
Pipelines Common Errors

For troubleshooting why a Pipeline Instance is not correctly building please check the following before reaching out to us directly:

  1. Service account used in the environment configuration has Admin role.
  2. All instances must have configured update sources correctly. Update source URL MUST CONTAIN “/” at the end of the URL. For details how to configure an update source click here.
  3. Ensure the mandatory GuardRails Pipeline Update Set has been installed in all instances.
  4. All environments configured for the pipeline MUST have the “source” environment added as an Update Source.

**Pipelines can ONLY be run in a production instance. Pipelines should not be configured or run in a sub-production instance.**

This issue is caused by cross-scope issues. Please follow the GuardRails Debug troubleshooting steps in order to resolve. All cross-scope issues must be resolved before running a system scan.