POLYCENTER
Security Compliance Manager for OpenVMS
User's Guide
Previous Contents Index

Chapter 2
User-Defined Tests

Introduction

POLYCENTER Security CM allows you to create your own test collections using your choice of supported programming language (for example, DCL) and include them in inspectors. This chapter provides information and guidelines for creating your own test collections and successfully integrating them in POLYCENTER Security CM.

In This Chapter

This chapter contains the following sections:

2.1 The Executor and User-Defined Tests

Summary

To successfully create and use your own test collections, you need a basic understanding of how the executor will deal with your tests. This section provides you with that explanation.

Understanding How the Executor Works

When an inspection is due to run, the executor analyzes the required work and creates the data structures and the logical names necessary to communicate with the test programs. When initialization is complete, the executor spawns subprocesses that run the programs that correspond to the user-defined test collections.

The executor takes the name of the user-defined program entered in the User Written Programs Dialog on the POLYCENTER Security Console GUI, and creates a command procedure to run this program. For example, imagine that to invoke your test you enter the program name USER$DISK1:SYS$MANAGER:MY_TEST.EXE on the GUI. The executor creates the following command procedure: 


$ RUN USER$DISK1:SYS$MANAGER:MY_TEST.EXE

Then, when you run an inspector, the subprocess runs this command procedure and invokes your user-defined test collection. As long as your test collections follow the protocols described in the rest of this chapter, the results are included with the rest of the results for the inspector.

When test programs complete, the user-defined test programs call the SYS$EXIT system service to indicate the final result, Pass or Fail. This result is written to a termination mailbox, which the executor assigns to the subprocess and which the executor maintains to synchronize test completion. The status written to the termination mailbox is then stored in a database for later use.

After all user-defined test programs are complete, the executor reads the partial report segment generated by those programs. Whether the results are pass or fail, the partial report segments are included in the total report.

After all user-defined test programs are complete, the executor assembles the final lockdown and unlockdown files. If a user-defined test program passed, its assigned lockdown file is ignored. If a test program fails, its assigned lockdown file is appended to the total lockdown file.

2.2 Guidelines for Creating Your Own Test Collections

Summary

When creating user-defined test collections, there are a number of guidelines you must follow to ensure the seamless integration of your tests into POLYCENTER Security CM. This section provides a summary of these guidelines and then discusses each one in more detail.

Guidelines

The following is a summary of the guidelines.

  1. Store the result you want to report in the report file pointed to by the INSPECT$UD_REPORT logical. See Reporting Results for more information.
  2. Store any lockdown code in the file pointed to by the INSPECT$UD_LOCKDOWN logical and any unlockdown code in the file pointed to by the INSPECT$UD_UNLOCKDOWN logical. You must store code in DCL format. See Generating Lockdown Code for more information.
  3. Open and initialize the report file and lockdown file. Both files must be new.
  4. Perform tests. If the tests find noncompliant conditions, write appropriate report text to the report file and lockdown code to the lockdown file. Record the overall status.
  5. Close the report file and lockdown file.
  6. Define the INSPECT$UD_ITEMSTESTED logical and the INSPECT$UD_ITEMSFAILED logical. These logicals allow you to count the number of items that are tested and the number of items that fail the tests. See Counting Items Tested for more information.
  7. If the test passes, delete the lockdown file and retain or delete the report file. Then, exit with the INSPECT$_PASS status.
    If the test fails, exit with the INSPECT$_FAIL status.

More information on each guideline is contained in the following sections.

Reporting Results

Your test collection can generate POLYCENTER Security CM report text, to describe noncompliant situations. You control the format of your report.

To include report text in the final POLYCENTER Security CM report, write the report text to the file defined by the logical name INSPECT$UD_REPORT. The job logical name table defines INSPECT$UD_REPORT to point to the file that the executor uses to build the final report. The report file must be a new file.

If a test collection passes, and you do not wish to include any informational text in the final report, delete any partial report segment you might have created.

Generating Lockdown Code

Your test collection can generate lockdown code that brings nodes into compliance with the testing performed by your test program. Your test collection can also generate unlockdown code that can reverse changes made by the lockdown code. You control the format of your lockdown and unlockdown code.

To include your lockdown commands in the final POLYCENTER Security CM lockdown command procedure, write the commands to a file defined by the logical name INSPECT$UD_LOCKDOWN. To include your unlockdown commands in the final POLYCENTER Security CM unlockdown command procedure, write the commands to a file defined by the logical name INSPECT$UD_UNLOCKDOWN. The job logical name table defines INSPECT$UD_LOCKDOWN and INSPECT$UD_UNLOCKDOWN to point to the files that the executor uses to build the final lockdown and unlockdown command procedures. These files should be new files.

If a node fails one or more of the test collections, the contents of INSPECT$UD_LOCKDOWN and INSPECT$UD_UNLOCKDOWN are appended to the total lockdown procedure. If the node passes, be sure to delete any partial lockdown segment that you might have created in anticipation of failed test collections.

Lockdown code must not rely on defaults defined outside your user-defined test. It is advisable to test the self-sufficiency of the lockdown code by separately executing the lockdown segment generated by your user-defined test.

Important Information

A user running an inspector must have the privileges required to execute the lockdown file associated with that inspector. Each supplied test allows the user sufficient privileges to execute the part of the script associated with that test. However, when including a user-defined test collection, you must make sure that the user has the required privileges. Using the POLYCENTER Security CM tool does not automatically provide privileges.

Counting Items Tested

Your test collection can track the number of items tested and the number of items that fail the tests. This information is then included in the test report. To track the number of items tested, define the logical INSPECT$UD_ITEMSTESTED in your program. To track the number of items that fail the tests, define the logical INSPECT$UD_ITEMSFAILED. You must define both of these logicals in the job logical name table (LNM$SYSTEM_TABLE).

If you do not define these logicals or you define them incorrectly, the system automatically assigns a value of 1 to INSPECT$UD_ITEMSTESTED and either 0 or 1 to INSPECT$UD_ITEMSFAILED depending on the test result.

Returning Status on Test Completion

When your test collection completes, it must return the final status to the executor. If a noncompliant condition is found, it must return a failure status. If everything passes, it must return a pass status. A status that is unknown or is not a pass status or a fail status is automatically considered to be a fail status. You must indicate how to return the status. Specify one of the following methods:

Using the SYS$EXIT Service

If you are using a high-level programming language, such as C, exit using the constant INSPECT$_PASS (for pass) or the constant INSPECT$_FAIL (for fail). Declare these as constants, for example: 


# define INSPECT$_PASS 8618001 
# define INSPECT$_PASS 8618304

Then link your program as usual.

Using the DCL EXIT Command

If you are using DCL, define DCL symbols that equate to the values of INSPECT$_PASS and INSPECT$_FAIL. The values for these are: 


INSPECT$_PASS = 8618001 
INSPECT$_FAIL = 8618304

When the user-defined DCL test collection completes, use $ EXIT to signal the result with the symbols already defined: 


$ EXIT (INSPECT$_PASS)          ! test passed 
$ EXIT (INSPECT$_FAIL)          ! test failed

2.3 Including User-Defined Test Collections

Summary

This section contains information on tasks you must carry out to integrate user-defined test collections into a POLYCENTER Security CM inspector.

Including User-Defined Test Collections

After you create your test program, you must use the POLYCENTER Security Console GUI to include it in a test inspector. The GUI includes the User Written Programs Dialog to allow you to easily specify the name and location of your program. See the POLYCENTER Security Console for Microsoft Windows NT 4.0 Installation and User's Guide or the GUI online help for more information.

Version 2.3 User-Defined Test Programs

If you have existing test programs that you created for use with POLYCENTER Security CM Version 2.3 or 3.0, you can include them in POLYCENTER Security CM Version 3.1 without modification.

Securing User-Defined Test Programs

The owner of your user-defined test programs must be UIC [1,4]. Inspectors run only user-defined test collections whose programs are owned by UIC [1,4]. If you try to run a test collection that uses a program not owned by UIC [1,4], then POLYCENTER Security CM writes an error to the inspection report.

Chapter 3
The Command Line Interface

Introduction

This chapter explains how to carry out POLYCENTER Security CM tasks from the OpenVMS command line.

In This Chapter

This chapter contains the following sections:

3.1 Command Line Interface Overview

Summary

This section describes the command line interface (CLI).

The CLI and the Local Node

The command line interface allows you to carry out some POLYCENTER Security CM tasks from the OpenVMS command line on the local node. It is expected that you will use the POLYCENTER Security Console GUI to perform most POLYCENTER Security CM tasks.

See the POLYCENTER Security Console GUI online help for more information.

Accessing the CLI

To access the CLI, enter the following command: 


$ INSPECT

POLYCENTER Security CM displays the Main Menu.

The Main Menu

The Main Menu and prompt are displayed as follows: 


 
1.  Start PSCM. 
2.  PSCM Configuration. 
3.  Executor Status. 
4.  Inspector Configuration. 
5.  Configuration of Default Inspector. 
6.  Import Inspector. 
7.  Export Inspector. 
8.  View Log Files 
9.  Generate Lockdown Files. 
10. Extract Inspector to Text File. 
11. Delete Inspector. 
12. Tokens. 
13. PSCM Maintenance. 
14. PSCM Troubleshooting. 
 
e. Exit from POLYCENTER Security Compliance Manager. 
 
Enter choice :

Choosing a Menu Item

To choose a menu item, enter the corresponding number at the Enter choice: prompt. POLYCENTER Security CM carries out the requested action or displays a submenu.

Exiting the CLI

To exit the CLI, enter e at the Enter choice: prompt.

Starting POLYCENTER Security CM

To start POLYCENTER Security CM, enter 1 at the Enter choice: prompt.

3.2 Configuring POLYCENTER Security CM

Summary

This section describes how to configure POLYCENTER Security CM parameters from the CLI.

The PSCM Configuration Menu

The CLI includes the PSCM Configuration Menu to allow you to change the values of a wide range of parameters related to to the way you set up POLYCENTER Security CM. The next 4 sections describe these tasks in detail.
Element Description
Site Configuration Details that are specific to your node or cluster.
Executor Configuration Parameters related to the executor.
Portal Configuration Parameters related to the portal.
PSRF Configuration Parameters related to POLYCENTER Security Reporting Facility (SRF).

Using the PSCM Configuration Menu

To access the PSCM Configuration Menu, enter 2 at the Enter choice: prompt.

To access a sub-menu, for example, Site Configuration, enter the number corresponding to the menu item. To change the value of a parameter, do the following:

  1. Enter the number associated with the parameter at the Enter choice: prompt.
  2. Enter the new value at the Enter New Value: prompt.

3.3 Site Configuration Tasks

Summary

This section describes how to configure POLYCENTER Security CM details that are specific to your site.

Changing Values

You can change the values for the following POLYCENTER Security CM parameters by choosing the number corresponding to the parameter and then entering the new value.

3.4 Executor Configuration Tasks

Summary

This section describes how to configure the operation of the POLYCENTER Security CM executor.

Changing Values

You can change the values for the following POLYCENTER Security CM parameters by choosing the number corresponding to the parameter and then entering the new value:

3.5 Portal Configuration Tasks

Summary

This section describes how to configure POLYCENTER Security CM portal details.

Specifying Values

You can change the values for the following POLYCENTER Security CM parameters by choosing the number corresponding to the parameter and then entering the new value:

Previous Next Contents Index