MidCommand Script Include

MidCommand is a utility Script Include for executing synchronous shell commands on MID Servers from both client-side and server-side scripts. It handles ECC Queue interaction, role-based access control, and secure credential management.

Download: https://developer.servicenow.com/connect.do#!/share/contents/6327452_midcommand

Problem Statement

Executing commands on a MID Server typically requires writing records to the ECC Queue and polling for responses. This asynchronous process involves:

• Inserting a record into the ecc_queue output queue
• Polling the input queue for the response
• Parsing the XML payload

This repetitive pattern requires boilerplate code in every script. Additionally, passing sensitive data (API keys, passwords) as command arguments can expose credentials in ECC Queue logs unless explicitly encrypted.

What It Does

MidCommand abstracts the ECC Queue communication into a reusable utility with built-in security features:

• Synchronous execution wrapper: Handles the write-poll-read cycle and returns a JSON object containing stdout, stderr, and command
• Role-based access control: Enforces user validation against the execute.midServerCommand.roles system property
• Configurable timeout: Prevents indefinite polling (default: 40 seconds)
• Optional encryption: Encrypts command payloads using sn_automation.AutomationAPI before writing to ECC Queue
• Credential injection: Retrieves secrets from Discovery Credentials and injects them into command templates without exposing plaintext values

Security Features

Access Control

The utility validates the calling user's roles against the execute.midServerCommand.roles system property (default: admin). Unauthorized execution attempts return an "Access Denied" error.

Command Encryption

When the encrypt parameter is set to true, the command string is encrypted before insertion into the ECC Queue. The MID Server decrypts it at runtime, ensuring the command is never stored in plaintext in the database.

Credential Management

The executeWithCredential method integrates with ServiceNow's credential store:

1. Retrieves the credential using sn_cc.StandardCredentialsProvider
2. Extracts the specified attribute (e.g., password, api_key)
3. Injects the secret into the command template (replacing ${password} or ${attribute_name})
4. Encrypts the final command before writing to ECC Queue
5. Sanitizes the ECC response to replace any plaintext command with the encrypted version

Usage Examples

Server-Side: Standard Execution

For non-sensitive commands such as system checks or status queries:

var runner = new MidCommand();
var result = runner.execute('mid_server_linux_01', 'df -h', 30);

if (result.stdout) {
    gs.info('Output:\n' + result.stdout);
} else {
    gs.error('Error:\n' + result.stderr);
}

Server-Side: Credential-Aware Execution

For commands requiring authentication (database queries, API calls, etc.):

var credSysId = '0123456789abcdef0123456789abcdef';
var commandTemplate = './deploy_script.sh --apikey ${password}';

var runner = new MidCommand();
var result = runner.executeWithCredential(
    'mid_server_linux_01', 
    commandTemplate, 
    credSysId
);

Client-Side: GlideAjax Execution

To execute commands from client scripts (UI actions, client scripts, etc.):

var ajax = new GlideAjax('MidCommand');
ajax.addParam('sysparm_name', 'execute');
ajax.addParam('sysparm_midServer', 'mid_server_linux_01');
ajax.addParam('sysparm_command', 'echo "Hello"');
ajax.addParam('sysparm_timeout', '30');
ajax.addParam('sysparm_encrypt', 'false');

ajax.getXMLAnswer(function(response) {
    var result = JSON.parse(response);
    console.log('stdout: ' + result.stdout);
    console.log('stderr: ' + result.stderr);
});

Use Cases

• Running diagnostic commands during troubleshooting workflows
• Executing deployment scripts that require credential injection
• Querying remote systems or databases via command-line tools
• Automating maintenance tasks (log rotation, cache clearing, service restarts)
• Integrating with third-party APIs via curl or CLI tools

Configuration

The update set includes:

• Script Include: MidCommand (client-callable)
• System Property: execute.midServerCommand.roles (default: admin)
• ACL: Restricts execution to users with specified roles

To allow additional roles, update the execute.midServerCommand.roles property with a comma-separated list (e.g., admin,mid_server_user).