Integrations

The integration templates make a livewells run for each link in an incident. They post the Start link to your analysts.

There is one template for Microsoft Sentinel and one for Tines. The templates are starting points. Test them on your own tenant before you rely on them.

Get the files

Sign in to livewells, then open one of these addresses and save the file.

• https://app.livewells.io/integrations/livewells-playbook.json is the template for Microsoft Sentinel.
• https://app.livewells.io/integrations/livewells-story.json is the story for Tines.

A person who is not signed in cannot open these addresses.

How a template works

1. The template reads the links of an incident.
2. The template sends each link to POST /v1/runs. See API.
3. livewells answers with a Start link.
4. The template posts the Start link to your analysts.

A run for a link waits for an analyst. The analyst opens the Start link, signs in and starts the browser.

A template shows each link defanged in its note. A link that holds markup or a mention shows as plain text. A template sends at most 5 links for each incident.

Choose the incidents

Each link counts as one run when livewells makes it, even when no analyst starts it.

A run that no analyst starts holds one of the 25 places of the key for up to 24 hours.

Limit the automation rule in Microsoft Sentinel, or the webhook in Tines, to the incidents that need an analyst. An example is an incident of medium severity or higher.

The API key

Make a key in Settings with the access level "Read and send links and files". See Administering livewells.

Set an expiry date and IP ranges on the key. Keep the key in a secret store: a key vault for Microsoft Sentinel, a credential for Tines. A template file holds no key.

Microsoft Sentinel

The file livewells-playbook.json is an Azure deployment template. It makes a Logic App and a Microsoft Sentinel connection.

The Logic App starts when an incident is created. Add an automation rule in Microsoft Sentinel that runs the playbook for new incidents.

The playbook reads the key from your key vault. It signs in to the key vault and to Microsoft Sentinel with its managed identity.

The playbook adds a comment with the Start link to the incident.

Tines

The file livewells-story.json is a Tines story. The story starts when its webhook receives a JSON body with incident_id and urls.

Add the key to a Tines credential named livewells_runs_key. Add the address that your analysts read to a credential named livewells_analyst_webhook. The story posts the Start link to that address.

The webhook is disabled when you import the story. Set a webhook secret, then enable the webhook.

Waits and limits

The Microsoft Sentinel playbook sends a request again when livewells answers 409, 429, 408 or a 5xx status. The Tines story sends a request again on 409, on 429 and on a 5xx status. A repeated request uses the same Idempotency-Key, so livewells makes one run.

The answer 409 means that the first request with the same Idempotency-Key still runs. The template waits and sends the request again.

When the answer holds a Retry-After header, the template waits that many seconds. Without the header, the Microsoft Sentinel playbook waits 15 seconds and doubles the wait after each try. No wait is longer than 900 seconds.

The Microsoft Sentinel playbook tries 6 times for one link, unless you set the template parameter maxAttempts. The Tines story tries 4 times for one link.

An organisation can hold 100 waiting runs, and a key can hold 25. At a limit, livewells answers 429 with the error too-many-awaiting-runs and no Retry-After header. The template waits as it does for any other 429 and sends the request again. After its last try, the template posts a note that asks your analysts to start the waiting runs or let them expire.

When the monthly limit is used, livewells answers 429 with the error run-limit. The template posts a note and does not send the request again.

When livewells refuses the key, the template posts a note for each link and sends no other request for that link. The note shows the status of the latest answer.