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 easier to provide management information such as user entitlement reports.

The policy data is grouped into users, hosts, commands, time/dates, and roles.

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.

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.

ℹ️

Note

For more information on entitlement reports, see View Entitlement Reports.

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: