ServiceNow VR Setup Guide

/**
* NodeZero ServiceNow VR Integration — setup script (v2.1.0)
*
* Run from: System Definition → Scripts - Background (scope: Global).
* Idempotent — safe to re-run. Prints a summary at the end.
*
* Creates: dedicated `sn_vul.nodezero_integration` role (inherits
* `sn_vul.vulnerability_admin`), integration definition + instance,
* 6 ACLs + role grants (minimal validated set),
* 5 severity map rows, 3 business rules
* (CI match trigger via CILookupUtil + DI→VI cascades).
*
* Does NOT create: service account (credentials) or CI Lookup Rules
* (customer-designed against their CMDB). See Customer Setup Guide.
*
* Kept ES5-compatible (no template literals / arrow functions / let-const)
* so it runs on older SNOW Background Script engines without ES2021 mode.
*/
(function () {
    var VERSION = '2.1.0';
    var INTEGRATION_NAME = 'NodeZero';
    var INTEGRATION_ID = 'com.horizon3.nodezero';           // stable programmatic key for the integration definition
    var ROLE_NAME_BASE = 'sn_vul.vulnerability_admin';      // OOTB role we inherit from
    var ROLE_NAME_NZ = 'sn_vul.nodezero_integration';       // dedicated role granted to the integration service account

    var stats = { created: 0, skipped: 0, updated: 0, errors: 0 };
    var log = function (m) { gs.print('[NZ setup] ' + m); };
    var warn = function (m) { gs.warn('[NZ setup] ' + m); stats.errors++; };

    log('NodeZero setup script v' + VERSION + ' — starting');

    // ------------------------------------------------------------------ helpers

    function lookupSysId(table, field, value) {
        var gr = new GlideRecord(table);
        gr.addQuery(field, value);
        gr.setLimit(1);
        gr.query();
        return gr.next() ? gr.getUniqueValue() : null;
    }

    // lookup: string (addEncodedQuery) OR object {field: value} (addQuery per key).
    // Use object form when any value contains '^' (SNOW's AND separator).
    function upsert(table, lookup, fields, label) {
        try {
            var gr = new GlideRecord(table);
            if (typeof lookup === 'string') gr.addEncodedQuery(lookup);
            else for (var lk in lookup) gr.addQuery(lk, lookup[lk]);
            gr.setLimit(1);
            gr.query();
            if (gr.next()) {
                var changed = false;
                for (var k in fields) {
                    var cur = String(gr.getValue(k) || '');
                    var des = fields[k] === true ? '1'
                            : fields[k] === false ? '0'
                            : String(fields[k]);
                    if (cur !== des) { gr.setValue(k, fields[k]); changed = true; }
                }
                if (changed) {
                    gr.update(); stats.updated++;
                    log('UPDATED ' + label + ' (' + gr.sys_id + ')');
                } else {
                    stats.skipped++;
                    log('SKIPPED ' + label + ' — already matches (' + gr.sys_id + ')');
                }
                return gr.getUniqueValue();
            }
            var ins = new GlideRecord(table);
            ins.initialize();
            for (var f in fields) ins.setValue(f, fields[f]);
            var sysId = ins.insert();
            if (sysId) { stats.created++; log('CREATED ' + label + ' (' + sysId + ')'); return sysId; }
            warn('Insert returned no sys_id for ' + label); return null;
        } catch (e) { warn('Error on ' + label + ': ' + e); return null; }
    }

    function grantRole(aclSysId, roleSysId, label) {
        try {
            var gr = new GlideRecord('sys_security_acl_role');
            gr.addQuery('sys_security_acl', aclSysId);
            gr.addQuery('sys_user_role', roleSysId);
            gr.setLimit(1); gr.query();
            if (gr.next()) {
                stats.skipped++;
                log('SKIPPED role grant on ' + label + ' — already present');
                return;
            }
            var ins = new GlideRecord('sys_security_acl_role');
            ins.initialize();
            ins.setValue('sys_security_acl', aclSysId);
            ins.setValue('sys_user_role', roleSysId);
            if (ins.insert()) { stats.created++; log('CREATED role grant on ' + label); }
            else warn('Failed to grant role on ' + label);
        } catch (e) { warn('Error granting role on ' + label + ': ' + e); }
    }

    // ---------------------------------------------------------- resolve scopes

    var scopeVR = lookupSysId('sys_scope', 'scope', 'sn_vul');
    var scopeSecCmn = lookupSysId('sys_scope', 'scope', 'sn_sec_cmn');
    var roleVulAdmin = lookupSysId('sys_user_role', 'name', ROLE_NAME_BASE);
    if (!scopeVR || !scopeSecCmn || !roleVulAdmin) {
        gs.error('[NZ setup] FATAL — could not resolve required scopes or role. ' +
            'Is Vulnerability Response installed? Aborting.');
        return;
    }
    log('Resolved scopes: VR=' + scopeVR + ', SecCmn=' + scopeSecCmn +
        ', role ' + ROLE_NAME_BASE + '=' + roleVulAdmin);

    // -------------------------------------------------- NodeZero Integration role
    // Dedicated role granted to the integration service account. Inherits
    // sn_vul.vulnerability_admin (so the service account gets the standard VR
    // permissions) and on top of that receives the NodeZero-specific table
    // write ACLs provisioned below. Customer assigns this role to the service
    // account instead of granting sn_vul.vulnerability_admin directly, so the
    // integration's privileges can be scope-tracked under one named role.

    log('--- Role ---');
    var roleNodeZero = upsert('sys_user_role', {name: ROLE_NAME_NZ}, {
        name: ROLE_NAME_NZ,
        description: 'Granted to the NodeZero integration service account. ' +
            'Inherits ' + ROLE_NAME_BASE + ' for read/write on standard VR tables; ' +
            'ACLs provisioned by snow-setup.js add the NodeZero-specific writes.',
        sys_scope: scopeVR
    }, 'role ' + ROLE_NAME_NZ);
    if (!roleNodeZero) {
        gs.error('[NZ setup] FATAL — could not provision NodeZero role. Aborting.');
        return;
    }

    // Inheritance: nodezero_integration contains vulnerability_admin
    (function () {
        var gr = new GlideRecord('sys_user_role_contains');
        gr.addQuery('role', roleNodeZero);
        gr.addQuery('contains', roleVulAdmin);
        gr.setLimit(1); gr.query();
        if (gr.next()) {
            stats.skipped++;
            log('SKIPPED role inheritance ' + ROLE_NAME_NZ + ' contains ' + ROLE_NAME_BASE + ' — already present');
            return;
        }
        var ins = new GlideRecord('sys_user_role_contains');
        ins.initialize();
        ins.setValue('role', roleNodeZero);
        ins.setValue('contains', roleVulAdmin);
        if (ins.insert()) {
            stats.created++;
            log('CREATED role inheritance: ' + ROLE_NAME_NZ + ' contains ' + ROLE_NAME_BASE);
        } else {
            warn('Failed to create role inheritance');
        }
    })();

    // ---------------------------------------------------- Integration Definition

    log('--- Integration Definition ---');
    var integrationDefSysId = upsert('sn_sec_int_integration',
        'id=' + INTEGRATION_ID, {
            name: INTEGRATION_NAME,
            id: INTEGRATION_ID,
            source: INTEGRATION_NAME,
            integration_type: 'MANUAL',
            is_reapply_ci_lookup_supported: true,
            is_auto_close_supported: false,
            ire_source_name: 'VR-NodeZero',
            configurable: true,
            short_description: 'NodeZero pentest vulnerability data from Horizon3.ai'
        }, 'integration definition');
    if (!integrationDefSysId) {
        gs.error('[NZ setup] FATAL — integration definition could not be created. Aborting.');
        return;
    }

    // ------------------------------------------------------ Integration Instance

    log('--- Integration Instance ---');
    upsert('sn_sec_int_impl',
        'name=' + INTEGRATION_NAME + '^integration=' + integrationDefSysId, {
            name: INTEGRATION_NAME,
            integration: integrationDefSysId,
            active: true,
            description: 'NodeZero pentest vulnerability data from Horizon3.ai'
        }, 'integration instance');

    // -------------------------------------------------------------------- ACLs
    // Identification: our ACLs are the only ones that grant the NodeZero role
    // on this exact (name, operation, scope). Lookup is a JOIN against
    // sys_security_acl_role — SNOW's ACLDescriber regenerates the description
    // field after role grants, so a description marker wouldn't survive.

    log('--- ACLs ---');
    // Minimal set: inherited vulnerability_admin already covers record-level
    // writes and most field writes; these add only what OOTB withholds.
    var ACLS = [
        // [name, operation, scope]
        ['sn_vul_third_party_entry',             'create', scopeVR],     // TPE record-create (OOTB denies)
        ['sn_vul_third_party_entry.*',           'write',  scopeVR],     // TPE field writes (OOTB .* restrictive)
        // bypasses the OOTB conditional write ACL (vulnerabilityISEMPTY) that
        // otherwise strips this field on insert; net-new ACL.
        ['sn_vul_vulnerable_item.vulnerability', 'create', scopeVR],     // let vulnerability survive insert
        ['sn_vul_vulnerable_item.src_ci',        'write',  scopeVR],     // DI<->VI link (OOTB field ACL restrictive)
        ['sn_sec_cmn_src_ci',                    'write',  scopeSecCmn], // DI record update; also gates DI field writes
        ['sn_sec_cmn_src_ci.source',             'write',  scopeSecCmn]  // DI `source` tag (OOTB specific ACL restrictive)
    ];

    function findAclByRoleGrant(aName, aOp, aScope) {
        var ar = new GlideRecord('sys_security_acl_role');
        ar.addQuery('sys_user_role', roleNodeZero);
        ar.addQuery('sys_security_acl.name', aName);
        ar.addQuery('sys_security_acl.operation', aOp);
        ar.addQuery('sys_security_acl.sys_scope', aScope);
        ar.setLimit(1);
        ar.query();
        return ar.next() ? ar.getValue('sys_security_acl') : null;
    }

    // Fallback: find our ACL directly if the role grant wasn't inserted yet
    // (e.g., a prior run crashed between ACL insert and role grant insert).
    // Without this, the next run would create a duplicate ACL.
    function findAclDirect(aName, aOp, aScope) {
        var gr = new GlideRecord('sys_security_acl');
        gr.addQuery('name', aName);
        gr.addQuery('operation', aOp);
        gr.addQuery('sys_scope', aScope);
        gr.setLimit(1);
        gr.query();
        return gr.next() ? gr.getUniqueValue() : null;
    }

    for (var i = 0; i < ACLS.length; i++) {
        var aName = ACLS[i][0], aOp = ACLS[i][1], aScope = ACLS[i][2];
        var label = 'ACL ' + aName + '/' + aOp;
        // Don't set `description` — SNOW's ACLDescriber auto-generates it from
        // the role grant and overwrites anything we set.
        var fields = {
            name: aName, operation: aOp, type: 'record',
            decision_type: 'allow', active: true,
            advanced: false, admin_overrides: false,
            sys_scope: aScope
        };
        var aclSysId = findAclByRoleGrant(aName, aOp, aScope);
        var roleGrantExists = aclSysId !== null;
        if (!aclSysId) aclSysId = findAclDirect(aName, aOp, aScope);
        if (aclSysId) {
            // Update existing ACL in place
            var gr = new GlideRecord('sys_security_acl');
            gr.get(aclSysId);
            var changed = false;
            for (var k in fields) {
                var cur = String(gr.getValue(k) || '');
                var des = fields[k] === true ? '1'
                        : fields[k] === false ? '0'
                        : String(fields[k]);
                if (cur !== des) { gr.setValue(k, fields[k]); changed = true; }
            }
            if (changed) {
                gr.update(); stats.updated++;
                log('UPDATED ' + label + ' (' + aclSysId + ')');
            } else {
                stats.skipped++;
                log('SKIPPED ' + label + ' — already matches (' + aclSysId + ')');
            }
            if (roleGrantExists) {
                stats.skipped++;
                log('SKIPPED role grant on ' + label + ' — already present');
            } else {
                // ACL existed from a prior half-completed run; fix the missing role grant
                grantRole(aclSysId, roleNodeZero, label);
            }
        } else {
            // Create new ACL and grant role
            var ins = new GlideRecord('sys_security_acl');
            ins.initialize();
            for (var f in fields) ins.setValue(f, fields[f]);
            aclSysId = ins.insert();
            if (aclSysId) {
                stats.created++;
                log('CREATED ' + label + ' (' + aclSysId + ')');
                grantRole(aclSysId, roleNodeZero, label);
            } else {
                warn('Insert returned no sys_id for ' + label);
            }
        }
    }

    // -------------------------------------------------------- Severity Mapping

    log('--- Severity Mapping ---');
    for (var sv = 1; sv <= 5; sv++) {
        upsert('sn_vul_severity_map',
            'source=' + INTEGRATION_NAME + '^source_value=' + sv, {
                source: INTEGRATION_NAME,
                source_value: String(sv),
                target_value: sv,
                integration_type: 'vr'
            }, 'severity map ' + sv + '→' + sv);
    }

    // --------------------------------------------------------- Business Rules
    // Lookup by name — unique per NodeZero BR and doesn't collide with OOTB BRs
    // that may share the same collection + filter_condition. Names kept ≤40
    // chars to avoid SNOW's name-field truncation.

    log('--- Business Rules ---');

    function installBR(collection, filter, name, when, onInsert, order, script, desc) {
        upsert('sys_script',
            { name: name }, {
                name: name, collection: collection, when: when,
                action_insert: onInsert, action_update: true,
                action_delete: false, action_query: false,
                active: true, advanced: true, order: order,
                filter_condition: filter, script: script, description: desc
            }, 'BR: ' + name.replace(/^NodeZero\s*—\s*/, ''));
    }

    var NL = '\n';

    // CILookupUtil calls discoveredItem.update() internally; reevaluate_ci
    // must be reset to false beforehand or that nested update re-fires this BR.
    installBR(
        'sn_sec_cmn_src_ci', 'reevaluate_ci=true',
        'NodeZero — run CI match immediately', 'async', true, 100,
        [
            "(function executeRule(current, previous /*null when async*/) {",
            "    if (current.source.integration.id + '' != '" + INTEGRATION_ID + "') return;",
            "    current.setValue('reevaluate_ci', false);",
            "    new sn_sec_cmn.CILookupUtil().processDiscoveredItem(current);",
            "})(current, previous);"
        ].join(NL),
        'When a NodeZero DI is inserted/updated with reevaluate_ci=true, run CI Lookup Rules immediately via CILookupUtil with OOTB default behavior. Unmatched DIs get a sn_sec_cmn_unmatched_ci placeholder linked as cmdb_ci, surfacing the host in the VR workspace.');

    // DI-side cascade — propagates cmdb_ci from a matched DI to its existing VIs.
    installBR(
        'sn_sec_cmn_src_ci', 'cmdb_ciISNOTEMPTY^cmdb_ciVALCHANGES^EQ',
        'NodeZero — DI→VI CI cascade (on DI)', 'after', false, 200,
        [
            "(function executeRule(current, previous /*null when async*/) {",
            "    if (current.source.integration.id + '' != '" + INTEGRATION_ID + "') return;",
            "    var vi = new GlideRecord('sn_vul_vulnerable_item');",
            "    vi.addQuery('src_ci', current.sys_id);",
            "    vi.setValue('cmdb_ci', current.getValue('cmdb_ci'));",
            "    vi.updateMultiple();",
            "})(current, previous);"
        ].join(NL),
        "When a NodeZero DI's cmdb_ci changes (e.g. matched by CI Lookup rule), cascade the CI reference to all VIs linked to this DI via src_ci.");

    // VI-side cascade — fills cmdb_ci on new VIs from their linked DI.
    installBR(
        'sn_vul_vulnerable_item', 'source=NodeZero^cmdb_ciISEMPTY^src_ciISNOTEMPTY',
        'NodeZero — DI→VI CI cascade (on VI)', 'before', true, 100,
        [
            "(function executeRule(current, previous /*null when async*/) {",
            "    var diCmdbCi = current.src_ci.cmdb_ci + '';",
            "    if (diCmdbCi) current.setValue('cmdb_ci', diCmdbCi);",
            "})(current, previous);"
        ].join(NL),
        "New NodeZero VIs arrive after their DI has been inserted and CI-matched. The DI-side cascade rule updates existing VIs when DI.cmdb_ci changes, but can't update VIs that don't exist yet. This rule fills in cmdb_ci on VI insert by dot-walking src_ci to cmdb_ci.");

    // ----------------------------------------------------------------- summary

    log('=====================================================');
    if (stats.errors > 0) {
        // Use gs.warn directly — the `warn` helper increments stats.errors.
        gs.warn('[NZ setup] !!!  SETUP DID NOT FULLY COMPLETE — ' + stats.errors + ' ERROR(S) !!!');
        gs.warn('[NZ setup] Scan the log above for "WARN" lines to see what failed.');
        gs.warn('[NZ setup] The script is idempotent: fix the cause and re-run to finish setup.');
    } else {
        log('NodeZero setup complete.');
    }
    log('Created: ' + stats.created + ' / Updated: ' + stats.updated +
        ' / Skipped: ' + stats.skipped + ' / Errors: ' + stats.errors);
    log('=====================================================');
    if (stats.errors === 0) log('Next: define CI Lookup Rules (see Customer Setup Guide).');
})();