TSSUTIL Utility

This section contains the following topics:

How to Report and Archive Security-Related Activity

Using the TSSUTIL Utility

Authority and Scope

TSSUTIL JCL

Formatted Record Types

TSSUTIL Verbs

TSSUTIL Report Selection Criteria

TSSUTIL Report Description

TSSUTIL Abend and Return Codes

How to Report and Archive Security-Related Activity

The TSSUTIL batch utility processes security-related activity that is recorded in SMF data sets and the CA Top Secret Audit/Tracking File. You can use TSSUTIL to perform the following activities:

Produce reports about activity.
Archive activity.

In a single execution of TSSUTIL, you can generate multiple different reports based on the same SMF or Audit/Tracking File input data.

To use TSSUTIL to archive and report on security-related activity:

Ensure that you have authority to use TSSUTIL.
Configure logging options to ensure that relevant security information is available for archiving and reporting.
Assemble JCL for the TSSUTIL job. JCL includes the following components:
- DD statements (if using SMF input)
- Verbs (EXTRACT to archive security incidents and REPORT to report on incidents)
- Selection criteria (to select types of incidents to process)
Submit the JCL to execute TSSUTIL.
CA Top Secret extracts data or produces reports according to your specifications.

Using the TSSUTIL Utility

The following considerations affect the TSSUTIL utility:

Reports are produced with events in the order found in the SMF or Audit/Tracking Files. No sorting is performed. For SMF data sets, the order is normally chronological. When the input is the CA Top Secret audit tracking file, the records are in order from the beginning of the files. If the file has wrapped or if an audit file switch has occurred, the report may not be in chronological order. Use the CA SORT or DFSORT utilities to create an input file sorted by date. For information, see the section TSSUTIL JCL.
Report and tracking depends greatly upon the correct specification of logging options. The LOG control option lets you request the type of events to be logged, specify where logging information is recorded, and choose where violation notification is to be made.

The following logging options are required to record the related security information for later reporting via TSSUTIL:

LOG(INIT,...) requests logging of all job/session initiations and terminations.
LOG(SMF,...) requests SMF recording of selected events.
LOG(ACCESS,...)
requests logging of all resource access.

Logging options can be set globally by the LOG control option or by facility using the LOG suboption of the FACILITY control option.
Security violations are always reported in the EVENT(AUDIT) report. To obtain audited events other than security violations, you must run the EVENT(AUDIT) report and have events being audited for resources or user activity via one of the following:
```
TSS ADDTO(acid) AUDIT
TSS PERMIT(acid) resclass(resource) ACTION(AUDIT)
TSS ADDTO(AUDIT) resclass(resourcename)
TSS MODIFY FACILITY(facilityname=AUDIT)
```
The Audit/Tracking Files should be backed up using the TSSARCHI job provided in CAI.CAKOJCL0. This job uses the EXTRACT keyword to retrieve all the events recorded in the atf(s) and places them on tape using the DCB attributes RECFM=VB and LRECL=465.
The EXTRACT function will produce either the SMFOUT, XTROUT file, or both depending on the situation. See the explanation of the EXTRACT keyword for a description of these files.
For z/OS 1.9 and above, SMF data may be sent to the LOGGER services controlling the write of SMF data in LOGSTREAM structures. SMF data will not be recorded in the usual SYS1.MANx data sets. The TSSRPTST utility is able to read the data when:
- The LOGR services are active on the system with the definitions that contains the SMF data.
- A LOGR subsystem is active on the system
- An IEFSSNxx member is defined and activated at IPL time with the definition:
```
	SUBSYS SUBNAME(LOGR) INITRTN(IXGSSINT) 
```
The RECxxxxx DD used to read the data has the format:
```
//RECxxxxx DD  DSN=IFASMF.DATA.LOGSTRM,DISP=SHR, 
//          SUBSYS=(LOGR,IFASEXIT,subsys-options1,subsys-options2) 
```
Description of SUBSYS options-1 includes:
```
[FROM={({[yyyy/ddd][,hh:mm[:ss]]}) | OLDEST}]
[TO={({[yyyy/ddd][,hh:mm[:ss]]}) | YOUNGEST}]
 [,DURATION=(nnnn,HOURS)]
 [,VIEW={ACTIVE|ALL|INACTIVE}]
 [,GMT|LOCAL]
```
The subsys-options1 parameters used by the IBM IFASEXIT are the same as those used by the IFBSEXIT. For information on the parameters for IFBSEXIT, see IBM's MVS Diagnosis: Tools and Service Aids.

Authority and Scope

To use TSSUTIL, an ACID must possess REPORT authority. This administrative authority might be given by anyone who has REPORT authority by entering the following command.

TSS ADMIN(acid) ACID(REPORT)
                RESOURCES(REPORT)

A user with no administrative authority may use TSSUTIL if given USE access to entity “TSSUTILITY.TSSUTIL” in the CASECAUT resource class. This access may be granted by an administrator using the following command:

TSS PERMIT(user) CASECAUT(TSSUTILITY.TSSUTIL) ACCESS(USE)

You can only extract those incidents that are generated for ACIDs within the scope of your authority. The scopes are as follows:

SCA: Every event
LSCA: Every event within the LSCAs scope
ZCA: Entire zone or specific divisions, departments or ACIDs within the zone
VCA: Entire division or specific departments or ACIDs within the division
DCA: Entire department or specific ACIDs within the department
USER: Himself

Note: When using EVENT(VIOL) or EVENT(AUDIT) VCAs and DCAs are allowed to view VIOL and AUDIT events for owned resources even if the subject acid is not within their scope. VCAs using EVENT (VIOL|AUDIT) and specifying a department will get resources within that department's scope. For more details about EVENT, see TSSUTIL Report Selection Criteria.