Alerts (planned)

Planned. Self-hosted deployment is not available yet. This page describes how alerts will work in it.

Alerts tell your people when a finding needs attention. They are rules in the app: when a finding of a chosen severity appears, send it somewhere. See Findings.

Email

Works the same as on the hosted service, through your mail relay. Set up Email first. A rule can send to named addresses, or to the owner of the agent a finding is about.

Webhooks

A webhook posts the alert, signed so the receiver can check it came from your deployment, to an HTTPS address. Use it for chat tools, ticket systems and your own services.

The default, and how you change it. By default the platform refuses to send webhooks, or make any outbound call on a user's behalf, to private network addresses (10.x, 172.16-31.x, 192.168.x and similar). That is the right default for a shared hosted service, where it stops one customer aiming the platform at internal services. Inside your own network your chat tool, ticket system and identity provider are on private addresses, so a self-hosted install has an internal allow-list: you name exactly what the platform may reach, and everything else stays refused.

Set it in the settings file and restart the service:

LEDGER_INTERNAL_HOSTS=chat.corp.example.com,*.tickets.corp.example.com,10.40.0.0/16,10.60.0.7
Entry Meaning
chat.corp.example.com that host name, wherever it resolves
*.tickets.corp.example.com any host under that name
10.60.0.7 that single IPv4 address
10.40.0.0/16 that IPv4 range (no broader than /8)

Rules it keeps:

  • Default deny. Unset, nothing private is reachable.
  • An entry opens only what it names. One host does not open its neighbours, and one range does not open the rest of the network.
  • Some addresses can never be allowed, however they are listed: the cloud instance-metadata range (169.254.0.0/16), 0.0.0.0/8, and multicast. A name that resolves there is refused even if it is listed.
  • A typo fails loudly. An entry the service cannot read, or a range broader than /8, stops the service from starting instead of opening the network.
  • The same list covers the identity provider (see Sign-in and SSO), not only webhooks.

The list is read at start, from the settings file. A settings screen with a reason recorded for each entry is planned.

Setting up an alert

  1. Open Findings and find the Alerts card.
  2. Add a rule: a destination (an email address, the owner of the agent a finding is about, or a webhook), a minimum severity, and optionally quiet hours and a daily digest.
  3. For a webhook, use an HTTPS address, and verify the signature in your receiver.

A message carries the finding kind, severity, subject and a link, never record content. Each finding sends once per rule and event. The delivery log under the card records every send, and a failed delivery says why (the address was refused, the receiver returned an error, or it timed out), so nothing is dropped silently.

If a webhook fails

The delivery log names the reason. The usual ones for a self-hosted install:

  • The address was refused as a private address. Add the host or range to LEDGER_INTERNAL_HOSTS and restart.
  • The certificate is not trusted. The receiver uses a certificate from your own authority: add the authority to the machine's trust store.
  • The receiver rejects the message. Check the signature code in your receiver; the signing secret is the one shown when the rule was created.