The daily edition.

Scope: Rocket Enterprise Developer / Enterprise Server 12.0 for Eclipse on UNIX (bundle enterprisedevelopereclux_ug_120). Everything below comes from that manual; no other release or platform is blended in.

What the capability is

Enterprise Server auditing is not limited to events the product itself raises. According to Creating Custom Audit Events, you can create your own audit events using the SAFROUTE API, which handles security-related requests for Enterprise Server applications. The AUDIT request type gives you an audit entry point inside COBOL programs hosted by Enterprise Server, so an application can record business-relevant security facts (for example, that a particular sensitive path was taken) in the same audit stream as the product's own events.

How an event is shaped

An audit event is built from two arbitrary strings, ENTITY and LOGSTR. The manual also notes you can use the username associated with any ACEE, if one is provided. Each event is attributed to either success or failure, and these map to audit event codes 5:1 and 5:2 respectively.

The Audit Event Codes page confirms the mapping in category 5 ("Other request", ESF only):

• 5 1: Audit success (a SAFROUTE AUDIT request with type=1). Parameters: user, the entity string supplied by the caller, and the log string supplied by the caller.
• 5 2: Audit failure (a SAFROUTE AUDIT request with type=2). Same three parameters.

That page also says events from ESF use the mf.safmgr component ID, and that different auditing emitters may separate the two numbers with a space or a colon, so 5 1 and 5:1 are the same event.

The documented workflow

The SAFROUTE API is defined in the copybook SAFAPI.cpy, located in the cpylib directory of the product installation (the manual's default is /opt/rocketsoftware/EnterpriseDeveloper/cpylib/SAFAPI.cpy). The manual's success example is:

identification division.
       program-id. testprog.

       environment division.
       configuration section.

       data division.
       working-storage section.

       copy "SAFAPI.cpy" replacing ==()== by ==ws==.

       01 ws-audit-entity    pic x(11) value "AuditEntity".
       01 ws-audit-string    pic x(11) value "AuditString".

       procedure division.
           move low-values to ws-safpb-parameter-block

           set ws-safpb-cur-ver-88 to true
           set ws-safpb-audit-req-88 to true
           set ws-safpb-audit-success-88 to true
           set ws-safpb-codeset-utf8-88 to true
           set ws-safpb-mod-CICS-88 to true

           set ws-safpb-audit-ENTITY-ptr to address of ws-audit-entity
           set ws-safpb-audit-ENTITY-len to length of ws-audit-entity

           set ws-safpb-audit-LOGSTR-ptr to address of ws-audit-string
           set ws-safpb-audit-LOGSTR-len to length of ws-audit-string

           call 'SAFROUTE' using ws-safpb-parameter-block

           if ws-safpb-api-rc > 0
               *> Audit call failed
           end-if

           goback.

       end program testprog.

Reading the example: the parameter block is cleared to low-values, the current-version and audit-request flags are set, success is chosen with ws-safpb-audit-success-88 (the failure counterpart, mapping to 5:2, is the other outcome), a character set is declared, and the entity and log strings are passed as pointer-plus-length pairs. The call is checked through ws-safpb-api-rc, and the manual's own comment treats a value above zero as "Audit call failed". That means your program should decide deliberately what to do when the audit write itself fails, rather than assuming it succeeded.

Prerequisites and limitations that decide whether anything is emitted

Two caveats on the custom-event page and one on the auditing setup page matter in practice.

First, the manual states that the SAFROUTE API does not work for standalone programs. It is for COBOL programs hosted by Enterprise Server, so you will not see custom events by running the same binary from a plain shell.

Second, the event goes nowhere unless auditing is configured. Configuring Enterprise Server Auditing lists three requirements: a syslog facility listening on a specific port; the security configuration for the service you want to audit (MFDS or a region) set to generate audit events by checking Create audit events and applying; and an audit.cfg file configured to send audit events to the syslog port. For a region using the Default ESM, that checkbox is in the Default ES Security tab; for a region with a specific ESM it is in that region's Security tab.

Third, ordering matters: you must create and configure audit.cfg first. The manual warns that without this file auditing fails and the security manager is not initialized. It belongs in the bin directory of the installation (by default $COBDIR), uses INI format, and is read only when the audit process is initialized, so an edited file requires restarting the audit process. The manual's example selects emitter=syslog, a [syslog] section with hostname, port and protocol (TCP or TLS), and a [TLS] section for the CA root and optional client certificate material.

Takeaway

In 12.0 for UNIX, a hosted COBOL program can add its own audit trail by calling SAFROUTE with the AUDIT request, producing events 5:1 (success) or 5:2 (failure) with caller-supplied ENTITY and LOGSTR strings, but only inside a hosted program and only once Create audit events is enabled and a valid audit.cfg is in place before the security manager starts.