Capturing security discovery data (SDD)

6.2 and later Applies to 6.2 and later.

Security discovery records security access requests within CICS®, contained in what's called the security discovery data (SDD). SDD is specific to CICS and records in SDD include access requests that were performed as a result of the existing security settings. They can also be access requests that would have been performed if the security settings were changed to allow it. With SDD, you can identify what security definitions would be required if the current CICS resource security were extended to include another resource classes.

For a list of data that is captured by security discovery, see Data captured by CICS security discovery.

For an overview of the whole security discovery process, see How it works: CICS security discovery. This task is Step 2 in that flow.

Before you begin

You must have configured your CICS regions for security discovery. For instructions, see Setting up CICS security discovery.

Important:

The security discovery state persists over a warm or an emergency restart. On a cold or an initial start of CICS, security discovery is inactive.

In case of a cold or an initial start, you need to manually reissue the SET SECDISCOVERY commands or add them to a program that runs as part of PLT to turn it on. See Activating CICS security discovery during CICS startup.

About this task

CICS always records transaction attach requests when security discovery is active. Such requests are protected by the XTRAN system initialization parameter. You need to decide what additional access requests are recorded based on business requirements to protect the associated resources.

Security discovery data (SDD) is never reset while CICS is running. When the data is written to the DFHSECD log stream, it is the complete set of data since security discovery was first activated in the region.

Recommendation: You are advised to use a single shared log stream for regions with identical security settings. The chance of contention is low because the data is usually only written to the log stream at end of day. A randomization process means that multiple regions do not write their data at the same time.

Procedure

Decide what security requests you want to discover in addition to transaction attach requests.
Decide the set of regions where security discovery needs to be activated.

A good starting point is to activate security discovery across a set of regions that run a similar workload, such as an application, and have identical CICS security settings.
Activate security discovery in either of the following ways:
- In CICS Explorer®, navigate to the Security Discovery Records view. Right-click the row of the region in which you want to activate security discovery and select Set Discovery Status > Switch On Security Discovery. For more options in CICS Explorer, see Security Discovery Records view in CICS Explorer documentation.
- Use a PLT program to activate security discovery during CICS startup. For instructions, see Activating CICS security discovery during CICS startup.
- Write your own transaction by using the SET SECDISCOVERY SPI command to switch recording on. For more information about options on the command, see SET SECDISCOVERY.
CICS captures the SDD in memory and writes the data out to the DFHSECD log stream at end of day or when the region shuts down.
- If needed, you can cause CICS to write the SDD to the log stream immediately with either of the following methods. Security discovery statistics are written to the DFHSECD log stream at the same time and the values are reset.
  
  CICS Explorer
  
  In the Security Discovery Records view, right-click the row of the region against which you want to perform the action. Then click Write Security Discovery Records. For more information, see Security Discovery Records view in CICS Explorer documentation.
  
  SPI commands
  
  Issue the PERFORM SECDISCOVERY WRITE command from your transaction.
- To check whether any new data has been recorded since the last time CICS wrote data to the log stream, use the DFHXS1602 message and either of the following methods to gain status information about security discovery. You can know when most or all of the SDD in the region is captured and the volume of the data that is to be processed by CICS Explorer.
  
  CICS Explorer
  
  The Security Discovery Records view shows the security discovery information per CICS region.
  
  SPI commands
  
  Issue the INQUIRE SECDISCOVERY command from your transaction.
To process the log stream, copy the DFH$SDDP JCL from the SDFHSAMP library and customizing the following variables:
HLQ

Is the high-level qualifier of your CICS libraries.

SDD

Is the file name to which the SDD file is written. The directory containing this file must already exist. The file extension must be .sdd.

LOGSTRM

Is the name of the log stream that contains the SDD.

To affect how the log stream data is processed, specify parameters for the DFHSDD program in the SYSIN data set. If none of the parameters are specified, every record in the log stream will be processed. Lines beginning with an asterisk are ignored.

APPLID=applid

Processes records with a matching APPLID. A trailing wildcard (*) can be specified.

STARTTIME=YYYYMMDDHHMMSS

Specifies a local date and time. All records before this time are ignored.

ENDTIME=YYYYMMDDHHMMSS

Specifies a local date and time. All records after this time are ignored.

TRACE

If you encounter problems, specify the TRACE option to capture a trace to the DFHTRACE destination.
This trace data can be used by IBM® support to diagnose the problem.
If you need to process data from multiple log streams, update the DFHSECD DDNAME within the SDD step to add a DD statement for each additional log stream that is to be processed:
```
//DFHSECD DD DSNAME=&LOGSTRM.,DCB=BLKSIZE=32760,
// SUBSYS=(LOGR,DFHLGCNV)
// DD DSNAME=HLQ.SECOND.LOGSTRM,DCB=BLKSIZE=32760,
// SUBSYS=(LOGR,DFHLGCNV)
```
Look at the SUMMARY output from the job. The output shows how many records were processed and how many were ignored as a result of the selection parameters or failing to match the security settings of the first record that was processed.
For an example of the SUMMARY output, see Example.

Results

You have successfully captured the SDD. You can then use the .sdd file as input for the security discovery analysis in CICS Explorer.

CICS security discovery statistics were also written to DFHSECD. The statistics were formatted by DFH$SDDP and the output was written to the STATS destination. The statistics can be used to estimate the cost of activating additional resource security within CICS.

Example

The following snippet shows an example of SUMMARY output:

Writing trace output to DFHTRACE. 
Selecting APPLID=CICSAPP* 
Selecting STARTTIME=20230310112500
Selecting ENDTIME=20230320115500

*****************
* Record counts *
*****************

SDD records read.......................: 12 
SDD records selected...................: 10 
SDD records rejected...................: 0 
Userids processed......................: 5
Transactions processed.................: 2

********************* 
* Security Settings *
*********************

SECPRFX = PROD
XCMD    = CICSCMD 
XDB2    = CICSDB2         
XDCT    = CICSDCT 
XFCT    = CICSFCT 
XHFS    = YES
XJCT    = CICSJCT 
XPCT    = CICSPCT 
XPPT    = CICSPPT 
XPSB    = CICSPSB 
XRES    = CICSRES         
XTRAN   = CICSTRN 
XTST    = CICSTST         
XUSER   = SURROGAT

The first section confirms the parameters that are in effect.

Within the Record counts section:

SDD records read: Shows the total number of records read from the DFHSECD log stream.
SDD records selected: Shows the number of records that met the selection criteria based on the input parameters.
SDD records rejected: Shows the number of records rejected due to having different security settings.
Userids processed: Shows the number of unique user IDs found within the processed records.
Transactions processed: Shows the number of unique transaction IDs found within the processed records.

The Security Settings section lists the SECPRFX and the RACF® class names for each system initialization parameter. These values come from the first record processed. All subsequent records must match these settings.