Creating input security metadata for security discovery analysis

A security administrator runs a JCL job to extract the RACF® definitions and convert them into input security metadata, which represents the security definitions for roles and transactions in an ESM agnostic format.

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

Before you begin

To create the security metadata for each set of CICS® regions that share security definitions, make sure the regions have the same RACF class(es) and SECPRFX SIT parameter.

For more information about security metadata, see What is security metadata?. This task does not require you to back up the data.

Procedure

  1. The security administrator needs to customize the DFH$R2SM JCL, which is a sample in hlq.SDFHSAMP.
    Customize the following parameters as needed:
    SECMETA EXEC DFHXSMET,SAMPLIB=hlq.SDFHSAMP
    The JCL uses REXX programs in the CICS sample library. On this line, change hlq to the installed library’s high-level qualifier.
    DIR
    Specifies the directory to one on zFS into which the output file will be created. This directory must already exist.
    FN
    Specifies the file name of the output file. The file will be created in ASCII with a file extension of .esm.
    CYL
    Specifies the number of cylinders that allows for the size of the RACF data to be extracted. The default allows for two million lines of output, which is sufficient for most installations.
    Xnnn
    The name of the CICS classes as defined on the SIT security class parameters (Xnnn), for example, XTRAN=CICSTRN, XFCT=CICSFCT.
    The transaction classes are always required. If XTRAN=NO is specified in the JCL, an error is returned:
    ERROR: XTRAN is not supported and terminates with Return code 12

    For other classes, Xnnn=NO is assumed unless the option is otherwise specified.

    SECPRFX
    The security prefix as defined on the SECPRFX SIT parameter.
    HIDE
    Obfuscates the output if you need to send it to IBM® for diagnostic purposes. Set it to NO for customer use.
    DEBUG
    Use it for diagnostic purposes if you need IBM support. Set it to NO for customer use.
  2. The job needs to be submitted by the security administrator who has at least ROAUDIT authority so that the RACF commands extract all of the transaction and group data.

    The security metadata looks like the following example:

    Figure 1. An example of generated security metadata
    --- # Security Metadata--- 
version: 2
file_created:
  - date: "17 Mar 2023"
  - time: "15:27:26"
  - user: SUE
  - esm: "RACF"
group_list:
  - name: MANAGER
    users:
      - MAINWRN
user_list:
  - user: MAINWRN
    username: "George Mainwaring"
secprfx: NO
classes:
  - class: XTRAN
    name: CICSTRN
    profiles:
      - name: MENU
        access_lists:
          - access: READ
            groups:
              - MANAGER
  3. Job steps return a completion code:
    • 0 - successful completion
    • 4 - warning messages issued (the job will continue)
    • 8, 12 - error messages issued (the job will terminate)
  4. Each job step might result in messages being issued to SYSTSPRT. Warning messages are issued for unsupported definitions as these definitions cannot be processed by the conversion programs.

Result

The security metadata is generated in ASCII on zFS.

What to do next

The security administrator passes the security metadata to the system programmer for analysis in CICS Explorer®. For instructions, see Analyzing security definitions using security discovery in CICS Explorer.

6.2 and later Optionally, the system programmer can capture security discovery data (SDD) as additional input data for analysis in CICS Explorer.