Elasticsearch

Configuration of audit providers is performed via modification of the application.conf file:

b2audit {
    elasticsearch {
        host: "localhost"
        port: 9200
        scheme: "http"
    }
}

The above is an example configuration for a localhost elastic instance audit client.

Note

These are default values and do not need to be overridden in the application.conf unless connecting to a foreign host.

Elasticsearch index definition/configuration is performed using JSON files. The inbuild REST request audit service uses a file called es-resourcerequests.json to define mappings:

{
    "mappings": {
        "@@INDEX_TYPE@@": {
            "_all": { "enabled": false },
            "properties": {
                "class": {
                    "type": "text",
                    "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                },
                "duration": { "type": "integer" },
                "status": { "type": "integer" },
                "email": {
                    "type": "text",
                    "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                },
                "httpMethod": {
                    "type": "text",
                    "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                },
                "method": {
                    "type": "text",
                    "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                },
                "package": {
                    "type": "text",
                    "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                },
                "path": {
                    "type": "text",
                    "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                },
                "timestamp": {
                    "type": "date",
                    "format": "YYYY-MM-dd HH:mm:ss.SSSZ"
                },
                "queryParams": {
                    "type": "nested",
                    "properties": {
                        "name": {
                            "type": "text",
                            "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                        },
                        "values": {
                            "type": "text",
                            "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                        }
                    }
                },
                "pathParams": {
                    "type": "nested",
                    "properties": {
                        "name": {
                            "type": "text",
                            "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                        },
                        "values": {
                            "type": "text",
                            "fields": { "keyword": { "type": "keyword", "ignore_above": 256 } }
                        }
                    }
                }
            }
        }
    }
}

To override this file, simply place a modified copy in $B2BOX_DATA/conf.

Index names

The index names generated by Platform 6 have a strict format:

b2-<user index name>--<b2box application id>

For example:

b2-resourcerequests--simont-test or b2-myindex--simont-test

Kibana can then be used to view and search the index data generated:

Specifying audit trail structure via JSON

A named Elasticsearch index will be created using a JSON definition file when the following Groovy method is called: audit.open(id).

If the index already exists, index updates are not performed. The current definition is left unchanged.

The JSON file searched for has the pattern: es-<id>.json. The file should be placed on the classpath in $B2BOX_DATA/conf.

The following is an example index mapping file:

{
    "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" }
                    }
                }
            }
        }
    }
}

Note

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 define structure using the file es-myindex.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 it’s existence.

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

Using Kibana you will see the audit data written: