Audit trail records

Purpose

Configure and write audit trail records to a configured Big Data channel.

Methods

Binding name: audit

---

Method: boolean open(String id, String schemaUri)

Creates or checks for the existence of the audit channel with the given id.

Once the named audit channel has been created this method no longer needs to be called. The schemaUri must point to a local file (e.g. protocol file: only), a JSON formatted file that describes the structure of the audit record.

Returns true if channel already exists or creation was successful

---

Method: void post(String id, Map values)

Posts an audit record to the named audit channel using the supplied values.

The id must be the name of a previously opened audit channel. The values map is a map of String keys with either String values or lists of other values map (in the case of nested audit record).

---

Method: void post(String id, String values)

Posts an audit record to the named audit channel using the supplied values String.

The id must be the name of a previously opened audit channel. The values map is a String formatted appropriately for the auditing provider. For example: JSON for ELASTICSEARCH

Details

Supported auditing providers:

• GCE_BIGQUERY Google Compute Engine Big Query
• LOG4J log4j
• ELASTICSEARCH Elasticsearch from Elastic

The provider is specified in the Platform 6 application.conf file.

b2audit attributes are also specified in the application.conf and vary depending upon the chosen provider.

audit {
    provider=ELASTICSEARCH
}

b2audit {
    elasticsearch {
        host: "log.amalto.com"
        port: 9200
        scheme: "http"
    }
}

audit {
    provider=GCE_BIGQUERY
}

b2audit {
    gce {
        projectId: "<gce project id>"
        clientId: "<gce client id>"
        clientKey: "<gce client key>"
        datasetId: "b2audit"
    }
}

Application identifier

Both Google BigQuery and Elastic Search can be shared by multiple instances of Platform 6. Therefore the Platform 6 application_id is used to extend and uniquely name each audit trail.

For more details see Audit Provider documentation: Audit Providers.

Examples

JSON is used to define the structure (schema) of an audit trail. The syntax differs depending upon the audit provider type:

GCE_BIGQUERY: myindex.json

[
    {
        "name": "company",
        "type": "STRING",
        "mode": "REQUIRED",
        "nested": []
    }, 
    {
        "name": "amount",
        "type": "FLOAT",
        "mode": "NULLABLE",
        "nested": []
    }, 
    {
        "name": "taxes",
        "type": "RECORD",
        "mode": "REPEATED",
        "nested": [
            {
                "name": "salestax",
                "type": "FLOAT",
                "mode": "NULLABLE",
                "nested": []
            },
            {
                "name": "taxrate",
                "type": "FLOAT",
                "mode": "NULLABLE",
                "nested": []
            }
        ]
    }
]

Supported schema modes:

• REQUIRED
• REPEATED

Supported schema field types:

• STRING
• INTEGER
• FLOAT
• BOOLEAN
• TIMESTAMP
• RECORD

ELASTICSEARCH: es-myindex.json

{
  "mappings": {
    "myindex": {
      "_all": {
        "enabled": false
      },
      "properties": {
        "timestamp": {
          "type": "date",
          "format": "YYYY-MM-dd HH:mm:ss.SSSZ"
        },
        "company": {
          "type": "text",
          "fields":{"keyword":{"type":"keyword","ignore_above":256}}
        },
        "amount": {
          "type": "float"
        },
        "taxes": {
          "type": "nested",
          "properties": {
            "salestax": {
              "type": "float"
            },
            "taxrate": {
              "type": "float"
            }
          }
        }
      }
    }
  }
}

Elasticsearch Schema

The Platform 6 audit trail client auto-generates a timestamp value. So it is advisable to add a mapping definition.

This is an example Groovy script which created the defined structure using JSON.

def success = audit.open("myindex")
println success

Writing to an audit trail

Writing (posting) to an audit trail is simple in Groovy.

def auditValues = [:]
auditValues["company"] = "Amalto"
auditValues["amount"] = 101.12

audit.post "myindex", auditValues

Note

Once an audit trail table has been created there is no need to use the ‘open’ method again… unless you need to validate its existence.

Writing to a nested audit trail

Writing to a nested RECORD is more tricky.

def auditValues = [:]

def taxValues = []

def taxValue1 = [:]
taxValue1["salestax"] = 12.35
taxValue1["taxrate"] = 10
taxValues.push(taxValue1)

def taxValue2 = [:]
taxValue2["salestax"] = 123.45
taxValue2["taxrate"] = 100
taxValues.push(taxValue2)

auditValues["taxes"] = taxValues
auditValues["company"] = "Amalto"
auditValues["amount"] = 123.45
audit.post "myindex", auditValues