This is a simple script that demonstrates how to interact with handle-event.sh
.
When you call handle-event.sh
you are required to pass it a handler script that
will be called each time the event occurs. A generic handler script is provided
in this sample and is described below.
A simple way to see this sample in action is to run sample-event-listener.sh
from this directory:
$ ./sample-event-listener.sh -E UserUpdated
Then, log into Safeguard via the UI and change the description of a user.
The output will look like this:
{
"DirectoryId": null,
"DirectoryName": null,
"DomainName": null,
"UserId": 30,
"UserIdentityProviderId": -1,
"UserIdentityProviderName": "Local",
"UserName": "BlueAutomation",
"UserPrimaryAuthenticationIdentity": "70E45112BC03447AD96DCDA019C34E3F82BDCB35",
"UserPrimaryAuthenticationProviderId": -2,
"UserPrimaryAuthenticationProviderName": "Certificate",
"EventName": "UserUpdated",
"EventDescription": "A user has been updated",
"EventTimestamp": "2019-06-18T17:08:52.4472318Z",
"ApplianceId": "18B1694CF1C0",
"EventUserId": 29,
"EventUserDisplayName": "Guber Admin",
"EventUserDomainName": null
}
UserId
is the ID of the user that was updated. EventUserId
is the ID of the
user that made the change. Some basic information is included in the event itself
but the UserId
can be used to pull the full information about the user that
recently changed.
Different types of events have different information. Sometimes the information included in the event itself will be sufficient for what you are trying to do. Other times you will want to query Safeguard in the event handler script for more information before reacting to the event.
As demonstrated in sample-event-listener.sh
, when you call handle-event.sh
the -S
option allows you to pass in a handler script. This script will be called
every time the event with the name you passed to the -E
option occurs.
In order for you to do something useful with the event, handle-event.sh
passes
the current authentication context information to the handler script. This allows
your handler script to call back to Safeguard if necessary to react to the event.
The handler script can make an authenticated request to Safeguard using the
current access token.
For security reasons, the handler script is passed the authentication context information over stdin. This prevents the access token from ending up in the process table as a command line argument. Each time the script is called for an event it can expect to receive four lines of output.
- Line 1 has the appliance network address
- Line 2 has the access token currently in use.
- Line 3 has the path to the CA bundle file to use for trusted connections
- Line 4 has the event data JSON minified to a single line of output
The generic-event-handler.sh
shows how to parse this data from stdin without
causing a potential hang via the bash read builtin.
When calling invoke-safeguard-method.sh
from the handler script, the best
practice is to use the -T
option to hide the access token from the process
table.
For example:
invoke-safeguard-method.sh -a $Appliance -B $CABundle -T ... <<<$AccessToken
Where, the ...
is replaced with whatever command you would like to send.
Your handler script is not limited to calling invoke-safeguard-method.sh
one
time. It may call Safeguard as many times as is necessary to accomplish whatever
you'd like to do to react to the event.