C H A P T E R  2

Framework Functions

This chapter provides reference information on using, adding, modifying, and removing framework functions. Framework functions provide flexibility for you to change the behavior of the Solaris Security Toolkit software without modifying source code.

Use framework functions to limit the amount of coding that is needed to develop new finish and audit scripts, and to keep common functionality consistent. For example, by using the common logging functions, you can configure the reporting mechanism without needing to develop or alter any additional source code. Similarly, by using this modular code for common functions, bugs and enhancements can be more systematically addressed.

In addition, framework functions support the undo option. For example, using the framework function backup_file in place of a cp or mv command allows that operation to be reversed during an undo run.

This chapter contains the following topics:


Customizing Framework Functions

The Solaris Security Toolkit software is based on a modular framework that allows you to combine features in various ways to suit your organization's needs. Sometimes, however, the standard features provided by the Solaris Security Toolkit software might not meet your site's needs. You can supplement the standard features by customizing framework functions to enhance and extend the functionality provided by the Solaris Security Toolkit software. The framework functions configure how the Solaris Security Toolkit software runs, define the functions that it uses, and initialize environment variables.

In most cases, you can easily copy standard framework function files and scripts, and then customize their functionality for your use. For example, using the user.run file, you can add, modify, replace, or extend the standard framework functions. The user.run file is similar in purpose to the user.init file, except that you use the user.init file to add or modify environment variables.

In some cases, you might need to develop new framework functions. In this case, use similar framework functions as a guide or template for coding, and be sure to follow the recommendations provided in this book. Development should only be undertaken by users who are familiar with the Solaris Security Toolkit software's design and implementation.



caution icon

Caution - Take extreme care when developing your own framework functions. Incorrect programming might compromise the Solaris Security Toolkit software's ability to properly implement or undo changes or to audit a system's configuration. Furthermore, changes made to the software could adversely impact the target platform on which the software is run.



CODE EXAMPLE 2-1 show how Solaris Security Toolkit functionality can be extended by customizing the standard framework. In this example, the mount_filesystems function is modified to enable the developer to mount additional file systems during a JumpStart installation. The mount_filesystems function is copied directly from the driver_private.funcs script into the user.run file. The modifications to it are in lines 8 and 9.


CODE EXAMPLE 2-1 Extending Functionality by Customizing the Framework
1   mount_filesystems()
2   {
3      if [ "${JASS_STANDALONE}" = "0" ]; then
4         mount_fs ${JASS_PACKAGE_MOUNT} ${JASS_ROOT_DIR} \
5            ${JASS_PACKAGE_DIR}
6         mount_fs ${JASS_PATCH_MOUNT} ${JASS_ROOT_DIR} \
7            ${JASS_PATCH_DIR}
8         mount_fs 192.168.0.1:/apps01/oracle \
9            ${JASS_ROOT_DIR}/tmp/apps-oracle
10     fi
11  }

For the sake of simplicity, the variable used to mount the new file system is not converted to Solaris Security Toolkit environment variables. To aid in portability and flexibility, abstract the actual values using environment variables. This approach allows changes to be made consistently, because the software is deployed into environments with different requirements, such as production, quality assurance, and development.



Note - You could implement the same functionality within a finish script that uses this mount point, so that the mounting, use, and unmounting of the file system is self-contained within the script. However, it might be more effective and efficient to mount the file system using mount_filesystems when a single file system is used by more than one script.





caution icon

Caution - A disadvantage to modifying mount_filesystemsis that when you install updates of the Solaris Security Toolkit software, you might need to modify the mount_filesystemsagain.




Using Common Log Functions

These functions control all logging and reporting functions and are located in the Drivers directory in a file called common_log.funcs. The logging and reporting functions are used in all of the Solaris Security Toolkit software's operational modes; therefore, they are considered common functions. Common functions such as logWarning and logError are in this file.

This section describes the following common log functions.

logBanner

This function displays banner messages. These messages typically precede driver, finish, or audit script run output. Banner messages also are used at the start and end of a run. They are displayed only if the logging verbosity is at least 3 (Full). For more information on verbosity levels, see Chapter 7.

Banner messages take one of two forms. If you pass an empty string to this function, then a single line separator is displayed. This line is often used to force a "break" in the displayed output. If you enter a single string value, then the output is displayed between a pair of single line separators. CODE EXAMPLE 2-2 shows a sample of a banner message.


CODE EXAMPLE 2-2 Sample Banner Message
================================================================
Solaris Security Toolkit Version: 4.2
Node name:                        imbulu
Zone name:                        global
Host ID:                          8085816e
Host address:                     192.168.0.1
MAC address:                      0:0:80:85:81:6e
OS version:                       5.10
Date:                             Fri Jul 1 22:27:15 EST 2005
================================================================

You can control the display of banner messages using the JASS_LOG_BANNER environment variable. For more information on this environment variable, see Chapter 7.

logDebug

This function displays debugging messages. Debugging messages have no type prefix, such as [FAIL] or [PASS]. Debugging messages are displayed only if the verbosity is at least 4 (Debug). The default is to not print debugging messages. For more information about verbosity levels, see Chapter 7.

Arguments: $1 - String to print

Returns: None

Example Usage:


logDebug "Print first message for debugging."

logError

This function displays error messages. Error messages are those that contain the string [ERR ].

Arguments: $1 - String to display as an error message

Returns: None

Example Usage:


logError "getScore: Score value is not defined."

Example Output:


[ERR ] getScore: Score value is not defined.

You can control the display of error messages using the JASS_LOG_ERROR environment variable. For more information on this environment variable, see Chapter 7.

logFailure

This function displays failure messages. Failure messages are those that contain the string [FAIL].

Arguments: $1 - String to display as an failure message

Returns: None

Example Usage:


logFailure "Package SUNWatfsr is installed."

Example Output:


[FAIL] Package SUNWatfsr is installed.

You can control the display of failure messages using the JASS_LOG_FAILURE environment variable. For more information on this environment variable, see Chapter 7.

logFileContentsExist and
logFileContentsNotExist

Use these functions to log messages associated with the results of file contents checks. These functions are used primarily by the check_fileContentsExist and check_fileContentsNotExist functions, although they can be used independently if necessary.

Arguments: $1 - File to test (string value)
$2 - Search pattern (string value)
$3 - Vulnerability value (non-negative integer)
$4 - Related information that you want displayed for users after a
PASS or FAIL message (optional)

Returns: Success or failure messages. You can control the display of these
messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS
environment variables. For more information on these environment
variables, see Chapter 7.

Example Usage:


logFileContentsExist /etc/default/inetinit "TCP_STRONG_ISS=2" 0

Example Output:


[PASS] File /etc/default/inetinit has content matching
TCP_STRONG_ISS=2.

logFileExists and
logFileNotExists

Use these functions to log messages associated with the results of file checks. These functions are primarily used with the check_fileExists and check_fileNotExists functions, although they can be used independently if necessary.

Arguments: $1 - File to test (string value)
$2 - Vulnerability value (non-negative integer). If this argument is
passed a null string value, then the function reports the result in
the form of a notice using the logNotice function. If the
argument is 0, it reports the result as a pass with the logSuccess
function
, otherwise as a failure with logFailure function.
$3 - Related information that you want displayed for users after a
PASS, FAIL, or NOTE message (optional).

Returns: Success or failure messages. You can control the display of these
messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS
environment variables. For more information on these environment
variables, see Chapter 7.

Example Usage:


logFileExists /etc/issue

Example Output:


[NOTE] File /etc/issue was found.

logFileGroupMatch and
logFileGroupNoMatch

Use these functions to log messages associated with the results of file group membership checks. These functions are used primarily by the check_fileGroupMatch and check_fileGroupNoMatch functions, although they can be used independently if necessary.

Arguments: $1 - File to test (string value)
$2 - Group to check
$3 - Vulnerability value (non-negative integer)
$4 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Returns: Success or failure messages. You can control the display of these
messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS
environment variables. For more information on these environment
variables, see Chapter 7.

Example Usage:


logFileGroupMatch /etc/motd sys 0

Example Output:


[PASS] File /etc/motd has group sys.

logFileModeMatch and
logFileModeNoMatch

Use these functions to log messages associated with the results of file permissions checks. These functions are used primarily by the check_fileModeMatch and check_fileModeNoMatch functions, although they can be used independently if necessary.

You can supply the following arguments to these functions:

Arguments: $1 - File to test (string value)
$2 - Permissions to check
$3 - Vulnerability value (non-negative integer)
$4 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Returns: Success or failure messages. You can control the display of these
messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS
environment variables. For more information on these environment
variables, see Chapter 7.

Example Usage:


logFileModeMatch /etc/motd 0644 0

Example Output:


[PASS] File /etc/motd has mode 0644.

logFileNotFound

This function is used by the software to display "file not found" messages. This function is used in the Solaris Security Toolkit code in both hardening and audit runs to provide a standard message when a designated file was not found on the system.

You can supply the following arguments to this function:

If this argument is passed a null string value, then this function reports the result in the form of a notice using the logNotice function. Otherwise, it reports the result as a failure using the logFailure function.

Example Usage:


logFileNotFound /etc/motd

Example Output:


[NOTE] File /etc/issue was not found.

You can control the display of notice and failure messages using the JASS_LOG_NOTICE and JASS_LOG_FAILURE environment variables, respectively. For more information on these environment variables, see Chapter 7.

logFileOwnerMatch and
logFileOwnerNoMatch

Use these functions to log the messages associated with the results of file ownership checks. These functions are used primarily by the check_fileOwnerMatch and check_fileOwnerNoMatch functions, although they can be used independently if necessary.

You can supply the following arguments to these functions:

Example Usage:


logFileOwnerMatch /etc/motd root 0

Example Output:


[PASS] File /etc/motd has owner root.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logFileTypeMatch and
logFileTypeNoMatch

Use these functions to log the messages associated with the results of file type checks. These functions are used primarily by the check_fileTypeMatch and check_fileTypeNoMatch functions, although they can be used independently if necessary.

You can supply the following arguments to these functions:

TABLE 2-1 lists the file types detected by the software:


TABLE 2-1 File Types Detected by Using the check_fileTypeMatch Function

File Type

Description

b

Block special file

c

Character special file

d

Directory

D

Door

f

Regular file

l

Symbolic link

p

Named pipe (fifo)

s

Socket


Example Usage:


logFileTypeMatch /etc/motd f 0

Example Output:


[PASS] File /etc/motd is a regular file.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logFinding

This function displays audit finding messages. This function accepts a single string argument to be displayed as a message. The input for this function is processed by the printPrettyPath function prior to display. In addition, if the verbosity level is 2 (Brief) or higher, then optional tags are prepended to the message. The following are the optional tags that you can prepend using this function:



Note - If the finding occurs outside of an audit script, such as within the flow of the driver.run script, then the name of the driver is used.



You can use all three output tags collectively or independently. The order of the position in the resulting output line is as you listed them in the input line. For more information on this function and verbosity levels, see Chapter 7.

Example Usage:


logFinding "/etc/motd"

Example Output:


test-script /etc/motd

logFormattedMessage

Use this function to generate formatted audit script headers that display information such as the script name, purpose, and rationale for the check. This function accepts a single string value and formats the message that is passed to the function.

These messages are reformatted as follows:

Formatted messages are displayed only when the verbosity level is at least 3 (Full). For more information on this function and verbosity levels, see Chapter 7.

Example Usage:


logFormattedMessage "Check system controller secure shell configuration."

Example Output:


# Check system controller secure shell configuration.

logInvalidDisableMode

Use this function to display an error message when the JASS_DISABLE_MODE environment variable is set to an invalid value. This utility function reports on the state of the JASS_DISABLE_MODE environment variable. For more information on this environment variable, see Chapter 7.

This function takes no arguments and generates the following output:


[ERR ] The JASS_DISABLE_MODE parameter has an invalid value: [...]
[ERR ] value must either be "script" or "conf".

logInvalidOSRevision

Use this function when either the check_os_revision or check_os_min_revision functions fail their checks. This utility function reports when a function is being called on a version of the Solaris OS for which it does not apply. For example, use this function when there is an attempt to use a Solaris 10 OS script with the Solaris 8 OS.

Example Usage:


logInvalidOSRevision "5.10"

Example Output:


[NOTE] This script is only applicable for Solaris version 5.10.

To specify multiple versions, enter a hyphen (-) between versions, for example, "5.8-5.9."

This function displays notice messages. You can control the display of messages using the JASS_LOG_NOTICE environment variable.



Note - Do not use the JASS_LOG_NOTICE environment variable on systems running the Solaris 10 OS.



For more information on this environment variable, see Chapter 7.

logMessage

Use this function to display any message that you want to display to users. Use this function for messages that do not have any tags associated with them. This function is similar to the logFormattedMessage function, but displays an unformatted message. This function accepts a single string value that is displayed as is, with no modification.

Unformatted messages are only displayed if the verbosity level is at least 3 (Full). For more information on this function and verbosity levels, see Chapter 7.

Example Usage:


logMessage "Verify system controller static ARP configuration."

Example Output:


Verify system controller static ARP configuration.

logNotGlobalZone

This function logs a message using logNotice that a script will not be run, because it must run in the global zone. In other words, the script cannot run in non-global zones.

Argument: None

Return: None

Example Usage:


logNotGlobalZone

logNotice

Use this function to display notice messages. This function accepts a single string value that is displayed as a notice message. Notice messages are those that contain the string [NOTE].

Example Usage:


logNotice "Service ${svc} does not exist in ${INETD}."

Example Output:


[NOTE] Service telnet does not exist in /etc/inetd.conf.

You can control the display of notice messages using the JASS_LOG_NOTICE environment variable. For more information on this environment variable, see Chapter 7.

logPackageExists and
logPackageNotExists

Use these functions to log the messages associated with the results of checks that determine if software packages are installed. These functions are used primarily by the check_packageExists and check_packageNotExists functions, although they can be used independently if necessary.

You can supply the following arguments to these functions:

Example Usage:


logPackageExists SUNWcsr 0

Example Output:


[PASS] Package SUNWcsr is installed.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logPatchExists and
logPatchNotExists

Use these functions to log the messages associated with the results of checks that determine if software patches are installed. These functions are used primarily by the check_patchExists and check_patchNotExists functions, although they can be used independently if necessary.

You can supply the following arguments to these functions:

Example Usage:


logPatchExists 123456-01 0

Example Output:


[PASS] Patch ID 123456-01 or higher is installed.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logProcessArgsMatch and
logProcessArgsNoMatch

Use these functions to log the messages associated with the results of checks for runtime process arguments. These functions are used primarily by the check_processArgsMatch and check_processArgsNoMatch functions, although they can be used independently if necessary.

You can supply the following arguments to these functions:

Example Usage:


logProcessArgsMatch inetd "-t" 0

Example Output:


[PASS] Process inetd found with argument -t.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logProcessExists and
logProcessNotExists

Use these functions to log the messages associated with the results of checks for processes. These functions are used primarily by the check_processExists and check_processNotExists functions, although they can be used independently if necessary.

Arguments: $1 - Process name (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logProcessExists nfsd 0

Example Output:


[PASS] Process nfsd was found.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logProcessNotFound

Use this function to log a FAIL message for any process that is not found. This function displays a standard "process not found" message when a designated process cannot be found on a system.

Arguments: $1 - Process name (string)
$2 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logProcessNotFound inetd

Example Output:


[FAIL] Process inetd was not found.

You can control the display of these messages using the JASS_LOG_FAILURE environment variable. For more information on this environment variable, see Chapter 7.

logScore

Use this function to report the number of errors found during an audit run.

Argument: $1 - String to associate with the report
$2 - Number of errors (string)

Returns: Number of errors found during an audit run.

Example Usage:


logScore "Script Total:" "0"

Example Output:


[PASS] Script Total: 0 Errors

logScriptFailure

Use this function to record a script failure to the corresponding script failure log.

Arguments: $1 - Type of failure:
"error"
"warning"
"note"
"failure"

$2 - Count of the type of failure recorded (string).

Example Usage:


logScriptFailure "failure" 1

This example would record one failure to the ${JASS_REPOSITORY}/${JASS_TIMESTAMP}/jass-script-failures.txt file.

logServiceConfigExists and
logServiceConfigNotExists

Use these functions to log the messages associated with the results of checks that determine if configuration files exist. These functions are used primarily by the check_serviceConfigExists and check_serviceConfigNotExists functions, although they can be used independently if necessary.

Arguments: $1 - Service name (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logServiceConfigExists /etc/apache/httpd.conf 0

Example Output:


[PASS] Service Config File /etc/apache/httpd.conf was found.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logServiceDisabled and logServiceEnabled

Use these functions to log that the specified service was enabled or disabled in a uniform manner.

Arguments: $1 - Service name (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logServiceDisabled "svc:/network/telnet:default" 0 ""

Example Output:


[PASS] Service svc:/network/telnet:default was not enabled.

logServiceInstalled and logServiceNotInstalled

Use these functions to log that the specified service was installed or not installed in a uniform manner. These functions are primarily used with the check_serviceEnabled and check_serviceDisabled functions, although they can be used independently if necessary.

Arguments: $1 - Service name (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logServiceInstalled "svc:/network/telnet:default" 1 ""

Example Output:


[FAIL] Service svc:/network/telnet:default was installed.

logServiceOptionDisabled and logServiceOptionEnabled

Use this function to log whether a service had a specified option set to a particular value. This function is used with the check_serviceOptionDisabled and check_serviceOption Enabled functions.

Arguments: $1 - Process name (string)
$2 - Service property name (string)
$3 - Service name (string)
$4 - Service property value (string)
$5 - Vulnerability value (numeric)
$6 - Related information that you want displayed for users after a
PASS or FAIL message (optional)

Example Usage:


logServiceOptionEnabled "in.ftpd" "inetd_start/exec" "svc:/network/ftp" "-1" 0 ""

Example Output:


[PASS] Service in.ftpd of svc:/network/ftp property inetd_start/exec has option -1.

logServiceProcessList

Use this function to print a list of processes associated with an SMF service. For each process, three items are printed: the process ID, process user ID, and process command.

Arguments: $1 - SMF service
$2 - PASS or FAIL
$3 - List of associated processes with process ID (pid), process user ID
(user), and process command (command).

Example Usage:


logServiceProcessList svc:/network/telnet 0 "245 root in.telnetd"

Example Output:


[PASS] Service svc:/network/telnet was found running (pid 245, user root, command in.telnetd).

logServicePropDisabled and logServicePropEnabled

Use this function to log whether a service had a specified option set to enabled or disabled. These functions are primarily used with the check_serviceOptionEnabled and check_serviceOptionDisabled functions, although they can be used independently if necessary.

Arguments: $1 - Service name (string)
$2 - Property name (string)
$3 - Property value (string)
$4 - Vulnerability value (numeric)
$5 - Related information that you want displayed for users after a
PASS or FAIL message (optional)

Example Usage:


logServicePropDisabled svc:/network/ftp enable_tcpwrappers enabled 1 ""

Example Output:


[FAIL] Service svc:/network/ftp property enable_tcpwrappers was enabled.

logServiceRunning and logServiceNotRunning

Use this function to log whether a specific service is running. These functions are primarily used with the check_serviceRunning and check_serviceNotRunning functions, although they can be used independently if necessary

Arguments: $1 - Service name (string)
$2 - Vulnerability value (numeric)
$3 - Process list (optional)
$4 - Related information that you want displayed for users after a
PASS or FAIL message (optional)

Example Usage:


logServiceRunning svc:/network/ftp 1

Example Output:


[FAIL] Service svc:/network/ftp was not running.

logStartScriptExists and
logStartScriptNotExists

Use these functions to log the messages associated with the results of checks that determine if run-control start scripts exist. These functions are used primarily by the check_startScriptExists and check_startScriptNotExists functions, although they can be used independently if necessary.

Arguments: $1 - Start script to test (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logStartScriptExists /etc/rc3.d/S89sshd 0

Example Output:


[PASS] Start Script /etc/rc3.d/S89sshd was found.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logStopScriptExists and
logStopScriptNotExists

Use these functions to log the messages associated with the results of checks that determine if run-control stop scripts exist. These functions are used primarily by the check_stopScriptExists and check_stopScriptNotExists functions, although they can be used independently if necessary.

Arguments: $1 - Stop script to test (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional).

Example Usage:


logStopScriptExists /etc/rc2.d/K03sshd 0

Example Output:


[PASS] Stop Script /etc/rc2.d/K03sshd was found.

These functions display either success or failure messages. You can control the display of these messages using the JASS_LOG_FAILURE and JASS_LOG_SUCCESS environment variables. For more information on these environment variables, see Chapter 7.

logSuccess

Use this function to display success messages. This function accepts a single string value that is displayed as an audit success message. Success messages are those that contain the string [PASS].

Example Usage:


logSuccess "Package SUNWsshdr is installed."

Example Output:


[PASS] Package SUNWsshdr is installed.

You can control the display of success messages using the JASS_LOG_SUCCESS environment variable. For more information on this environment variable, see Chapter 7.

logSummary

Use this function to display summary information from a Solaris Security Toolkit run. The function takes arguments of the driver to compare the run against, and the number of scripts run.

Example Usage:


logSummary undo.driver 61

Example Output:


==============================================================================
[SUMMARY] Results Summary for UNDO run of jass-execute
[SUMMARY] The run completed with a total of 91 scripts run.
[SUMMARY] There were  Failures in   0 Scripts
[SUMMARY] There were  Errors   in   0 Scripts
[SUMMARY] There was a Warning  in   1 Script
[SUMMARY] There were  Notes    in  61 Scripts
 
[SUMMARY] Warning Scripts listed in:
         /var/opt/SUNWjass/run/20050616052247/jass-undo-script-warnings.txt
[SUMMARY] Notes Scripts listed in:
         /var/opt/SUNWjass/run/20050616052247/jass-undo-script-notes.txt
==============================================================================

logUserLocked and logUserNotLocked

Use this function to log whether the specific user account was locked. These functions are used primarily by the check_userLocked and check_userNotLocked functions, although they can be used independently if necessary.

Arguments: $1 - User name (string)
$2 - Vulnerability value (numeric)
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional)

Example Usage:


logUserLocked "uucp" 1

Example Output:


[FAIL] User uucp was not locked.

logUndoBackupWarning

Use this function to log a general warning about the consequences of an undo run.

Example Usage:


logUndoBackupWarning

Example Output:


[WARN] Creating backup copies of some files may cause unintended effects.
[WARN] This is particularly true of /etc/hostname.[interface] files as well as crontab files in /var/spool/cron/crontabs.

logWarning

Use this function to display warning messages. This function accepts a single sting value that is displayed as a warning message. Warning messages are those that contain the string [WARN].

Example Usage:


logWarning "User ${acct} is not listed in ${JASS_PASSWD}."

Example Output:


[WARN] User abc is not listed in /etc/passwd.

You can control the display of warning messages using the JASS_LOG_WARNING environment variable. For more information on this environment variable, see Chapter 7.


Using Common Miscellaneous Functions

These functions are for common miscellaneous functions that are used within several areas of the Solaris Security Toolkit software and are not specific to functionality provided by other framework functions (files ending with the .funcs suffix). These functions are in the Drivers directory in a file called common_misc.funcs. Common utility functions, such as isNumeric and printPretty, are included in this file.

This section describes the common miscellaneous functions.

adjustScore



Note - This function applies only to audit runs.



Use this function to increase the score outside of the methods provided by the functions defined in the audit_public.funcs file. For example, there might be times when only the audit script can determine a failure. In those cases, use this function to adjust the score, accounting for the failure. If you do not supply a value, the function logs an error message and does not adjust the score.

Argument: $1 - Value to add to current score for an audit script (positive integer)

Return: None

Example Usage:


adjustScore 1

checkLogStatus



Note - This function applies only to audit operations.



Use this function to determine whether the calling function is requesting to log its results.

Argument: $1 - Value of the logging parameter

Return: 0 - No output is requested to be logged by the calling function
1 - Value is LOG, indicating calling function requests to log its results

Example Usage:


checkLogStatus "${_logParameter}"

clean_path

Use this function to remove redundant forward slash characters (/) from a file name. This function is used to clean up path names before they are displayed to the user or before they are placed in logs.

Argument: $1 - Path to be cleaned

Return: Returns value in $1 after any duplicate forward slash characters (/)
have been removed.

Example Usage:


newPath=`clean_path "${oldPath}"`

extractComments

Use this function to remove comments from a file or script. This function defines a comment as any substring of text that begins with a number symbol (#) and continues to the end of the line.

Arguments: $1 - List of tokens, such as script names or file names

Return: Removes any text that is commented out.

Example Usage:


FinishScripts=`extractComments "${JASS_FILES}"`

get_driver_report

Use this function to read a log file and return the number of scripts that reported an error or warning.

Argument: $1 - Log file to check

Returns: 255 - Unspecified failure
0 - Success
1 - Log file was not readable

Example Usage:


failures=`get_driver_report "{JASS_SCRIPT_FAIL_LOG}"`

get_lists_conjunction

Use this function to take lists A and B, and return list C consisting of elements in both A and B.

Arguments: $1 - listA, consisting of white-space-separated tokens
$2 - listB, consisting of white-space-separated tokens

Returns: List C containing all elements in both List A and List B.

Example Usage:


SvcsToLog=`get_lists_conjunction "${JASS_SVCS_DISABLE}" "${JASS_SVCS_ENABLE}"`

get_lists_disjunction

Use this function to take lists A and B, and return list C consisting of those elements in list A that are not present in list B.

Arguments: $1 - listA, consisting of white-space-separated tokens
$2 - listB, consisting of white-space-separated tokens

Returns: List C containing those elements in list A that are not present in list B.

Example Usage:


SvcsToDisable=`get_lists_disjunction "${JASS_SVCS_DISABLE}" "${JASS_SVCS_ENABLE}"`

invalidVulnVal



Note - This function applies only to audit operations.



Use this function to determine if vulnerability value arguments are positive integers. This function logs an error message for each failure. This function is necessary to determine where there might be an invalid argument supplied to a function as a vulnerability value. In all other aspects, this function behaves like its isNumeric counterpart.

Argument: $1 - Vulnerability to be checked

Returns: 0 - Vulnerability is positive integer
1 - Vulnerability is not positive integer

Example Usage:


invalidVulnVal "${testVulnerability}"

isNumeric

Use this function to determine if string arguments are positive integers. It is used throughout the software by helper functions whenever input must be validated to ensure that it consists of a single positive integer. If the value is a positive integer, this function displays 0, otherwise it displays 1.

Argument: $1 - String to be checked

Returns: 0 - String is positive integer
1 - String is not positive integer

Example Usage:


isNumeric "${testString}"

printPretty

Use this function to format printed output so that it is easier to read. This function accepts an unformatted input string and processes it. The resulting string is wrapped at 72 characters, with each line of output indented by three characters.

Argument: $1 - String to be printed

Returns: None

Example Usage:


printPretty "${CommentHeader}"

printPrettyPath

Use this function to format path names. This function accepts as input an unformatted path name. This function strips any redundant forward slashes from the input string, then displays the result. If the string is empty, then the keyword <No Value> is displayed in its place.

Argument: $1 - String to be printed

Returns: None

Example Usage:


printPrettyPath "${PathToLogFile}"

strip_path

Use this function to remove the JASS_ROOT_DIR prefix from the file name. This function accepts as input a single string argument and returns the same value after removing the JASS_ROOT_DIR prefix and replacing it with a single forward slash character (/). This function is used with the add_to_manifest function when storing path names in the JASS manifest file.

Argument: $1 - File path to be cleaned

Returns: None

Example Usage:


StrippedString=`strip_path "${JASS_ROOT_DIR}/etc/motd"`


Using Driver Functions

These functions are for driver functionality. These functions are in the driver_public.funcs file, located in the Drivers directory. Functions such as add_pkg and copy_a_file are in this file.

When customizing or creating scripts, use the following functions to perform standard operations.

add_crontab_entry_if_missing



Note - This function is used only for SMF in the Solaris 10 OS.



Use this function to add crontab line $3 to the crontab if program $2 is not in user's $1 crontab. If $4 is zero, backs up the crontab file before modifying (see Example Usage). The function ignores crontab comment lines.

Arguments: $1 - User ID of crontab to be modified
$2 - Program to add to crontab (full path name)
$3 - crontab line to add if $2 is not present in the crontab file
$4 - If zero, call backup_file before modifying (else the file was
created or already backed up.)

Returns: 1 - If the crontab file was backed up; otherwise, passes back the
argument $4 unmodified.)

Example Usage:


add_crontab_entry_if_missing 'root' '/usr/lib/acct/dodisk' '0 2 * * 4 
/usr/lib/acct/dodisk' 0

add_option_to_ftpd_property



Note - This function is used only for SMF in Solaris 10 and applies to the ftp daemon only (options -1 or -a).





caution icon

Caution - If you find the function add_option_to_gl_propertyor add_option_to_smf_property, rename the function to add_option_to_ftpd_property.



Use this function to add an option to the SMF-enabled in.ftpd service property value in Solaris 10 OS. Only call this function for a hardening operation. This function writes to the Solaris Security Toolkit manifest file for an undo operation.

Argument: $1 - Option to add to the start command: a or 1 (for use with
ftpaccess(4) and log ftp session, respectively)

Returns: None

Example Usage:


add_option_to_ftpd_property "a"

add_patch

Use this function to add Solaris OS patches to the system. By default, this function expects that the patches installed are located in the JASS_PATCH_DIR directory. TABLE 2-2 lists the options for this function.


TABLE 2-2 Options for add_patch Finish Script Function

Option

Description

-o options

Options to be passed on

-M patchdir

Fully qualified path to the source directory

patchlist

List of patches or name of file containing a list of patches to apply


Example Usage:


add_patch 123456-01
add_patch -M ${JASS_PATCH_DIR}/OtherPatches patch_list.txt

add_pkg

Use this function to add Solaris OS packages to the system. By default, this function expects that the packages are located in the JASS_PACKAGE_DIR directory and that these packages are in one of the standard Sun formats, spooled directories, or package stream files. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run. During an undo run, packages added using this function are removed from the system. TABLE 2-3 lists the options for this function.


TABLE 2-3 Options for add_pkg Function

Option

Description

-a ask_file

pkgadd ask file name. By default, the pkgadd ask file, noask_pkgadd, is used if no other file is specified.

-d src_loc

Fully qualified path to the source package (streams or directory) to be installed

-o options

pkgadd command options

package

Package to be installed


Example Usage:


add_pkg ABCtest
add_pkg -d ${JASS_ROOT_DIR}/${JASS_PACKAGE_DIR}/SUNWjass.pkg SUNWjass

add_to_manifest

Use this function to manually insert entries into a manifest file during hardening runs without calling one of the helper functions. This approach is most often used when a command must be executed for the undo operation to complete. Use this option with care to protect the integrity of the system and the Solaris Security Toolkit repository.

The add_to_manifest command uses the following syntax:


add_to_manifest operation src dst args

This command puts an entry in the JASS_RUN_MANIFEST file in JASS_REPOSITORY/jass-manifest.txt, which is critical to the ability to undo the changes made by a finish script.



Note - Not all of the operations used by the Solaris Security Toolkit support each of these arguments. The meaning of the options for src, dst, and args can differ based on the operation selected, as discussed in TABLE 2-4.



The operations supported by the add_to_manifest function are listed in TABLE 2-4. This table includes a sample resulting manifest entry after each option.



Caution - Exercise extreme caution when using the Xmanifest option. The commands specified by this operation are executed during an undo run of the Solaris Security Toolkit as the rootuser. If you are notcareful, you could cause data loss or render a target system unstable. For example, an Xmanifest entry of rm-rf/would delete the system's root partition during an undo run.




Table identifying the file operations that can be performed by the add_to_manifest function.


Table identifying the file operations that can be performed by the add_to_manifest function.


TABLE 2-4 add_to_manifest Options and Sample Manifest Entries

Option

Description

C

Indicates a file was copied. In this case, the srcand dstparameters represent the original and copied file names, respectively. No other arguments are used.

install-templates.fin /etc/syslog.conf /etc/ \
syslog.conf.JASS.20020823230626

D

Indicates a directory was created. In this case, the src parameter represents the name of the newly created directory. No other arguments are used.

disable-lp.fin /var/spool/cron/crontabs.JASS

J

Indicates a new file was created on the system. This operation is used onlywhen the file specified by the srcparameter does notexist on the system. During an undo run, files tagged with this operation code are removed. This operation uses both the srcand dstparameters to represent the original name of the file and its saved file name (which must include the JASS_SUFFIX).

disable-power-mgmt.fin /noautoshutdown \
/noautoshutdown.JASS.20020823230629

M

Indicates a file was moved. In this case, the srcand dstparameters represent the original and moved file names, respectively. No other arguments are used.

disable-ldap-client.fin /etc/rcS.d/K41ldap.client \
/etc/rcS.d/_K41ldap.client.JASS.20020823230628

R

Indicates a file was removed from the system. In this case, the srcparameter represents the name of the file that was removed. Files marked with this operation code cannotbe restored using the Solaris Security Toolkit undo command.

S

Indicates a symbolic link was created. In this case, the srcand dstparameters represent the source and target file names, respectively. During an undo run, the symbolic links for files tagged with this operation are removed from the system.

install-templates.fin ../init.d/nddconfig /etc/rc2.d/ \
S70nddconfig

X

Indicates a command was defined that should be run when the Solaris Security Toolkit processes a manifest entry that has this operation code. A special operation, this one is most often used to execute complex commands that go beyond the standard operations. For example, in the install-fix-modes.finfinish script, the following manifest entry is added to instruct the software to undo changes made by the Fix Modes program:

/opt/FixModes/fix-modes-u

This command instructs the software to run the fix-modesprogram with the -uoption. Note that all commands processed by this operation code should be specified using an absolute path to the program.


backup_file

Use this function to back up an existing file system object. This function backs up the original file using a standard naming convention. The convention appends JASS_SUFFIX to the original file name. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

The JASS_SAVE_BACKUP variable specifies if the Solaris Security Toolkit software saves or does not save backup copies of files modified during a run. If this environment variable is set to 0, then this function does not save backup files on the system. If files are not saved, then the run cannot be reversed by using the undo command.

Example Usage:


backup_file /etc/motd

backup_file_in_safe_directory

Use this function to disable files that cannot be stored in their original directory (see disable_file for more information) and to leave a copy of the files in place for further editing, as well as moving the originals. This includes all files in directories /etc/skel/, /var/spool/cron/crontabs/, /etc/init.d/, and /etc/rcx.d/.

Arguments: $1 - Fully qualified path to source file
$2 - If set to "-u" for an undo file, the prior timestamp is
stripped from the file name.

Returns: None

Example Usage:


backup_file_in_safe_directory ${JASS_ROOT_DIR}etc/rcS.d/S42coreadm

change_group

Use this function to change the file group ownership. This function automatically adds the necessary manifest entries to be reversed during an undo run.

Arguments: $1 - Group ID of file owner
$2 - One or more files for which to change group ownership (must be
a regular or special file or directory, not a soft link.

Returns: 0 - If the file now has the correct group ownership
non-zero - If no file or file permission was specified, or chown failed

Example Usage:


change_group root ${JASS_ROOT_DIR}var/core

change_mode

Use this function to change the permissions mode of a file. This function automatically adds the necessary manifest entries to be reversed during an undo run.

Arguments: $1 - File permissions in octal chmod(1) format (for example, 0700)
$2 - One or more files for which to chmod (must be a regular or special
file or directory, not a soft link.

Returns: 0 - If the file now has the correct ownership
non-zero - If no file or file permission was specified, or chown failed

Example Usage:


change_mode 0700 ${JASS_ROOT_DIR}var/core

change_owner

Use this function to change the file ownership and, optionally, the group. This function automatically adds the necessary manifest entries to be reversed during an undo run.

Arguments: $1 - User ID of file owner
$2 - One or more files for which to change ownership (must be a
regular or special file or directory, not a soft link.

Returns: 0 - If the file now has the correct ownership
non-zero - If no file or file permission was specified, or chown failed

Example Usage:


change_owner root:root ${JASS_ROOT_DIR}var/core
change_owner root ${JASS_ROOT_DIR}var/core

check_and_log_change_needed

Use this function to keep your finish scripts clean by moving a common operation, checking and storing the current value in a file, into a framework function. This function is most useful to you if you are a finish script writer and will be repeatedly checking variables in a single file.

This function checks and logs a parameter separated by an equal sign (=) in a file. If the new value is set, the global variable new_var is set to the new value. Otherwise, new_var is set to the value currently existing in the file. If the most recent value is different from the previous value, a log message is printed, and the global variable change_needed is incremented.

Use this function with the write_val_to_file function (see write_val_to_file).

Arguments: $1 - File name
$2 - Keyword in the file
$3 - New value

Returns: Sets the global environment variable new_var to the new value,
unless it is empty, in which case it is set to the value in the file, or ""
if it is not set.

Example Usage:


change_needed="0"
check_and_log_change_needed "/etc/default/passwd" "MINALPHA" "${JASS_PASS_MINALPHA}"
minalpha="${new_var}"
check_and_log_change_needed "/etc/default/passwd" "MINLOWER" "${JASS_PASS_MINLOWER}"
minlower="${new_var}"
 
if [ "${change_needed}" != "0" ]; then
   ...

check_os_min_version

Use this function to detect functionality that exists in multiple releases of the Solaris OS. This function takes only one argument, indicating the minimal OS release version. If the actual release of the OS on the target platform is greater than or equal to the argument, then the function returns 0, otherwise this function returns 1. If an error is encountered, then this function returns 255.

For example, this function can be used as shown in CODE EXAMPLE 2-3.


CODE EXAMPLE 2-3 Detecting Functionality That Exists in Multiple OS Releases
if check_os_min_revision 5.10 ; then
    disable_service svc:/network/dns/server:default
elif check_os_min_revision 5.7 ; then
    disable_conf_file ${JASS_ROOT_DIR}etc named.conf
else
    disable_conf_file ${JASS_ROOT_DIR}etc named.boot
fi

In this example, Domain Name System (DNS) service is disabled with an SMF FMRI, which was first available in the Solaris 10 OS. Otherwise, DNS is disabled by renaming /etc/named.conf for the Solaris 7 OS and /etc/named.boot for the Solaris 2.6 OS or earlier.

check_os_revision

Use this function to check for a specific OS revision or range of values. This function can take either one or two arguments. If one argument is supplied, then the script returns 0 only if the target operating system revision is the same as the argument, otherwise it returns 1.

Similarly, if two arguments are provided, the target operating system revision must be between the two values inclusively for the result to be 0. In either case, if an error is encountered, this function returns a value of 255.

For example, this function can be used as shown in CODE EXAMPLE 2-4.


CODE EXAMPLE 2-4 Checking for a Specific OS Revision or Range
if check_os_revision 5.5.1 5.8; then
   if [ "${JASS_DISABLE_MODE}" = "conf" ]; then
      disable_conf_file ${JASS_ROOT_DIR}/etc asppp.cf
   elif [ "${JASS_DISABLE_MODE}" = "script" ]; then
      if [ "${JASS_KILL_SCRIPT_DISABLE}" = "1" ]; then
         disable_rc_file ${JASS_ROOT_DIR}/etc/rcS.d K50asppp
         disable_rc_file ${JASS_ROOT_DIR}/etc/rc0.d K47asppp
         disable_rc_file ${JASS_ROOT_DIR}/etc/rc0.d K50asppp
         disable_rc_file ${JASS_ROOT_DIR}/etc/rc1.d K47asppp
         disable_rc_file ${JASS_ROOT_DIR}/etc/rc1.d K50asppp
      fi
      disable_rc_file ${JASS_ROOT_DIR}/etc/rc2.d S47asppp
   fi
else
   logInvalidOSRevision "5.5.1-5.8"
fi

In this example, the script disables only its scripts or configuration files, based on the value of JASS_DISABLE_MODE, when the target OS revision is or falls between Solaris OS versions 2.5.1 (SunOS 5.1) and 8 (SunOS 5.8) inclusively.

check_readOnlyMounted

Use this function to determine whether the file specified is mounted on a read-only file system.

Argument: $1 - File to check

Returns: 255 - Error occurred
0 - File system that file $1 is in is mounted as read only.
1 - File system that file $1 is in is not mounted as read only

Example Usage:


check_readOnlyMounted /usr/bin/ls

checksum

Use this function to calculate the checksum for a file. This function takes a single string value that represents the file for which the checksum is being calculated.

convert_inetd_service_to_frmi

Use this function to convert an inetd service name in the /etc/inet/inetd.conf file to an SMF FMRI for use by the inetconv(1M) command. This function only uses legacy inetd service names in /etc/inet/inetd.conf, not on SMF FMRIs. The converted FMRI prints to standard output.

Argument: $1 - inetd service name to be converted.

Returns: 0 - Success
1 - Failure

Example Usage:


tooltalk_fmri=`convert_inetd_service_to_fmri 100083`

copy_a_dir

Use this function to recursively copy the contents of a directory. This function takes two arguments, a source directory name and a destination directory name. This function copies the contents of the source directory to the directory specified by the destination parameter. This function creates the new directory if it does not already exist. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Example Usage:


copy_a_dir /tmp/test1 /tmp/test2

copy_a_file

Use this function to copy exactly one regular file. This function takes two arguments: a source file name and a destination file name. This function copies the contents of the source file to the file name specified by the destination parameter. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Example Usage:


copy_a_file /tmp/test-file-a /tmp/test-file-b

copy_a_symlink

Use this function to copy a symbolic link to the target platform. This function takes two arguments: a source link name and a destination file name. This function creates a new symbolic link based on the source link specified using the new file name passed as the destination parameter. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Example Usage:


copy_a_symlink /tmp/test-link-a /tmp/test-link-b

copy_files

Use this function to copy a set of file system objects from the JASS_HOME_DIR/Files directory tree to a target system. This function uses the following copy functions to ensure that the changes made can be reversed during an undo run:

This function is capable of copying regular files, directories, and symbolic links.

Example Usages:


copy_files /etc/init.d/nddconfig

copy_files "/etc/init.d/nddconfig /etc/motd /etc/issue"

 

This function extends capability by permitting the selective copy of files based on tags appended to their file names that contain the values specified by environment variables. (See Chapter 7 for detailed information about all of the environment variables.)

The files that are copied by this function are selected by the following criteria, which are listed in the order of precedence used to match. For example, if a host-specific and generic file both exist, the host-specific file is used if the name of a target system matches the host name defined by the host-specific file. The following examples use /opt/SUNWjass as the home directory specified in the JASS_HOME_DIR environment variable, but you might have specified a different home directory. In our examples, the directory tree being searched is /opt/SUNWjass/Files/.



Note - The copy_files function ignores any objects listed that are not found in the JASS_HOME_DIR/Files directory tree.



1. Host-specific version - /opt/SUNWjass/Files/file.JASS_HOSTNAME

In this option, the software copies the file only if the name of the host target platform matches the value specified by the JASS_HOSTNAME environment variable. For example, if the file name is etc/issue and the JASS_HOSTNAME is eng1, a file copied under this criteria would be:

/opt/SUNWjass/Files/etc/issue.eng1

2. Keyword + OS-specific version - /opt/SUNWjass/Files/file-JASS_FILE_COPY_KEYWORD+JASS_OS_VERSION

In this option, the software copies the file only if the name of the keyword and OS version match the values specified by the JASS_FILE_COPY_KEYWORD and the JASS_OS_VERSION environment variables.

For example, if the file being searched for is /etc/hosts.allow, JASS_FILE_COPY_KEYWORD is "secure" (for secure.driver), and the JASS_OS_VERSION is 5.10, a file copied under this criteria could be:

/opt/SUNWjass/Files/etc/hosts.allow-secure+5.10

3. Keyword-specific version - /opt/SUNWjass/Files/file-JASS_FILE_COPY_KEYWORD

In this option, the software copies the file only if the keyword matches the value specified by the JASS_FILE_COPY_KEYWORD environment variable. For example, if the JASS_FILE_COPY_KEYWORD is "server", a file copied under this criteria could be:

/opt/SUNWjass/Files/etc/hosts.allow-server

4. OS-specific version - /opt/SUNWjass/Files/file+JASS_OS_REVISION

In this option, the software copies the file only if the OS revision of the target platform matches the value specified by the JASS_OS_REVISION environment variable. For example, if the file being searched for is /etc/hosts.allow and JASS_OS_REVISION is "5.10", a file copied under this criteria could be:

/opt/SUNWjass/Files/etc/hosts.allow+5.10

5. Generic version - /opt/SUNWjass/Files/file

In this option, the software copies the file to a target system.

For example, if the file name is etc/hosts.allow, a file copied under this criteria would be:

/opt/SUNWjass/Files/etc/hosts.allow

6. Source file is of size 0 - When the file length/size is zero, the file is not copied to the system.

create_a_file

Use this function to create an empty file on a target system. This function uses a combination of the touch, chown, and chmod commands to create an empty file with a specific owner, group, and set of permissions.



Note - This function does not adjust permissions or ownerships on a file that exists.



This function creates a file with specific permissions.

Example Usage:


create_a_file -o guppy:staff -m 750 /usr/local/testing

In this example, a file called testing is created in the /usr/local directory, owned by guppy and group of staff, with permissions 750. This function accepts the options listed in TABLE 2-5.


TABLE 2-5 create_a_file Command Options

Option

Valid Input

[-o user[:group]]

Follows syntax of chown(1) and accepts user and user:group

[-m perms]

Follows syntax of chmod(1) and accepts perms

/some/fully/qualified/path/file

The fully qualified path to the file


Example Usages:


create_a_file /usr/local/testing
create_a_file -o root /usr/local/testing
create_a_file -o root:sys /usr/local/testing
create_a_file -o root -m 0750 /usr/local/testing

create_file_timestamp

Use this function to create a unique timestamp value for a given file and for all file backup operations. This function is useful for creating a backup of a file that has already been backed up when a unique suffix value is needed. The timestamp value created is in the same format as JASS_TIMESTAMP. The resulting timestamp value created by this function is stored in the JASS_SUFFIX environment variable. For more information, see Chapter 7, JASS_TIMESTAMP.

Example Usage:


create_file_timestamp /usr/local/testing

disable_conf_file

Use this function to disable service configuration files. This function accepts two string values representing the directory name in which the file is located and the service configuration file name. This function disables the service configuration file by prepending a prefix of underscore (_) to the file name, thereby preventing its execution.

Example Usage:


disable_conf_file /etc/dfs dfstab

This example renames a file from /etc/dfs/dfstab to /etc/dfs/_dfstab.JASS.timestamp. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

disable_file

Use this function to disable files that cannot be stored in their original directory. For example, the /var/spool/cron/crontabs directory contains individual user crontab files. If a disabled or backed-up copy of a crontab file were stored in the crontabs directory, then the cron service would indicate an error, because there would be no user name that matched the names of the disabled or backed-up files.

To address this issue, this function creates a mirror directory with a .JASS suffix within which to store any of the disabled files. For example, if the file to be disabled is located in the /var/spool/cron/crontabs directory, this function creates a /var/spool/cron/crontabs.JASS directory into which the disabled file is moved.

The file to be disabled, as with the other disable functions, has a suffix of .JASS.timestamp. However, using this function, the disabled file is not stored in the same directory as the original file.

Example Usage:


disable_file /var/spool/cron/crontabs/uucp

In this example, the file /var/spool/cron/crontabs/uucp is moved to the
/var/spool/cron/crontabs.JASS directory and renamed as uucp.JASS.timestamp. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

disable_rc_file

Use this function to disable the execution of a run-control file. This function accepts two string values representing the directory name in which the script is located and the run-control script name. To be executed, a script name must begin with either an S or a K depending on its purpose as a start or kill run-control script. This function disables the script by prepending a prefix of underscore (_) to the file name, thereby preventing its execution by the run-control framework. In addition, a suffix of .JASS.timestamp is appended to the disabled file.

Example Usage:


disable_rc_file /etc/rc2.d S71rpc

This example renames a file from /etc/rc2.d/S71rpc to /etc/rc2.d/_S71rpc.JASS.timestamp. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

disable_service



Note - This function is used only for SMF in Solaris 10.



Use this function to disable all SMF services on a given FMRI list. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Argument: $1 - FMRIs of the one or more SMF services to be disabled

Returns: None

Example Usage:


disable_service "svc:/application/x11/xfs:default"

enable_service



Note - This function is used only for SMF in Solaris 10.



Use this function to enable all SMF services on a given FMRI list. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Argument: $1 - FMRIs of the one or more SMF services to be enabled

Returns: None

Example Usage:


enable_service "svc:/network/ipfilter:default"

find_sst_run_with

Use this function to find the most recent, still active Solaris Security Toolkit run with a given keyword-value pair as specified. See set_stored_keyword_val (set_stored_keyword_val) and get_stored_keyword_val (get_stored_keyword_val) for more information about storing and retrieving the keyword-value pair.

This function searches through all Solaris Security Toolkit runs on the system that have not been undone. If any of those runs have used the set_stored_keyword_val command to store the keyword-value pair being searched for, the function returns the timestamp of the most recent one. If none of these runs have used this command, nothing is returned.

Arguments: $1 - Keyword to be checked
$2 - Value being searched for

Returns: Prints the timestamp of the most recent active run using that script
and keyword-value pair, or "" if no such run was found.

Example Usage:


last_date=`find_sst_run_with MY_STORED_VALUE 17`

get_expanded_file_name

Use this function to return the tag-expanded file name as described in copy_files.

Argument: $1 - File name

Returns: Expanded file name, or empty if no file name matched

Example Usage:


get_expanded_file_name /etc/motd

This example would return /etc/motd.jordan if the file JASS_HOME/Files/etc/motd.jordan existed when the function was run on system jordan.

get_stored_keyword_val

Use this function to retrieve a stored keyword-value pair from a saved file. The saved file used defaults to the JASS_RUN_VALUES file, but you can specify your own file name.

Arguments: $1 - Keyword to be checked
$2 - Repository name, blank is default

Returns: 0 - Keyword was found. RETURN_VALUE has been set to the value in
the file
1 - File was not found.
2 - Keyword was not set in the file.

Example Usage:


if get_stored_keyword_val MY_STORED_VALUE; then
...

get_users_with_retries_set

Use this function to obtain those user accounts with a password that have an user_attr entry with lock_after_retries set. This function is useful in both audit and finish scripts. (See enable-account-lockout.fin or enable-account-lockout.aud.)

Argument: $1 - List of users to be filtered out

Returns: List of users with password and lock_after_retries set.

Example Usage:


user_list=`get_users_with_retries_set "root"`

is_patch_applied and is_patch_not_applied

Use these functions to determine if a patch is applied to a system. These functions accept a single string value representing the patch number to check.

This value can be specified in one of two ways:

Example Usage:


is_patch_applied 123456

Example Usage:


is_patch_applied 123456-02

is_service_enabled



Note - This function is used only for SMF in Solaris 10.



Use this function to determine whether an SMF service is enabled.

Argument: $1 - FMRI of SMF service to check

Returns: 0 - Service is enabled or will be enabled after reboot.
1 - Service is disabled and no enable script is present in the upgrade
manifest, or the FMRI is not recognized.

Example Usage:


is_service_enabled "svc:/network/ipfilter:default"

is_service_installed



Note - This function is used only for SMF in Solaris 10.



Use this function to determine whether an SMF service is installed. In stand-alone mode, an SMF command does the verification. In JumpStart mode, the verification is done by searching the service manifest .xml files.

Argument: $1 - FMRI of the SMF service to check

Returns: 0 - Service is installed (stand-alone mode), or the service manifest
exists (JumpStart mode).
1 - Service is not installed (stand-alone more), no service manifest
exists (JumpStart mode), or the FMRI is not recognized.

Example Usage:


is_service_installed "svc:/network/ipfilter:default"

is_service_running



Note - This function is used only for SMF in Solaris 10, and cannot be used in JumpStart mode.



Use this function to determine whether an SMF service is running.

Argument: $1 - FMRI of the service to check

Returns: 0 - Service is running
1 - Service is not running

Example Usage:


is_service_running "svc:/network/ipfilter:default"

is_user_account_extant



Note - Use this function only for systems running the Solaris 10 OS.



Use this function to determine whether a user account exists.

Argument: $1 - User account name to check

Returns: 0 - User account exists
1 - User account does not exist

Example Usage:


is_user_account_extant "nuucp"

is_user_account_locked



Note - Use this function only for systems running the Solaris 10 OS.



Use this function to check if a user account is locked in the password file.

Argument: $1 - User account name to check

Returns: 0 - User account is locked
1 - User account is not locked

Example Usage:


is_user_account_locked "nuucp"

is_user_account_login_not_set



Note - Use this function only for systems running the Solaris 10 OS.



Use this function to check whether a user account has a password set.

Argument: $1 - User account name to check

Returns: 0 - User password is not "NP"
1 - User password is "NP"

When "NP" (no password) is returned from this function, then the user has no password defined and could be able to log in without one. Whether the user can actually log in without a password, depends on how the user is logging in and what the security restrictions are of that login mechanism. For example, Secure Shell is configured, by default, to not allow a user who does not have a password to log in.

Example Usage:


is_user_account_login_not_set "root"

is_user_account_passworded



Note - Use this function only for systems running the Solaris 10 OS.



Use this function to verify whether a user account has a password entry in the /etc/shadow file.

Argument: $1 - User account name to check

Returns: 0 - User account is in the password file
1 - User account is not in the password file

Example Usage:


is_user_account_passworded "root"

lock_user_account



Note - Use this function only for systems running the Solaris 10 OS.



Use this function to lock a user account.

Argument: $1 - User account name to lock

Returns: None

Example Usage:


lock_user_account "nuucp"

make_link

Use this function to create a symbolic file link. This function automatically adds the necessary manifest entries to be reversed during an undo run.

Argument: $1 - Source link file name
$2 - Destination link file name

Returns: None

Example Usage:


make_link ../lib/sendmail ${JASS_ROOT_DIR}usr/bin/newaliases

mkdir_dashp

Use this function to create a new directory on a target system. This function accepts a single string value representing the name of the directory to create. This function uses the -p option to mkdir so that no error is reported if the target directory exists. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Example Usage:


mkdir_dashp /usr/local

move_a_file

Use this function to move a file from one name to another. This function requires two entries: a source file name and a destination file name. This function moves, or renames, the source file to the file name specified by the destination parameter. This function automatically adds the necessary manifest entries to permit this operation to be reversed during an undo run.

Example Usage:


move_a_file /tmp/test-file-a /tmp/test-file-b

rm_pkg

Use this function to remove Solaris OS packages from a system. The operations performed by this function are final and cannot be reversed during an undo run. The options for this function are listed in TABLE 2-6.


TABLE 2-6 rm_pkg Function Options

Option

Description

-a ask_file

pkgrm ask file name. By default, the pkgrm ask file, noask_pkgrm, is used if no other file is specified.

-o options

pkgrm command options

package

Package to be removed


Example Usage:


rm_pkg SUNWadmr

set_service_property_value



Note - This function is used only for SMF in Solaris 10.



Use this function to set a property value for an SMF service.

Arguments: $1 - FMRI of the service
$2 - property name to set
$3 - property value to set

Returns: None

Example Usage:


set_service_property_value "svc:/network/inetd" "defaults/tcp_wrappers" "true"

set_stored_keyword_val

Use this function to set a stored keyword-value pair to a saved file. The default file used is the JASS_RUN_VALUES file.

Arguments: $1 - Keyword to be set
$2 - Value to be set

Returns: 0 - Keyword is set. If a keyword that already exists in the file is being
set, the old value is overwritten
1 - Problem writing to the file..

Example Usage:


get_stored_keyword_val MY_STORED_VALUE 23

unlock_user_account



Note - This function is used only for SMF in Solaris 10.



Use this function to unlock a user account. This function automatically adds the necessary manifest entries to be reversed during an undo run.

Arguments: $1 - User account name to unlock

Returns: None

Example Usage:


unlock_user_account "adm"

update_inetconv_in_upgrade

Use this function to write an instruction to run the inetconv(1M) command in the upgrade file, which is run after rebooting. The inetconv command imports inetd.conf entries into the SMF repository. This function automatically adds the necessary manifest entries to be reversed during an undo run.

Argument: None

Returns: 0 - Success
1 - Failure

Example Usage:


update_inetconv_in_upgrade

warn_on_default_files

Use this function to issue logWarning commands about any files in the Solaris Security Toolkit distribution that have not been modified by the user. Because these files can be installed by the Solaris Security Toolkit, with unpredictable results if not fully configured, you should check these files to ensure the files are what you expect. Modifying the file, or having a customer version not shipped in the distribution produces no warning.

Arguments: ${1} - One or more files to check.

Specify the fully qualified, installed target path relative to the front
slash root (/), without any prefix. For example, /etc/motd.

Returns: None

Example Usage:


warn_on_default_files /etc/opt/ipc/ipf.conf

write_val_to_file

Use this function to write a name value pair separated by an equal sign (=) to a file. If the value is null, nothing is written. Use this functions with the check_and_log_change_needed function (see check_and_log_change_needed.)

Arguments: $1 - File name
$2 - Keyword in the file
$3 - New value

Returns: None

Example Usage:


write_val_to_file /etc/default/passwd MINALPHA 7


Using Audit Functions

Two types of audit functions are provided in the software: private and public. The functions defined in the audit_private.funcs file are private and not for public use. Never use the private scripts defined in this file. Use only the public scripts defined in the audit_public.funcs file.

The public functions define audit functions used in audit scripts, which are located in JASS_AUDIT_DIR. Functions defined in this file are public and can be freely used in both standard and custom audit scripts. Note that in many cases, the functions defined in this file are stubs that call functions defined in the audit_private.funcs file. These stubs were implemented to allow users to code their scripts to these public interfaces without needing to care if the underlying code is modified or enhanced in newer releases.

Use these functions as part of audit scripts to assess components of the system's stored and runtime configurations. The following functions are public interfaces to the Solaris Security Toolkit software's audit framework.

When customizing or creating audit scripts, use the following functions to perform standard operations.

check_fileContentsExist and
check_fileContentsNotExist

Use these functions to determine if a designated file has content matching a supplied search string. The search string can be in the form of a regular expression. These functions display a 0 for success, 1 for failure, and 255 for an error condition.

You can supply the following arguments to these functions:

Example Usage:


check_fileContentsExist /etc/default/inetinit "TCP_STRONG_ISS=2" 1 LOG

check_fileExists and
check_fileNotExists

Use these functions to determine if a file exists on a target system. These functions display a status of 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_fileExists /etc/inet/inetd.conf 1 LOG

check_fileGroupMatch and
check_fileGroupNoMatch

Use these functions to determine if a file belongs to a group on a target system. These functions display a status of 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_fileGroupMatch /etc/passwd sys 1 LOG
check_fileGroupMatch /etc/passwd 3 1 LOG

check_fileModeMatch and
check_fileModeNoMatch

Use these functions to determine if a file has the permissions specified on a target system. These functions display a status of 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_fileModeMatch /etc/passwd "0444" 1 LOG
check_fileModeMatch /etc/passwd "ugo=r" 1 LOG

check_fileOwnerMatch and
check_fileOwnerNoMatch

Use these functions to determine if a file belongs to a specific user on a target system. These functions display a status of 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_fileOwnerMatch /etc/passwd root 1 LOG
check_fileOwnerMatch /etc/passwd 0 1 LOG

check_fileTemplate

Use this function to determine if a file template defined by the Solaris Security Toolkit software matches its counterpart installed on a target system. For example, if you were to use this function to check the file template /etc/motd, this function would compare the contents of JASS_FILES_DIR/etc/motd with /etc/motd to determine if they were the same. If they were identical, this function would display 0 for success, 1 for failure, or 255 for any error condition. If you specify more than one file, they all must pass to get a display code of 0.

You can supply the following arguments to this function:

Example Usage:


check_fileTemplate /etc/motd 1 LOG

check_fileTypeMatch and
check_fileTypeNoMatch

Use these functions to determine if a file system object is a specific object type on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

TABLE 2-7 lists the file types detected by the software:


TABLE 2-7 File Types Detected by the check_fileTypeMatch Function

File Type

Description

b

Block special file

c

Character special file

d

Directory

D

Door

f

Regular file

l

Symbolic link

p

Named pipe (fifo)

s

Socket


Example Usage:


check_fileTypeMatch /etc/passwd f 1 LOG
check_fileTypeMatch /etc d 1 LOG

check_if_crontab_entry_present

Use this function to check if crontab entry $2 is present in the crontab file for user $1.

Arguments: $1 - User name of the crontab file owner
$2 - Program name to check in the crontab table

Returns: 0 - $2 is present
non-zero - crontab entry $2 missing or crontab file is missing

Example Usage:


check_if_crontab_entry_present adm /usr/lib/acct/ckpacct

check_keyword_value_pair

Use this function for a more convenient way to check a keyword-value pair in a file, which is a common audit task. The keyword must be the first non-whitespace character on a line, separated from its value by an equal sign (=). The file being checked must exist; otherwise, the function's behavior is undefined.

Arguments: $1 - File to be checked
$2 - Keyword to be checked against value in $3
$3 - Value to be checked against keyword in $2

Returns: None

Example Usage:


check_keyword_value_pair {JASS_ROOT_DIR}etc/security/policy.conf CRYPT_DEFAULT 1

check_minimized

Use this function when a package check should only be performed on a minimized platform. (A minimized platform is one that has had Solaris OS packages removed that are not needed.) This function is similar to the check_packagesNotExist function, except that its behavior is controlled by the JASS_CHECK_MINIMIZED environment variable. If a target system is not minimized, then the JASS_CHECK_MINIMIZED environment variable should be set to 0. In this case, this function does not perform any of its checks and simply displays a value of 0 with a notice indicating that a check was not run. Otherwise, this function behaves exactly as the check_packageNotExists function and displays a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to this function:

Example Usage:


check_minimized SUNWatfsu 1 LOG

check_minimized_service



Note - Use this function only for SMF on systems running the Solaris 10 OS.



Use this function to check for services that are not installed. Use this function in the special case when the existence of packages is not necessarily an error; for example, when the system has not been minimized. This function is controlled by the environment variable JASS_CHECK_MINIMIZED = 1 (see Chapter 7 for more details).

Arguments: $1 - services - List of services to check
$2 - vulnValue - Vulnerability value (integer)
$3 - logStatus - Logging status (optional)

Returns: 255 - If an error occurs or the supplied arguments are invalid
0 - If none of the packages exist
1 - If at least one of the packages exist

Example Usage:


check_minimized_service "svc:/network/finger:default" 1 LOG

check_packageExists and
check_packageNotExists

Use these functions to determine if software package are installed on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_packageExists SUNWsshdu 1 LOG

check_patchExists and
check_patchNotExists

Use these functions to determine if software patches are installed on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_patchExists 123456 1 LOG
check_patchExists 123456-01 1 LOG



Note - You can specify a patch revision. If you do, then any installed revision must be equal to or greater than the revision specified. If you do not specify a revision, then this function indicates success if any version of the patch is installed.



check_processArgsMatch and
check_processArgsNoMatch

Use these functions to determine if a process is running on the system with specific runtime arguments. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_processArgsMatch /usr/sbin/syslogd "-t" 1 LOG

check_processExists and
check_processNotExists

Use these functions to determine if processes are running on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_processExists sshd 1 LOG

check_serviceConfigExists and
check_serviceConfigNotExists

Use these functions to determine if service configuration files exist on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_serviceConfigExists /etc/ssh/sshd_config 1 LOG

check_serviceDisabled and
check_serviceEnabled



Note - These functions are used only for SMF in Solaris 10.



Use these functions to check a list of services to see whether each service is disabled or enabled.

Arguments: $1 - services - List of services to check
$2 - vulnValue - Vulnerability value
$3 - logStatus - Logging status (set to LOG if logging desired on
failures)
$4 - relatedInfo - Related information string

Returns: 255 - If an error occurs or the supplied arguments are invalid
0 - If all services are disabled/enabled
1 - If at least one service is disabled/enabled

check_serviceInstalled and
check_serviceNotInstalled



Note - These functions are used only for SMF in Solaris 10.



Use these functions to check a list of services to see whether each service is installed.

Arguments: $1 - services - List of services to check
$2 - vulnValue - Vulnerability value
$3 - logStatus - Logging status (set to LOG if logging desired on
failures)
$4 - relatedInfo - Related information string

Returns: 255 - if an error occurs or the supplied arguments are invalid
0 - If none/all of the services exist
1 - If at least one of the packages exists/does not exist

Example Usage:


check_serviceInstalled svc:/network/ssh:default 1 LOG

check_serviceOptionEnabled and
check_serviceOptionDisabled



Note - These functions are used only for SMF in Solaris 10.



Use these functions to have an SMF command check if an option of a service's property is enabled or disabled.

Arguments: $1 - List of services to check
$2 - Property of the service to check for
$3 - Pattern before the option
$4 - Option
$5 - Integer vulnerability value
$6 - Set to "LOG" if logging desired on failures (optional)
$7 - Related information string (optional)

Returns: 255 - if an error occurs or the supplied arguments are invalid
0 - Service option is enabled (disabled)
1 - Service option is disabled (enabled)

check_servicePropDisabled



Note - This function is used only for SMF in Solaris 10.



Use this function to have an SMF command check to see if an option of a service's property is disabled.

Arguments: $1 - List of FMRIs
$2 - property
$3
- vulnvalue
$4
- logStatus

Returns: 255 - if an error occurs or the supplied arguments are invalid
0 - Property is enabled (disabled)
1 - Property is disabled (enabled)

check_serviceRunning and
check_serviceNotRunning



Note - These functions are used only for SMF in Solaris 10.



Use these functions to check a list of services to see whether each service is running.

Arguments: $1 - List of services
$2 - vulnvalue
$3
- logStatus
$4
- related Info

Returns: 255 - if an error occurs or the supplied arguments are invalid
0 - All services are running/not running
1 - At least one service is not running

check_startScriptExists and
check_startScriptNotExists

Use these functions to determine if run-control start scripts exist on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_startScriptExists /etc/rc3.d/S89sshd 1 LOG

check_stopScriptExists and
check_stopScriptNotExists

Use these functions to determine if a run-control stop script exists on a target system. These functions display a 0 for success, 1 for failure, and 255 for any error condition.

You can supply the following arguments to these functions:

Example Usage:


check_stopScriptExists /etc/rc2.d/K03sshd 1 LOG

check_userLocked and
check_userNotLocked



Note - Use these functions only for systems running the Solaris 10 OS.



Use these functions to check if a user account is locked.

Arguments: $1 - User ID

Returns: 255 - If an error occurs, or the supplied arguments are invalid
0 - If the user is locked
1 - If the user is not locked

finish_audit

Use this function to signal that a check script has completed all of its processing and that a score for the script must be computed. This function is typically the last entry in a check script. If you want to display a message indicating a script's termination, then pass a single string argument to this function.

Example Usage:


finish_audit

finish_audit "End of script"

 

get_cmdFromService



Note - Use this function only for systems running the Solaris 10 OS.



Use this function to obtain a list of commands, or processes, for a running service.

Arguments: $1 - Service name

Returns: "" - If no process is associated with the service
process list - processes associated with a particular service in the
form { pid user comm [pid user common] }

Example Usage:


get_cmdFromService svc:/network/ssh:default

start_audit

Use this function to call an audit script. This function is typically the first instruction in an audit script, not including comments or variable declarations. This function defines the name of the script, displays the banners, and resets the script score to 0.

Arguments: $1 - Audit script name
$2 - Audit script description, can be multiple lines and is formatted
using the logFormattedMessage function.
$3 - Related information that you want displayed for users after a
PASS or FAIL message (optional), formatted using the
logFormattedMessage function.

Returns: 255 - If an error occurs, or the supplied arguments are invalid
0 - If the user is locked
1 - If the user is not locked

Example Usage:


start_audit disable-apache.aud "Apache" "Description of Check"

Example Output:


#--------------------------------------------------------------
# Apache
#
# Description of Check
#--------------------------------------------------------------