Create policy files

A security policy file is a collection of instructions that define the system security rules that Endpoint Privilege Management for Unix and Linux applies during task verification processing. These instructions are written using Endpoint Privilege Management for Unix and Linux Security Policy Scripting Language.

The default name of the primary Endpoint Privilege Management for Unix and Linux security policy file is pb.conf. This file is analogous to the main() function in a C program. It is possible to add Security Policy Scripting Language statements directly to pb.conf or to use security policy subfiles. Security policy subfiles are separate, individual security policy files invoked at runtime using the include statement (using the syntax include "subfilename";).

ℹ️

Note

We strongly recommend that you use security policy subfiles.

Conceptually, the include statement can be thought of as a placeholder.

At run time, EPM-UL replaces include statements with the actual contents of the specified include file. This process occurs in computer memory and does not alter the physical files in any way.

The use of security policy subfiles enables you to organize a site’s security policy implementation in a modular fashion. Using this method, each security policy subfile can focus on a specific area of security policy implementation. This compartmentalizes security policy implementation, making it much easier to maintain and enhance over time.

A common way to organize security profile files is by type of user and system access requirements.

root should own the security policy files and their permissions should be set to 400 or 600. Place the files in the same directory (we recommend /opt/pbul/policies) for convenience. The /opt/pbul/policies directory is the default location. A different directory can be specified with the policydir setting in the pb.settings file. To insure security policy file integrity, Endpoint Privilege Management for Unix and Linux does not process a security policy file if users other than root has security permissions that allow them to modify or delete the file. In other words, only root should have read/write permissions for these files, and the directories in which these files are stored should have security permissions that prevent users other than root from reading, modifying, or deleting them.

Security policy files are usually created with a standard text editor. They are saved as plain text files. By default, Endpoint Privilege Management for Unix and Linux uses a .conf file name suffix for security policy files, but this is not a requirement.

When naming security policy files, any file suffix may be used, or the suffix may be omitted. Starting with v9.0, a new Role Based Policy mechanism has been implemented that allows administrators to maintain their policy in a database with an option 'change management' functionality.

Default policy

Starting with version 8.0, a default policy is installed by default if an existing policy does not exist. The files pbul_policy.conf and pbul_functions.conf are created in a /opt/pbul/policies directory (from v9.4.3+ and in /etc/pb prior to v9.4.3) by default. pbul_policy.conf are then included in the main policy (by default /opt/pbul/policies/pb.conf from v9.4.3+ and /etc/pb.conf prior to v9.4.3).

This default policy contains the following roles:

Helpdesk role

Enabled by default, when invoking pbrun helpdesk it allows any user in HelpdeskUsers (default root) to initiate a helpdesk menu as root on any host in HelpdeskHosts (default submithost only). The helpdesk menu of actions contains:

• List of processes (ps -ef)
• Check if a machine is up (ping )
• List current users on this host (who -H)
• Display host's IP settings (ifconfig -a)

PBTest

Enabled by default, for all users on all hosts, pbrun pbtest allows checking connectivity and policy.

Controlled shells

Enabled by default, allows users in ControlledShellUsers (by default the submituser), for runhosts in ControlledShellHosts (by default only submithost), to enable iologging for pbksh/pbsh. iologs are created by default in "/tmp/pb....[pbksh|pbsh].XXXXXX". This role has a list of commands (empty by default) to elevate privileges for, as well as a list of commands (empty by default) to reject.

Admin role

Enabled by default, allows users in AdminUsers (by default root) to run any command on runhosts in AdminHosts (by default only submithost).

Demo role

Disabled by default, allows users in DemoUsers (default all users) to run commands in DemoCommands (default id and whoami) as root on any host in DemoHosts (default all hosts).

The policy ends by allowing all users to run any command as themselves without any privilege escalation.

This policy is meant to be used as a starting point for your own policy. You can enable or disable any of the roles listed above by simply setting the corresponding "EnableRole" to true or false. Or you can completely delete the policy and use your own. If you choose to continue with the default policy as a starting point, you can add more users, hosts and commands to the various lists used for each role, for example you can take ControlledShellRole further by adding users to ControlledShellUsers, and hosts to ControlledShellHosts, and commands to ControlledShellRejectedCmds and ControlledShellPrivilegedCmds.

Splunk role

Disabled by default. If enabled, only when pbrun is invoked, enables iologging (creating iologs in /pbiologs), sets default ACA rule, enables aca session history and sets iologcloseaction to a script sending records to Splunk.

Sudo role

Disabled by default, allows users in SudoUsers (only root, by default) to run any command on runhosts defined in SudoHosts (default submithosts).

This serves as a demo policy for the sudo wrapper which requires policy modification before it is installed. It illustrates what changes to start with to make all the sudo wrapper options available.

ℹ️

Note

For more information on the sudo wrapper, see Sudo wrapper.

Role-Based Policy database schema

Role based policy has been implemented to simplify the definition of policy for administrators. Policies are kept within structured records in a database, simplifying maintenance, decreasing system load, increasing throughput, and providing a comprehensive REST API to integrate policy management with existing customer systems and procedures, including simplified bulk import/export of data. Once the customers' data is held within the Role Based Policy database it is much easier to provide management information, such as user entitlement reports. The policy data is grouped into users, hosts, commands, time/dates and roles detailed in the schema below.

User groups

User groups define groups of users and/or wildcard patterns that match usernames:

CREATE TABLE usergrp (
    id INTEGER PRIMARY,
    name TEXT UNIQUE,
    description TEXT,
    disabled INTEGER CHECK(disabled BETWEEN 0 AND 1), -- 0=enabled, 1=disabled
    type CHAR(1) CHECK (type IN ('I','E')), -- I=internal, E=external
    extinfo TEXT -- external lookup info
);
CREATE TABLE userlist (
    id INTEGER REFERENCES usergrp(id),
    user TEXT, -- "glob" wildcard
PRIMARY KEY(id,user)
);

Each user group has multiple user list entries that specify names, wildcards, or both, that match both submit and run user names when matched by the role.

Host groups

Host groups define groups of hosts, wildcard patterns, or both, that match hostnames:

CREATE TABLE hostgrp (
    id INTEGER PRIMARY,
    name TEXT UNIQUE,
    description TEXT,
    disabled INTEGER CHECK(disabled BETWEEN 0 AND 1), -- 0=enabled, 1=disabled
    type CHAR(1) CHECK (type IN ('I','E')), -- I=Internal, E=external
    extinfo TEXT -- external lookup info
);
CREATE TABLE hostlist (
    id INTEGER REFERENCES hostgrp(id),
    host TEXT, -- "glob" wildcard
PRIMARY KEY(id,host)
);

Each host group has multiple host list entries that specify names and/or wildcards that match both submit and run host names when matched by the role.

Command groups

Command groups define groups of commands, wildcard patterns, or both, that match commands:

CREATE TABLE cmdgrp (
    id INTEGER PRIMARY,
    name TEXT UNIQUE,
    description TEXT,
    disabled INTEGER CHECK(disabled BETWEEN 0 AND 1)-- 0=enabled, 1=disabled
);
CREATE TABLE cmdlist (
    id INTEGER REFERENCES cmdgrp(id),
    cmd TEXT, -- "glob" wildcard
    rewrite TEXT, -- new command (see below)
PRIMARY KEY(id,cmd)
);

Each command group has multiple command list entries that specify commands and/or wildcards that match the submitted command name when matched by the role, and a rewrite column to rewrite the command that is executed. The rewrite is in a similar format to Bourne/Bash shell arguments, for example, $0, $1, $*, $#etc. Rewrite uses the original command to substitute arguments into the new rewritten command.

Time/date groups

Time/date groups define groups of times/dates and/or wildcard patterns that match times/dates:

CREATE TABLE tmdategrp (
    id INTEGER PRIMARY,
    name TEXT UNIQUE,
    description TEXT,
    disabled INTEGER CHECK(disabled BETWEEN 0 AND 1)-- 0=enabled, 1=disabled
);

CREATE TABLE tmdatelist (
    id INTEGER REFERENCES tmdategrp(id),
    tmdate TEXT, -- json format - see below
PRIMARY KEY(id,tmdate)
);

Each time/date group has multiple time/date list entries that specify times/dates, wildcards, or both, that match the submitted command name when matched by the role, and a rewrite column to rewrite the command that is executed. Each individual time/date is specified in JSON format, and can be one of two different formats:

• From/To specific date range: both from and to are specified in epoch seconds:

  '{ "range" : { "from" : 1415851283, "to": 1415887283 }}'
  

• Day of the week: each day is specified as an array of hours.

  Each hour is a number representing 15 minute intervals defined as a binary mask:

  1 1 1 1
        ^  0 to 14 minutes of the hour
      ^-- 15 to 29 minutes of the hour
    ^---- 30 to 44 minutes of the hour
  ^------ 45 to 59 minutes of the hour
  Therefore the values range from 0 to 15:
      '{
      "mon" : [0,0,0,0,0,0,0,15,15,15,15,15,15,15,15,15,15,15,3,0,0,0,0,0,0],
      "tue" : [0,0,0,0,0,0,0,15,15,15,15,15,15,15,15,15,15,15,3,0,0,0,0,0,0],
      "wed" : [0,0,0,0,0,0,0,15,15,15,15,15,15,15,15,15,15,15,3,0,0,0,0,0,0],
      "thu" : [0,0,0,0,0,0,0,15,15,15,15,15,15,15,15,15,15,15,3,0,0,0,0,0,0],
      "fri" : [0,0,0,0,0,0,0,15,15,15,15,15,15,15,15,15,15,15,3,0,0,0,0,0,0],
      "sat" : [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
      "sun" : [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
  }'
  

Roles

Roles are the entities that tie all the other entities together to define a role.

CREATE TABLE role (
    id INTEGER PRIMARY,
    name TEXT UNIQUE,
    rorder INTEGER, -- rule order for matching
    description TEXT,
    disabled INTEGER CHECK(disabled BETWEEN 0 AND 1), -- 0=enabled, 1=disabled
    risk INTEGER CHECK(risk >= 0),
    action CHAR(1) CHECK (action IN ('A','R')), -- A=Accept, R=Reject
    iolog TEXT, -- iolog template
    script TEXT -- pbparse script
    tag TEXT DEFAULT NULL -- Arbitrary tag that will allow grouping of roles
    comment TEXT DEFAULT NULL -- Arbitrary comment field that can contain anything
    message TEXT DEFAULT NULL -- Accept/reject message (templated)
    variables TEXT DEFAULT NULL -- Contains JSON formatted Policy Script variables to set (templated)
    varmatch TEXT DEFAULT NULL -- Contains JSON formatted Policy Script variables to match
    auth TEXT DEFAULT NULL -- Contains JSON formatted array of authentication methods (templated)
    rpt INTEGER DEFAULT 1 -- 1=on, 0=off, include Role in Entitlement Report
);
CREATE TABLE roleusers (
    id INTEGER REFERENCES role(id),
    users INTEGER REFERENCES usergrp(id),
    type CHAR(1) CHECK (type IN ('S','R')), -- S=Submit, R=Run User
    PRIMARY KEY (id,users,type)
);
CREATE TABLE rolehosts (
    id INTEGER REFERENCES role(id),
    hosts INTEGER REFERENCES hostgrp(id),
    type CHAR(1) CHECK (type IN ('S','R')), -- S=Submit, R=Run User
    PRIMARY KEY (id,hosts,type)
);
CREATE TABLE rolecmds (
    id INTEGER REFERENCES role(id),
    cmds INTEGER REFERENCES cmdgrp(id),
    PRIMARY KEY (id,cmds)
);
CREATE TABLE roletmdates (
    id INTEGER REFERENCES role(id),
    tmdates INTEGER REFERENCES tmdategrp(id),
PRIMARY KEY (id,tmdates)
);

Each role has multiple users, hosts, commands and time/dates. When the Policy Engine matches against roles, complete records are selected from the database as fully populated roles, sorted by the role attribute rorder. Once the first record has been matched, the attributes of the role are applied to the session, and the Policy Engine accepts or rejects the session. The iolog template is the normal script format log file, for example /var/log/io_ log.XXXXXX.

The script is a full EPM script that is called if the role is accepted. The script can carry out extra processing to authorize the session (and can therefore override the accept/reject status with an implicit command), and can carry out extended environment configuration as would a normal EPM script.

Role "Auth" attribute

A column holding a JSON formatted configuration provides the flexibility of the multiple authentication methods that script policy currently employs. The applicable functions are then called by Role Based Policy authorization functions in a similar way as the script based policy.

A database column, formatted in JSON format provides extra authentication options. The column is a JSON array of methods that are called in order, and REJECT when the first one fails. Each array element is a JSON object with a method and attributes:

{"method" : "getstringpasswd", "passwd" : <string>, "prompt":"<string>", message":"<string>", "rejectMessage":"<string>", "tries":<num>}

{"method" : "getuserpasswd", "user":<string>, "fname" : <string>, "prompt":"<string>", message":"<string>", "rejectMessage":"<string>", "tries":<num>, "period" : <num>}

{"method" : "getuserpasswdpam", "user":<string>, "service" : <string>, "fname" : <string>, "prompt":"<string>", message":"<string>", "rejectMessage":"<string>", "tries":<num>, "period" : <num>}

{"method" : "submitconfirmuser",  "user":<string>, "fname" : <string>,  "prompt":"<string>", message":"<string>", "rejectMessage":"<string>", "tries":<num>, "period" : <num>}

{"method" : "submitconfirmuserpam",  "user":<string>, "service" : <string>, "fname" : <string>,  "prompt":"<string>", message":"<string>", "rejectMessage":"<string>", "tries":<num>, "period" : <num>}

There are also three other variables (runconfirmuser, runconfirmmessage, runconfirmpasswdservice) that affect reauthentication. However, because these are policy script variables as opposed to functions, these are implemented in a similar way. In this respect, these variables should be set in the Variables column, and are templated in a similar manner.

Example

{ "runconfirmuser" : "%user%" }

Matching EPM variables for a role

A JSON formatted column allows the matching of roles based upon variables submitted by the client, for example pbclientmode. Matched values are wildcarded using normal glob(3) rules.

The format of the object is similar to:

{  "varmatch" : { "pbclientmode" : "pbrun", "year" : "201[678]" }}

Role-Based Policy, change management events

There are two different approaches to maintaining the role-based policy database. The first, simple method is to access the tables using pbdbutil at the command line. Each change is individual, and instantaneous, and is immediately live. Although for smaller organizations this is adequate, larger organizations have a more controlled procedural access method.

Role-based policy database change transactions can be enabled using the pb.setting rbptransactions. Once enabled, before changes can be made, the administrator must begin a change transaction, specifying a reason why the change is being made. This is logged and the whole role-based policy database is then locked for update - only that administrator can continue to make changes. These changes will NOT be mirrored in the live authorization process and can continue to be made by that administrator alone, and when completed can be committed or rolled back. Once the changes are committed they are all applied to the database as one update, and a change management event is generated. If the changes are rolled back, they are discarded and nothing changes.

If a change transaction is begun, and the administrator fails to close the transaction, any other administrator with access can force the rollback of the changes. Once again, this requires a reason specifying, and logs a change management event. The change transactions are necessary once the GUI policy updates are implemented to force database integrity. See the section below for Change Transaction command line options.

To enable the logging of change management events each client needs the pb.setting changemanagementeventsm yes and log servers will need to defined the eventdb and need the REST pbrest service running.

Settings

The following settings are used and need to be set when Role-based policy and change management is implemented and used:

policydb

• The path to the Role Based Policy database.
• There is no default for this setting.

pbresturi

• The partial REST url string between the hostname and /REST.
• There is no default for this setting.

pbrestport <port#>

• The REST port.
• Default value is the base port + 6.

rolebasedpolicy <yes/no>

• Enabled/Disable Role Based Policy checking.
• The default is no.

eventdb

• The path to the Change Management event database.
• There is no default for this setting.

rbptransactions <yes/no>

• Enable the use of Role Based Policy transactions to ensure integrity.
• The default is no.

changemanagementevents <yes/no>

• Enable/Disable the logging of Change Management events when maintaining databases.
• The default is no.

pbresttimeskew

• The maximum time in seconds that hosts are mis-matched by (it is recommended that the customer uses a time synchronization service).
• The default is 60 seconds.

Role-Based Policy entitlement reports

Role-based policy Entitlement reports are available to the user from the pbrun command using -e, or to the administrator as an overall report using pbdbutil --rbp -R. They provide a comprehensive report on what users can access commands on which hosts, and when they are allowed to run them.

pbdbutil: Role-Based Policy options

The pbdbutil Role Based Policy options are described below.

pbdbutil --rbp [<options>] [ <file> <file> ...]
-R { json param } Report user entitlements from the database
    -R Add option to display commands
        -R Add option to display time/date restrictions
           -R Add option to display additional role options
-E { json param }  List user entitlements data from the database
    where { json param } is one or more of:
    "submituser" : "user1" Specify submit user or wildcard
    "submithost" : "host1" Specify submit host or wildcard
    "runuser"    : "user1" Specify run user or wildcard
    "runhost"    : "host1" Specify run host or wildcard
"command"    : "command" Specify command or wildcard

pbrun options

The following options are available only when Role Based Policy is enabled:

Custom functions

What are custom functions?

Custom functions (also referred to as user written functions) are standalone units of security code you write that perform specific programming tasks. After you write a function you can invoke it in any security policy file to perform its specific task or function.

How are custom functions useful to my organization?

To help simplify security policy implementation, the Security Policy Scripting Language enables the security administrator to write custom functions and procedures. For more information about the difference between these two, see Functions and procedures.

Functions are standalone units of security code that perform specific programming tasks. After you write a function you can invoke it in any security policy file to perform its specific task or function.

Important information

In most cases, the order of the instructions in a security policy file is not important. The user’s security requirements determine the rules that the file contains.

The overall structure of a security policy file is user-written functions first, followed by a security policy code.

Best practices

• Write functions for repetitive programming tasks. This centralizes the logic and allows for updating in one place while reusing it in multiple places.
• By centralizing the logic for a repetitive type task in a single function, all of the security policy files that call the function automatically benefit from any updates that are made to the function.

Syntax checking

Always check the syntax of a security policy file before putting it into production. If a request encounters a security policy file syntax error, then the task that causes the error is immediately rejected. The Reject event is logged in the Endpoint Privilege Management for Unix and Linux event log.

Syntax checking is done with pbcheck, an Endpoint Privilege Management for Unix and Linux utility program. It performs two functions:

• Security policy file syntax validation
• Simulates security processing for test task requests to determine if that task request would be accepted or rejected during production processing

ℹ️

Note

For more information, see pbcheck.

Policy debugging

Policies can be debugged via the pbadmin --poldbg command.

ℹ️

Note

For more information, see poldbg.

Environment variable processing considerations

As discussed earlier, it is possible to install pbrun, pbmasterd, pblocald, and/or pblogd on different machines (that is, the submit host, policy server host, run host, and log host may represent different physical machines). When this is the case, each of these separate machines can have its own set of users, groups, and environment variables, which can differ from host to host.

ℹ️

Note

If pbrun, pbmasterd, and/or pblocald are installed on different machines, then the environment variables on those machines can contain different values.

For instance, a user might have one home directory on the submit host and another on the run host. In another example, a user group list on policy server host can be different from the same user group list on the run host. This situation might arise if the policy server host is not an NIS client or has fewer entries in its /etc/passwd file.

Security policy file processing always takes place on the policy server host machine, while task execution takes place on the run host machine. When the policy server host and run host represent different machines, by default, it is the user and group information on the policy server host machine that is accessed during security profile file processing. If it is necessary to access users or groups only on the run host machine, then special pass-through values must be used. When these values are encountered during security profile file processing, pbmasterd passes through the value to the run host machine to be resolved when the task runs.

ℹ️

Note

The execute_via_su mechanism enables the runhost's environment for the runuser, overriding the run environment that the policy on the policy server has set up. Note also that the runenvironmentfile feature can also be used to add runhost specific environment variables.

ℹ️

Note

For more detailed information on using pass-through values, see Task Information Variables.

Support for multiple-byte character sets

The policy language supports the processing of UTF-8 encoded multiple-byte character strings. In addition, several variables (indicated by i18n_ in their names) format UTF-8 encoded date and time values according to the operating system’s locale settings.