pbcheck

The pbcheck program processes a policy file and produces a report of syntax or language problems, or an entitlement report. The policy server daemon (pbmasterd) reports any policy file errors to a log file; however, pbcheck should be used to detect errors before you install a policy file on a live system.

With no options, pbcheck performs a run-check on the policy file that is specified in your settings file.

The -c option to check licenses has been retired. Use pbadmin --lic -l for this purpose.

With the -e option, pbcheck produces an entitlement report in CSV format. The output data contains the columns submithost, user, command, argv, runhost, runuser, runcommand, and runargv. When a field has no value, the entitlement report displays an empty string for that field.

The policy file must first be syntactically correct, so you should run pbcheck to check the policy syntax before running pbcheck -e. Because pbcheck -e processes the policy without arguments, you should ensure that the logic of the policy works even if no argument is passed to it.

With the -U, -C, or -H options, pbcheck produces a formatted text entitlement report that is sorted by user, command, or host, respectively. If more than one of these options is specified, then each of the reports is produced, one after the other. Using the -x or --csv2 option, you can export the entitlement data to Microsoft® Excel CSV format.

In CSV format, the resulting data is presented as comma-separated values and contains ASCII-formatted information for the following (in this order):

  • Submit host
  • User
  • Command
  • Argv
  • Accept/reject/error text
  • Run host
  • Run user
  • Run command
  • Run argv
  • Iolog (yes/no): Not displayed when detail level is low
  • Policy file name: Not displayed when detail level is low
  • Policy line number: Not displayed when detail level is low
  • Policy Server host: Displayed only when detail level is high
  • Dependencies: Displayed only when detail level is high
  • Constraints: Semi-colon separated. Displayed only when detail level is high

The fields displayed in this format are displayed as empty quotation marks ("") if they were not specified in the policy; this means they could be any value.

If a field contains Can not evaluate soft … expression in the output, it means the policy was setting the corresponding variable to a value that can be evaluated only at runtime (when running pbrun), such as argv, date, time, and so on.

With the option -H, each submit host is displayed on the top, followed by as many lines as necessary containing the other fields in the same order as above (except the submit host field).

Host: <submithost>
<submitUser> <command> <argv> <Accept/Reject/Error Text> <runHost> <runUser>
   <runCommand> <runArgv> <iolog> <policyName> <policyLineNumber> <masterHost>
   <dependency> <constraints>

With the option -U, each user is displayed on the top, followed by as many lines as necessary containing the other fields in the same order as above (except the user field).

User: <user>
<submitHost> <command> <argv> <Accept/Reject/Error Text> <runHost> <runUser>
   <runCommand> <runArgv> <iolog> <policyName> <policyLineNumber> <masterHost>
   <dependency> <constraints>

With the option -C, each command is displayed on the top, followed by as many lines as necessary containing the other fields in the same order as above (except the command field).

Command: <command>
<submitHost> <submitUser> <argv> <Accept/Reject/Error Text> <runHost>
   <runUser> <runCommand> <runArgv> <iolog> <policyName> <policyLineNumber>
   <masterHost> <dependency> <constraints>

The fields displayed in -H, -U, and -C are displayed as <UNSPECIFIED> if they were not specified in the policy, and means they could have any value.

The fields iolog, policyname, and policyLineNumber are not displayed if detail level is low, and the fields masterhost, dependency, and constraints are displayed only when detail level is high.

The entitlement report mechanism uses a temporary work file before creating the final report. This temporary file is created in the $TMPDIR directory. If the TMPDIR environment variable is not set (or is set to /tmp/), the workfile is written in the /tmp directory.

Temporary files that are owned by root in /tmp are a potential vulnerability. We recommend you set TMPDIR=/var or some other appropriate directory where normal users do not have write access.

Policies that use looping constructs which modify the iterating variable within the loop do not work correctly. Policies that test the contents of argv or runargv may produce incomplete results.

Policies that use data that is known only at an actual run-time (such as the date and argv variables) produce incomplete results. In these cases, warnings and errors use the term soft when referring to variables that cannot be fully evaluated.

If a policy contains conditions that are based on external data sources or on external files that are generated at run time, the entitlements are evaluated as if the conditions are true. The last column (displayed when the --detail option is set to High), Constraint, shows that each row is displayed when a condition is accepted. For example, if the policy checks whether a user belongs to a certain netgroup before accepting the command, the report shows the command for this user as accepted; the Constraint field shows the condition that the user belongs to the netgroup. At runtime, a particular user listed in the report might actually not be part of that netgroup, and therefore gets rejected.

The constraint option enables you to limit the report by using any valid Privilege Management for Unix and Linux policy language expression.

-c "user=='dba'" -c "host in {'A', 'B'}"

This limits the report to dba privileges on hosts A and B.

Most user defined functions are not properly processed for entitlement reporting.

pbcheck evaluates a limited set of functions in a constraint when those functions are used against the output variables submithost, user, command, runhost, runuser, and runcommand. The supported functions are basename(), tolower(), and toupper().

Examples of constraints whose function calls are evaluated are:

  • basename(command) in Allowed_Cmds
  • tolower(user) in Allowed_Users
  • toupper(submithost) in Allowed_Hosts

All other functions are not evaluated, and do not show actual values for the affected output field.

The following policy does not produce specific values in the command field:
gsub("^.*/", "", command) in Allowed_Cmds

It does, however, insert that whole constraint in the command field for informational purposes.

The -b (--nobasename) option for pbcheck has been deprecated because pbcheck now evaluates the basename() function.

  • Version 3.5 and earlier: long command options not supported.
  • Version 4.0 and later: long command options supported.
pbcheck [options] [command [arguments]]
   -f, --file=file_name
   -h, --host=host_name
   -r, --run
   -s, --syntax
   -t, --type
   -x, --csv2
   -p, --policydir=directory
   -L, --showlists[=listname [,listname]...]
   -S, --showduplicates
pbcheck [options] [-c constraint [-c constraint]...] [command [arguments]]
   -f, --file=file_name
   -p, --policydir=directory
      -e,--entitlement [=abridged|standard|extended| exhaustive]
      -b, --nobasename
      -l, --uselistnames[=columnname[,columnname]...]
   --maxchildren <number>
   --maxloopchildren <number>
   -U, --user_report
   -H, --host_report
   -C, --command_report
   -D, --detail[=low|medium|high]
   -d, --display_headers
   -A, --accepted
   -R, --rejected
   -I, --rejected_implicit
   -c, --constraint=expression
   -x, --csv2
pbcheck -v | --version
pbcheck --help
-A, --accepted

Optional. For entitlement reporting only. Report accepted commands (default).

May be combined with -I and -R.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-b, --nobasename

Obsolete. Optional. For entitlement reporting only. Remove basename function calls from the entitlement report, leaving only the command or runcommand.

Version 6.0 and earlier: option not available.

Version 6.1 through 6.2.2: option available.

Version 6.2.3 and later: option deprecated.

This is the built-in default behavior of pbcheck.

-c, --constraint =expression

Optional. Restrict the entitlement report to items that match the expression (for example, -c "user=='root'").

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-C, --command_report

Optional. Produce a formatted entitlement report in command sequence.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-d, --display_headers

Optional. Display the field headers as the top of an entitlement report.

Version 6.0.0 and earlier: option not available.

Version 6.0.1 and later: option available.

-D, --detail [=low|medium|high]

Optional. Produce the specified level of detail.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-e, -entitlement [=abridged|standard| extended|exhaustive]

Optional. Produce entitlement data in CSV format. The optional arguments are:

abridged: Simplest and fastest method. It ignores the interactions between different if statements and groups similar data (for example, users or hosts) during evaluation.

standard (default): Slower and more detailed method. It tracks the interactions between different conditionals.

extended: Method providing more detail. It tracks interactions between different conditionals and evaluates the policy for each member of a list, rather than treating the list as a group.

exhaustive: Method providing more detail. The output is currently the same as extended, but may be changed in the future.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-f, --file=file_name Optional. The file name to check. Defaults to the normal policy file.
-h, --host=host_name

Optional. Simulate a check with a remote host name.

-H, --host_report

Optional. Produce a formatted entitlement report in host sequence.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-I, --rejected_implicit

Optional. For entitlement reporting only. Report commands that are implicitly rejected at the end of the policy. May be combined with -A and -R.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-l, --uselistnames [=column_name [,column_name]...]

Optional. For entitlement reporting only. Replace the list values with the name of the list variable for all fields or for specific fields. Valid field names are submitHost, submitUser, command, runHost, runUser, and runCommand. When specifying multiple field names, enter them as comma-separated values (no spaces). Omit the field name to replace all applicable fields with the list variable name.

Statements that act on individual items (for example, switch and case) cause the list to be expanded in the report, regardless of the -l option.

If the run variables runuser and runcommand are not explicitly set in the policy, their values will depend on the variables user and command. For more information, please see the Privilege Management for Unix and Linux Policy Language Guide.

In such a case, the --uselistnames option applied to user and command fields (submitUser, command) automatically affect the output of their corresponding run variables (fields runUser and runCommand). Similarly, if a policy has an explicit dependency for runhost on submithost, then the --uselistnames option applied to the submitHost field are also reflected in the runHost field.

Version 6.0 and earlier: option not available.

Version 6.1 and later: option available.

-L, --showlists [listname [,listname]...]

Optional. Show members of all lists or of specific lists. Omit the list name to display members of all lists.

Version 6.2.2 and earlier: option not available.

Version 6.2.3 and later: option available.

--maxchildren <number>

Limit the total number of live pbcheck descendant processes. After this limit is reached, the entire pbcheck process tree is terminated. This is a safety mechanism to prevent crippling a system with too many processes. The default value is 200. Increasing the value should only be necessary for policies with a large number of if, case, or looping statements that do not result in an Accept or a Reject.

Version 6.1 and earlier: option not available.

Version 6.2 and later: option available.

--maxloopchildren <number>

Limit the number of child processes that evaluate the same policy line (for example, an endless loop). After this limit is reached, the process that encounters the same line for the specified number of iterations issues a diagnostic message indicating the policy line and statement. Then the process exits. That child’s parent and all ancestors are free to continue processing, resulting in a possibly incomplete entitlement report. This is a safety mechanism to prevent crippling a system with too many processes. The default value is 25.

Version 6.1 and earlier: option not available.

Version 6.2 and later: option available.

-p, --policydir =directory

Optional. Provide a policy directory to control include files in the configuration policy. If a file name in an include statement starts with a slash (/), then that file is used. Otherwise, the directory that is specified using the -p option is used to search for the file in the include statement.

-r, --run

Optional. Perform run-time checking (forces syntax and type checking).

-R, --rejected

Optional. For entitlement reporting only. Report commands that are rejected by an explicit Reject statement. May be combined with -A and -I.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

-s, --syntax

Optional. Perform syntax checking.

-S, --showduplicates

Optional. Show information on lists with duplicate members.

Version 6.2.2 and earlier: option not available.

Version 6.2.3 and later: option available.

-t, --type

Optional. Perform type checking (forces syntax checking).

-U, --user_report

Optional. Produce a formatted entitlement report in user sequence.

Version 4.0 and earlier: option not available.

Version 5.0 and later: option available.

[command [arguments]] Optional. Search through the policy for the specified command and arguments to display whether it is accepted or rejected. The command and its arguments must be specified last in the pbcheck argument list. If the pbcheck argument list includes options that Accept arguments, they must be specified before command.
-v, --version

Optional. Displays the version information on stderr and exits.

-x, --csv2

Optional. Export entitlement data in Microsoft Excel CSV format.

Version 6.2 and earlier: option not available.

Version 6.2.1 and later: option available.

--help

Optional. Displays the program’s help message and exits.

Privilege Management for Unix and Linux policy file

Perform a syntax check of the user-specified configuration file pb.mainconfig located in /etc
pbcheck –f /etc/pb.mainconfig

For more information, please see the following: