Creating a custom profile with custom rules

You can create a custom rule to use with a custom profile. This section assumes that you are starting from a new profile of your own design, and not from a custom profile created from a PowerSC profile. You might choose this procedure if the PowerSC profiles do not meet your needs.

For the most seamless PowerSC integration, the custom rule should follow PowerSC conventions, such as returning an error with a message, returning success, and undoing the operation when needed.

The following list summarizes the high-level steps you must perform to create a custom rule:

Copy an existing rule script to create your new rule.
Modify the script to perform your new functionality.
Make sure to verify all use cases (enforce, check, undo).
Make sure to return proper success and error codes.
Use the POST /profiles/{profileLibrary}/{profileName} API through Swagger to create the profile for your custom rule. This API creates the needed PowerSC PowerSCProfileBean version of your custom profile and ensures that the profile is available in the PowerSC GUI.
Use the PowerSC GUI to copy the custom profile to a group of endpoints
Use the PowerSC GUI to verify that all use cases work properly.

Examine the PowerSC rule scripts and use one or more as templates for your rule script. The PowerSC rule scripts use the bash shell, but you don't have to follow this convention.
- The PowerSC Linux rules are in /etc/security/pscxpert/bin.
- The PowerSC AIX rules are in /etc/security/pscexpert/bin.

For example, consider the cisv2_gnome_automount rule in the Linux_CISv2_Lev1_RHEL9 profile. This rule uses the relatively straightforward /etc/security/pscxpert/bin/gnome_automount script, which is instructive without being overly complex.

Note: The cisv2_gnome_automount rule first calls the /etc/security/pscxpert/bin/adapter script to do some needed configuration and check the arguments. /etc/security/pscxpert/bin/adapter then invokes /etc/security/pscxpert/bin/gnome_automount.

#!/usr/bin/bash
#
#       COMPONENT_NAME: (PSCXPERT)gnome_automount
#       FUNCTIONS:
#
#       Syntax:
#              gnome_automount  -{c|e} [v] <local_args> <value>
#
# ROCKET_PROLOG_BEGIN_TAG
# //* Copyright Rocket Software, Inc. or its affiliates 2023 *
# //* All Rights Reserved.                                            *
# ROCKET_PROLOG_END_TAG


source ${BIN_DIR}/linux-ice-common a 

if [[ $PSCXPERT_UNDO == "1" ]]; then b 
    rm -f /etc/dconf/db/local.d/00-media-automount
    dconf update
    exit 0
fi

case $1 in
    "$LINUX_ICE_ENFORCE" | "$LINUX_ICE_ENFORCE_VERBOSE") c 
        undo="NA"
        if [ "$1" == "$LINUX_ICE_ENFORCE_VERBOSE" ]; then
                set -x
        fi

        setting=$(gsettings get org.gnome.desktop.media-handling automount)
        if [[ $setting != "false" ]]; then
            echo "[org/gnome/desktop/media-handling]" >> /etc/dconf/db/local.d/00-media-automount
            echo "automount=false" >> /etc/dconf/db/local.d/00-media-automount
            echo "automount-open=false" >> /etc/dconf/db/local.d/00-media-automount
            dconf update

            undoparm=""
            generate_undo_metadata "${PSCXPERT_NAME}" "Undo" "${PSCXPERT_DESC}" "No prereq"  \
                "${PSCXPERT_COMMAND}" "${undoparm}" "Group not supported yet"
        fi

        ;;

 "$LINUX_ICE_CHECK" | "$LINUX_ICE_CHECK_VERBOSE") c 
        if [ "$1" == "$LINUX_ICE_CHECK_VERBOSE" ]; then
            set -x
        fi

        setting=$(gsettings get org.gnome.desktop.media-handling automount)
        if [[ $setting != "false" ]]; then
            echo "%$ICE_STATUS_NON_COMPLIANT%"$(msg "Gnome automount is not disabled.")
            exit 1
        fi
        ;;
    *)
        echo "%$ICE_STATUS_EINVAL%"$(msg "Usage: %s -{c|e}[v] <local_args> <value>" "$(basename ${BASH_SOURCE[0]})") d 
        exit 1
        ;;
esac

echo "%$ICE_STATUS_OK%" e 
exit 0

Callout Notes:

PowerSC rules use two operating-system specific scripts to provide some initial setup and establish variables. For example, all of the *ICE* constructs used elsewhere in this script are defined here. You may find that these scripts provide useful functions to your custom rule. Review these scripts for the operating system type of the endpoints to which you want to apply your custom rule. Do not modify these scripts.
- AIX: /etc/security/pscexpert/bin/initialize_variables
- Linux: /etc/security/pscxpert/bin/linux-ice-common
By PowerSC convention, your custom rule must be able to undo any operations it performs. An undo operation calls your custom rule like an enforce operation, except that it sets a variable called PSCXPERT_UNDO to the value of 1.

Select the operation to perform, such as enforcing a change or checking a status.

case $1 in
"$LINUX_ICE_ENFORCE" | "$LINUX_ICE_ENFORCE_VERBOSE")
   some_enforcement_operation

;;
"$LINUX_ICE_CHECK" | "$LINUX_ICE_CHECK_VERBOSE")
   some_check_operation
;;
esac

Return an error with a message.

echo "%$ICE_STATUS_EINVAL%$(basename ${BASH_SOURCE[0]}):" $(msg "Missing arguments.")
	exit 1

Return success.
```
echo "true%$ICE_STATUS_OK%"
exit 0
```

Copy and modify your chosen template script to perform your new functionality.
Test your script from outside of PowerSC. PowerSC does not validate the script.

Use the POST /profiles/{profileLibrary}/{profileName} API through Swagger to create the profile for your custom rule:

If you have not already done so, follow the steps in Getting started with Swagger UI to get started with Swagger UI.
Expand the Profiles section.
Click POST /profiles/{profileLibrary}.
Click Try it Out
Select custom from the profileLibrary list.
Specify the profile name for the profile to create as profile-name.xml in the profileName text box. Identify Linux, IBM® i, HMC, and VIOS profile names by their respective (Linux_, IBMi_, HMC_, and VIOS_) prefix. AIX-specific profile names do not have a prefix.
Select the media type from the list. This controls the header accept type in the curl command. Possible values are application/json and application/xml. You can generally accept the default of application/json.

Supply the request body in the following format.

{
  "comments": [
    {
      "value": "string"
    }
  ],
  "entries": [
    {
      "function": "string",
      "name": "string",
      "args": "string",
      "command": "string",
      "group": "string",
      "prereqlist": "string",
      "ruleType": "string",
      "description": "string",
      "descSetNum": "string",
      "descMsgNum": "string",
      "descCatalog": "string",
      "defaultDesc": "string"
    }
  ],
  "profileType": "string"
}

Consider the following example. For demonstration purposes the example specifies only a single rule.

{
  "comments": [
    {
      "value": "This is my custom profile"
    }
  ],
  "entries": [
    {
      "function": "gnome_automount",
      "name": "my_gnome_automount",
      "args": "",
      "command": "/etc/security/pscxpert/bin/adapter /etc/security/pscxpert/bin/my_gnome_automount",
      "description": "Implements my custom profile to ensure GDM automatic mounting of removable media is disabled.",
      "group": "Company policy recommendations",
      "prereqlist": "",
      "ruleType": "CISv2cust",
      "isLinux": true       
    },
  ],
  "profileType": "CISv2cust"
}

Click Execute.

Swagger UI submits the request and shows the curl command that was submitted.

curl -X 'POST' \
  'https://your-system-name/ws/powerscui/profiles/custom/Linux_gnome.xml' \
  -H 'accept: */*' \
  -H 'Authorization: Basic a21jZG9ub3VnaDpHdW5zMTUwR3Vuc3N1ZWVtaWx5bQ==' \
  -H 'Content-Type: application/json' \
  -d '{
  "comments": [
    {
      "value": "This is my custom profile"
    }
  ],
  "entries": [
    {
      "function": "gnome_automount",
      "name": "my_gnome_automount",
      "args": "",
      "command": "/etc/security/pscxpert/bin/adapter /etc/security/pscxpert/bin/my_gnome_automount",
      "description": "Implements my custom profile to ensure GDM automatic mounting of removable 
           media is disabled.",
      "group": "Company policy recommendations",
      "prereqlist": "",
      "ruleType": "CISv2cust",
      "isLinux": true       
    },
  ],
  "profileType": "CISv2cust"
}'

If successful, the Responses section shows the response with an HTTP status code of 200 OK.

Use the PowerSC GUI to view your custom profile and ensure that it is correct:
1. From the main page, select the Profile Editor tab.
  The Profile Editor page opens.
2. Click the downward arrow to open the list of profiles. The drop-down menu lists the Built-in Profiles and Custom Profiles that are available.
3. Expand the Custom Profiles list.
4. Select the profile that you created.
5. Click the Edit Profile icon. Your custom profile opens in edit mode.
6. Verify that the profile is correct, and repeat Steps 5.h and 5.i if needed.
Manually copy your script file to the following location on each required uiAgent:
- Linux uiAgents: /etc/security/pscxpert/bin
- AIX uiAgents: /etc/security/pscexpert/bin
Copy the custom profile to your chosen group of endpoints, as described in Copying a custom profile to a group of endpoints.
(Linux endpoints only) The POST /profiles/{profileLibrary}/{profileName} API generates XML with an AIX-specific prefix. If you copied the custom profile to one or more Linux systems, you must edit the profile XML file and change the prefix.
1. ssh to a Linux endpoint.
2. Change directory to /etc/security/pscxpert/custom.
3. Edit the XML file for your custom profile.
4. Change every occurrence of <AIXP and </AIXP to <PSCxp and </PSCxp, respectively.
5. Save the changes.
6. Copy the edited profile to the /etc/security/pscxpert/custom directory of each required Linux endpoint.
Simulate or apply the custom profile to your chosen group of endpoints, as described in Simulating compliance levels and profiles and Applying compliance levels and profiles, respectively.
If you need to undo the profile, follow the steps described in Undoing compliance levels. The undo action from your script is invoked by the Undo action on the Compliance page using the following undo action rules.
- For AIX, the undo action rules are written to the /etc/security/aixpert/core/undo.xml file.
- For Linux, the undo action rules are written to the /etc/security/pscxpert/core/undo.xml file.