Miscellaneous

Miscellaneous functions and procedures (refer to the following table) do not fit into any other category.

egrep

• Version 4.0 and earlier: egrep() function not available.
• Version 5.0 and later: egrep() function available.

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Description

The egrep() function runs the policy server host’s egrep() command using the provided arguments and files, and returns the result as a string.

Syntax

egrep ([egrep-arguments, ] search-pattern, filename-or-template [, filenameor-template …]);

Arguments

Return values

A string that contains the output of egrep().

Example

result = egrep ("-w", "word", "filename");
result = egrep ("pattern", "manynames*");

fgrep

• Version 4.0 and earlier: fgrep() function not available.
• Version 5.0 and later: fgrep() function available.

Description

The fgrep() function runs the policy server host’s fgrep command using the provided arguments and files, and returns the result as a string.

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Syntax

fgrep ([fgrep-arguments, ] search-pattern, filename-or-template [, filenameor-template …]);

Arguments

Return values

A string that contains the output of fgrep.

Example

result = fgrep ("-w", "word", "filename");
result = fgrep ("pattern", "manynames*");

glob

Description

The glob() function searches a character string for a specific shell-style pattern. glob() is often used to match patterns to file names because the patterns that are used are the same patterns that are used by the Unix/Linux shell file name matching algorithms.

ℹ️

Note

For more information on creating search patterns, see Wildcard Search Characters and quote.

Syntax

result = glob (pattern, string);

Arguments

Return values

Example

result = glob (pattern, logfilename);

grep

• Version 4.0 and earlier: grep() function not available.
• Version 5.0 and later: grep() function available.

Description

The grep() function runs the policy server host’s grep command using the provided arguments and files, and returns the result as a string.

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Syntax

grep ([grep-arguments, ] search-pattern, filename-or-template [, filename-ortemplate …]);

Arguments

Return values

A string containing the output of grep.

Example

result = grep ("-w", "word", "filename");
result = grep ("pattern", "manynames*");

iologcloseaction

Description

iologcloseaction() is used to specify a program to be executed on the log server (or policy server, if no log server ) when an iolog is closed.

This can be used, for example, to execute scripts that can send IOlog or ACA data to Splunk or other systems. When Endpoint Privilege Management for Unix and Linux is installed, an example Perl script called closeactionsplunk.pl, that sends ACA data from the IOlog to Splunk is installed in /opt/pbul/scripts.

Note that unlike the iologcloseactionrunhost() procedure, this does not include the ability to specify runuser, runcwd, environment, timeout, or command line arguments.

IOLogs with a closeaction specified, or when Solr is used, are placed in a queue, rather than acted upon immediately.

pbconfigd monitors the queue and launches pbreplay to handle both Solr and iologcloseaction activity.

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Syntax

iologcloseaction( command );

Arguments

Example

iologcloseaction("/opt/pbul/scripts/closeactionsplunk.pl");

iologcloseactionrunhost

Description

iologcloseactionrunhost() is used to specify a /path/filename to be executed on the runhost when the iolog is closed. The specified /path/filename can be a shell script or binary. The user to run the program as, environment, arguments, and working directory are specified in the function call. Stdin, stdout, stderr are redirected to /dev/null.

The timeout (specified in seconds) is mandatory. A timeout value of zero indicates no timeout. Note that a timeout value greater than zero causes the end user’s invocation of pbrun to pause while the close action takes place or until the timeout expires.

Any runtime errors such as invalid user, cwd, or command are logged via syslog, and to the appropriate EPM log (for example,pbrunlog, pblocaldlog) if specified in pb.settings.

Syntax

Iologcloseactionrunhost( user, environment, timeout, cwd "/path/command and arguments");

Arguments

Example

iologcloseactionrunhost(  "jsmith", {"PATH=/bin", "TMPDIR=/tmp/", "PBUL=PBULTEST"},  20, "/tmp", "/usr/local/bin/closeaction –a –b" );

Example

iologcloseactionrunhost(  "root", {},  0, "/tmp", "/usr/local/bin/closeaction –a –b" );

ℹ️

Note

For more information, see iolog .

ipaddress

Description

The ipaddress() function returns the IP address of the machine that is specified by hostname. hostname should be a fully qualified machine name.

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Syntax

result = ipaddress (hostname);

Arguments

Return values

result contains the IP address of the specified machine. If the IP address cannot be determined, a blank string is returned (that is, length = 0).

Example

result = ipaddress (hostname);

In this example, result contains the IP address of the machine specified in hostname.

isset

Description

The isset() function determines whether a variable has been set. A variable with a blank or zero value returns true, because blank and zero are considered values.

Syntax

result = isset (string);

Arguments

Return values

Example

In this example, result contains an integer value of 1 (true) because the runhost variable has a value of beyondtrust1.

runhost = "beyondtrust1";
result = isset ("runhost");

policytimeout

Description

The policytimeout() procedure adds an overall policy timeout mechanism so that pbmasterd can abort the request when the policy processing takes an inordinate amount of time.

For example, when submitconfirmuser() is used, but the submitting user (or process) does not enter a password.

This prevents pbmasterd processes that appear to be unresponsive when the policy is waiting for user input which may never arrive. When the policy timeout is encountered, the request is rejected, with the exitstatus set to:

policy timeout (<seconds> seconds) reached for <submitting user> on host <submithost> for command <command and args>

That message is also logged to pbmasterd.log.

This timeout mechanism terminates pbmasterd any time that the policy processing takes longer than the timeout value specified.

This includes any user input functions, infinite loops, long running external programs run with system() and remotesystem(), DNS and NFS hangs, and lengthy policies.

When the policytimeout() procedure is called at the beginning of the policy it applies to the entire policy. If called later, it applies to the rest of the policy.

If the function is not called, or called with a value of 0, there is no timeout and pbmasterd processes the entire policy (including waiting for user input) before terminating.

The policytimeout() procedure can be called many times, each time overriding the value previously set.

This timeout is canceled when an accept or reject is encountered (for example, the policy is completed). Note that this timeout does not affect the runconfirmuser mechanism, which is processed after an accept. This timeout does not affect the secured task once accepted. For example, this cannot protect against a user not providing username/password input for pbrun telnet . pbmasterd informs EPM clients (pbrun, pbksh, pbsh, pbssh) of the timeout, and those clients also timeout. Note that the exact timing of pbmasterd timing out and the client timing out is not exact.

pbmasterd and the client process the timeout independently, and either may terminate before the other. Older clients cannot process such a timeout, and may appear unresponsive when pbmasterd terminates during expected user input. pbmasterd does not have a mechanism to interrupt an older client that is expecting input.

When remotesystem() is used with the submithost, the policy timeout is independent of the timeout specified in the remotesystem function call. The first of those timeouts to be encountered is the one that is processed.

When remotesystem() is used with a host other than the submithost, only the timeout specified in the remotesystem function call is used. If that is 0 (meaning no timeout), and the policy server encounters the policy timeout, the remote host may have a hungpblocald process.

Syntax

policytimeout( <timeout_value_in_seconds> );

Arguments

Return values

Not applicable

Example

policytimeout(25);
submitconfirmuser(user);
accept;

Example

tmout=2;
policytimeout(tmout);
submitconfirmuser(user);
accept;

Example

policytimeout(25);
...
policytimeout(40);
...
policytimeout(0);
...

quote

Description

The quote() function encloses a string in the specified character. It also inserts a backslash character (\) in front of any special characters that are contained in the string, to indicate that these characters should be taken literally (that is, treated as special characters). The quote() function is useful when parsing arguments into commands that are shell scripts.

ℹ️

Note

For more information on special characters, see Special Characters.

Syntax

result = quote (string1, quotechar);

Arguments

Return values

result contains the quoted string.

Example

In the example:

result = quote ("Hello, Hello, Hello", "*");

result is assigned:

"*Hello, Hello, Hello*"

remotesystem

Description

Introduced in Endpoint Privilege Management for Unix and Linux 7.1, remotesystem() is used to run commands on a host other than the policy server host (any Endpoint Privilege Management for Unix and Linux runhost) as part of the policy. This can be called as a procedure (command output is shown on pbrun's terminal) or as a function (command output is captured into a policy variable). This is similar to the system() function/procedure, however the command is run on a different host. The Endpoint Privilege Management for Unix and Linux variable status is set to the return code of the command upon exit. Input to the command comes from the user's keyboard or from the inputstring argument if it is present. Output goes to the user's screen or to the result string variable, if present.

If the specified host is the same as the submithost, the requesting program (pbrun, pbksh, pbsh) executes the command. If the specified host is not the submithost, pblocald is used to execute the command.

This is primarily intended to be used as a function, without interactive keyboard or screen I/O. Limited I/O is allowed, however programs such as vi are not supported.

This policy function requires Endpoint Privilege Management for Unix and Linux 7.1 clients (pbrun, pbsh, pbksh, pbssh, pblocald).

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Syntax

[result =] remotesystem( hostname, user, environment, timeout, cwd, "command and arguments" [,inputstring]);

Arguments

Return values

If the result variable is specified, remotesystem() acts as a function returning the output of the command. If the result variable is not specified, the output from the command that is executed by the remotesystem() procedure appear on stderr of the requesting program (pbrun, pbsh, pbksh, pbssh).

The Endpoint Privilege Management for Unix and Linux variable status is set to the return code. In general, a return code of 0 means the command completed successfully. For a description of non-zero return codes, see the documentation for the command that is being run. A status of -15 indicates a timeout.

Example

In this example, the processlist variable is assigned the output from the ps command executed on the submithost. Note that the optional input argument is a set of empty quotes, meaning that the command is not given any input.

processlist = remotesystem( submithost, "root", {"PATH=/bin","TMPDIR=/tmp/"}, 20, "/tmp", "ps -ef", "" );

Example

In this example, again, the processlist variable is assigned the output from the ps command executed on the submithost. Note that the optional input argument is not provided, meaning that the submituser's keyboard is connected through to the command. Note that bash -c is used to allow for a shell to process the multiple commands (ps and grep).

processlist = remotesystem( submithost, "root", {"PATH=/bin","TMPDIR=/tmp/"}, 20, "/tmp", "bash -c 'ps -ef | grep ^" +user+"'");

Note

For more information, see status.

runtimewarn

Description

After the specified number of minutes, a message is written to the user’s stderr. If the optional message argument is not specified, the default message is: WARNING: You have exceeded the maximum allowed session time.

Internally, this feature makes use of the new read-only policy variables runtimewarn and runtimewarnmsg to communicate the details from the policy server to the run host.

This feature might typically be used to warn a user of an upcoming timeout specified by the runtimelimit variable.

The runtimewarn time limit is specified in minutes (within a procedure), while runtimeout is specified in seconds (as a variable).

This feature may also be used with the new runtimewarnlog() procedure described below.

Syntax

runtimewarn( minutes [, message] );

Arguments

Example

runtimewarn(20);  
runtimewarn(20, "Warning, your session will expire soon!");

runtimewarnlog

Description

This feature requires an I/O log. After the specified number of minutes, a message is written to the log server’s syslog. This message allows variable substitution using the %variable% syntax. Any variable recorded in the Accept event can be incorporated into the message. When the finish event is logged, the new timelimitexceeded variable is set to 1. If the time limit is not exceeded, the timelimitexceeded variable is not recorded in the finish event. If the optional message argument is not specified, the default message is: user:%user% exceeded time limit as %runuser%@%runhost% for %runargv%

Internally, this feature makes use of the new read-only policy variables runtimewarnlog and runtimewarnlogmsg to communicate the details from the policy server to the run host.

This feature might typically be used to create log entries of the longer sessions, possibly after warning a user using runtimewarn() of an upcoming timeout specified by the runtimelimit variable.

ℹ️

Note

The runtimewarnlog time limit is specified in minutes (within a procedure), while runtimeout is specified in seconds (as a variable).

Syntax

runtimewarnlog( minutes [, message] );

Arguments

Example

runtimewarnlog(20);
runtimewarnlog(20, "user:%user% exceeded session time limit");

system

Description

The system() function is used to run commands on the policy server host as part of the policy. The Endpoint Privilege Management for Unix and Linux variable status is set to the return code of the command upon exit. By default, commands that are run by the system() function are run as root. However, commands can be run as different users by setting the Endpoint Privilege Management for Unix and Linux variable subprocuser.

Input to the command comes from the user’s keyboard or from the inputstring if it is present. Output goes to the user’s screen or to the result string variable, if present.

ℹ️

Note

Not supported in Endpoint Privilege Management for Linux (EPM-L).

Syntax

[result =] system (command [,inputstring]);

Arguments

Return values

result contains the output of the command. If the result variable is not specified, the output from the command that is executed by the system() function appears on stderr of the requesting program (pbrun, pbsh, pbksh).

The Endpoint Privilege Management for Unix and Linux variable status is set to the return code. In general, a return code of 0 means the command completed successfully. For a description of non-zero return codes, see the documentation for the command that is being run.

Example

In this example, result is assigned date\n because the echo command outputs the string date with a newline character.

result = system ("echo date");

ℹ️

Note

For more information, see policygetenv, policysetenv, policyunsetenv, status, and subprocuser.

unset

Description

The unset procedure is used to remove temporary variables from the event and I/O log files when the variables are no longer needed. Variables that are required for the functioning of an EPM daemon may not be unset.

Syntax

unset (variable);

Arguments

Return values

Not applicable

Example

In this example, removes the temporary variable xyz from the log files.

unset("xyz");