# Kanalen

Kanalen bepalen waar de meldingen van een project heen gaan: naar e-mailadressen, je eigen webhook-endpoint, Slack, Discord of Microsoft Teams. Een project kan meerdere kanalen hebben, elk met eigen filters en een eigen manier van versturen. Open het project, dan **Kanalen** en **Kanaal toevoegen**.

Een kanaal hoort bij één project en krijgt alleen de meldingen van dat project: de software, de watches, de sites en de CVE-regels ervan. Wil je de meldingen van meerdere projecten op één plek, zie dan [Meerdere projecten op één plek](#projects).

## Soorten kanalen

| Kanaal          | Zo koppel je het                                    | Abonnement |
| --------------- | --------------------------------------------------- | ---------- |
| E-mail          | Voeg adressen toe, elk adres bevestigt eerst        | Betaald    |
| Webhook         | Je eigen HTTPS-URL, geverifieerd met een challenge  | Alle       |
| Slack           | Kies een kanaal in het toestemmingsscherm van Slack | Alle       |
| Discord         | Plak de URL van een Discord-webhook                 | Alle       |
| Microsoft Teams | Plak de URL van een Teams-workflow                  | Alle       |

Elk kanaal krijgt dezelfde meldingen, behalve Discord op het Free-abonnement, dat alleen meldingen van CVE-regels krijgt. E-mail en chat-apps krijgen een leesbaar bericht, webhooks de ondertekende JSON uit [Events en payloads](https://ladon.hackindex.io/nl/docs/events.md).

## E-mail

E-mailkanalen horen bij de betaalde abonnementen. Voeg een of meer e-mailadressen toe. Elke ontvanger krijgt eerst een bevestigingsmail met een link die 7 dagen geldig is, en krijgt pas meldingen na het bevestigen. Elke meldingsmail heeft een afmeldlink die met één klik werkt, ook vanuit mailprogramma's die one-click afmelden ondersteunen.

Meldingsmails gebruiken de taal van het kanaal, zie [Taal](#taal).

## Webhooks

Ladon stuurt elke melding als ondertekende JSON naar een URL die je kiest. De URL moet:

- `https` gebruiken, op poort 443 of 8443;
- een hostnaam gebruiken, geen IP-adres;
- alleen naar openbare IP-adressen wijzen. Ladon controleert elk adres en stuurt nooit naar privé- of interne netwerken.

Bij het toevoegen stuurt Ladon eerst een challenge om te bewijzen dat het endpoint van jou is. Je krijgt ook het signing secret, dat maar één keer wordt getoond. Alles over de requests, handtekeningen en retries staat in [Webhooks](https://ladon.hackindex.io/nl/docs/webhooks.md).

## Slack

Kies **Slack** als je een kanaal toevoegt en ga verder naar Slack. Slack vraagt in welke workspace en welk kanaal Ladon mag posten. Ladon vraagt alleen toestemming om in dat ene kanaal te posten en kan niets in je workspace lezen.

Berichten tonen de ernst met een gekleurde stip, de software en titel, de CVE en opgeloste versies, een knop om de melding in Ladon te openen, en de bron met de copyrightvermelding. Wil je later in een ander kanaal posten, gebruik dan **Kanaal koppelen** op de kanaalpagina.

Wordt de Slack-app verwijderd of het kanaal gearchiveerd, dan meldt Slack dat de webhook niet meer bestaat. Ladon zet het kanaal dan uit en mailt de owners en admins.

## Discord

Discord werkt op elk abonnement, ook op Free, dus je kunt een feed van kritieke kwetsbaarheden in een community-server draaien. Op Free krijgt een Discord-kanaal alleen meldingen van [CVE-regels](https://ladon.hackindex.io/nl/docs/cve-rules.md), niet de software die je project volgt: maak het kanaal aan en koppel het daarna aan een CVE-regel van hetzelfde project. Vanaf Pro krijgt het ook de meldingen van je watches, en kies je welke meldingen, welke ernst en wanneer, net als bij elk ander kanaal. Zonder white-label-abonnement houdt elk bericht zijn link **Openen in Ladon**.

Open in Discord de instellingen van het kanaal, dan **Integraties**, **Webhooks**, **Nieuwe webhook** en **Webhook-URL kopiëren**. Plak de URL in Ladon. Die begint met `https://discord.com/api/webhooks/`.

Berichten zijn embeds met een kleur per ernst. Mentions staan uit, dus tekst uit de titel van een kwetsbaarheid kan nooit iemand op je server pingen. Is het een forumkanaal, vink dan **Dit is een forumkanaal** aan: elke melding start dan een nieuwe post.

Wordt de webhook in Discord verwijderd, dan zet Ladon het kanaal uit na het eerste antwoord dat dat meldt.

## Microsoft Teams

Open in Teams het menu van het kanaal, kies **Workflows** en de sjabloon **Send webhook alerts to a channel**. Aan het eind toont Teams een URL, plak die in Ladon. Die bevat `environment.api.powerplatform.com`.

Berichten zijn Adaptive Cards met dezelfde details en een knop om de melding in Ladon te openen.

Een workflow hoort bij de persoon die hem maakte. Wordt diens account verwijderd, dan stopt de workflow en zet Ladon het kanaal uit. Laat hem maken door iemand die blijft, of door een serviceaccount.

Ladon accepteert in deze kanalen alleen webhook-URL's van Slack, Discord en Microsoft Teams, en slaat ze versleuteld op. Ze werken als een wachtwoord, dus Ladon toont ze na het opslaan nooit meer.

## Wanneer meldingen gaan

- **Direct**: elke melding gaat de deur uit zodra hij er is. Stel eventueel **Maximaal per uur** in. Boven dat aantal worden meldingen tot het eind van het uur gebundeld in één bericht. Kritieke meldingen gaan altijd direct.
- **Gebundeld**: meldingen die kort na elkaar komen, gaan als één bericht. De eerste melding start een wachttijd van 5, 15 of 60 minuten, alles wat in die tijd binnenkomt gaat mee.
- **Samenvatting**: alle meldingen in één bericht op een vast moment: elk uur, elke dag op een tijd die je kiest, of elke week op een dag en tijd die je kiest, in jouw tijdzone. Lange samenvattingen worden verdeeld over berichten van maximaal 100 events.

Bij gebundeld versturen of een samenvatting kun je **Kritieke meldingen direct versturen** aanvinken, zodat een kritieke kwetsbaarheid nooit wacht.

Het gratis abonnement heeft direct en de dagelijkse samenvatting. Gebundeld versturen, samenvattingen per uur of week en kritieke meldingen direct versturen horen bij de betaalde abonnementen. Gaan er veel meldingen tegelijk uit, dan gaan betaalde abonnementen voor.

## Taal

Elk kanaal heeft een eigen taal, Engels of Nederlands, voor zijn mails, chatberichten, samenvattingen en tests. Een nieuw kanaal begint in de taal van wie het toevoegt, ook via de API, waar dat de taal van het HackIndex-account van de eigenaar van het token is. Wijzig het onder **Bewerken**, of met `locale` in de API. Een team heeft zelf geen taal, dus één team kan een Engels kanaal voor een klant hebben en een Nederlands kanaal voor zichzelf.

De JSON van een webhook heeft geen taal. Alleen de `data.message` van een test en de `reasons` van een [CVE-regel](https://ladon.hackindex.io/nl/docs/cve-rules.md) volgen het kanaal.

## Opmaak {#appearance}

Vanaf Pro kies je wat een bericht in Slack, Discord, Microsoft Teams of een mail laat zien, onder **Bewerken** en dan **Opmaak**. Het formulier toont een voorbeeld van een kritieke melding terwijl je het aanpast.

- **Details**: laat de ernst, het CVE-nummer, de opgeloste versie, de projecten die het installeren, wat er veranderde, of de details en redenen van [CVE-regels](https://ladon.hackindex.io/nl/docs/cve-rules.md) weg. De link naar de bron en de vermeldingen van de gegevens blijven altijd staan, hun licentie vraagt erom.
- **Indeling**: met details, of compact: alleen de titel, de ernst en de links.
- **Tekst voor elke titel**, zoals `[Acme]`, maximaal 30 tekens. Samenvattingen krijgen hem ook.
- **Kleur van de lijn** in Discord: per ernst, of één eigen kleur.
- **Mentions** bij kritieke meldingen, of bij kritieke en hoge: in Discord een rol, een persoon of `@here`, in Slack `@here`, `@channel` of een gebruikersgroep. Kopieer het ID van een Discord-rol of -persoon met de ontwikkelaarsmodus aan, het ID van een Slack-gebruikersgroep begint met `S`.

In de API heet dit `appearance`, met `hidden`, `layout`, `prefix`, `mentions` (zoals `role:123`, `user:123`, `here`, `channel` of `group:S0123ABCDE`), `mention_from` (`critical` of `high`) en `color` (zoals `#15803d`, of `null` per ernst). Na een overstap naar Free blijft het kanaal werken met de standaardopmaak, en je keuzes komen terug na een upgrade. Webhooks krijgen altijd de volledige JSON.

## White-label {#white-label}

Vanaf Business kunnen meldingen jouw huisstijl dragen in plaats van die van Ladon. Stel die één keer per team in op het tabblad **Huisstijl** van het team: een naam, een logo, een kleur, een voettekst en een antwoordadres. Elk kanaal van elk project van het team kan hem gebruiken. Zet hem per kanaal aan met **Gebruik de huisstijl van het team** onder **Opmaak**.

| Kanaal          | Wat er verandert                                                                                                                                                                                                 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Discord         | Jouw naam en logo als afzender, jouw kleur bij berichten zonder ernst                                                                                                                                            |
| Slack           | Jouw logo en naam bovenaan het bericht. De afzender blijft de app van Ladon, zo wil Slack het. Wil je ook de afzender wijzigen, maak dan een eigen Slack-app met een incoming webhook en plak die URL als kanaal |
| Microsoft Teams | Jouw logo en naam bovenaan de kaart. De afzender is al de persoon die de workflow maakte                                                                                                                         |
| E-mail          | Jouw naam als afzender, jouw logo bovenaan, jouw voettekst en, na bevestiging, jouw antwoordadres. Het adres blijft van ons, zodat de mail aankomt                                                               |

De vermeldingen en links van de bronnen blijven altijd staan, hun licenties vragen erom, en elke mail meldt onderaan dat hij via HackIndex Ladon is verstuurd. Een nieuw antwoordadres telt pas als de eigenaar het via een link bevestigt. Na een overstap naar een lager abonnement blijft de huisstijl bewaard en gaan kanalen terug naar de opmaak van Ladon, een upgrade brengt hem terug.

## Link naar Ladon {#link-to-ladon}

Chatberichten en mails linken met **Openen in Ladon** naar de melding in Ladon. Die link weghalen hoort bij white-label (Business en hoger): zet **Toon Openen in Ladon** uit onder **Bewerken**, of stuur `link_to_ladon: false` via de API. Zonder dat abonnement blijft de link altijd staan, zo blijft een gratis Discord-feed terugwijzen naar Ladon. Staat de link uit, dan linkt de melding alleen naar de bron, en de vermeldingen en de link naar de licenties blijven staan. Webhooks hebben de links altijd in hun JSON.

## Filters per kanaal

Het kanaal bepaalt welke meldingen het verstuurt: met eigen soorten events, een eigen ernstfilter en een eigen [tagfilter](#tags). De software van een project kiest dat niet, dus de lockfiles, de software die je zelf toevoegde en de gewone software van een project bereiken elk kanaal waarvan de filters de melding doorlaten. Stuur bijvoorbeeld alles naar een ticketsysteem en alleen kritieke meldingen naar het adres van wie dienst heeft.

Een watch die je zelf maakte of via de API aanmaakte, houdt zijn eigen soorten events en ernstfilter, bovenop die van het kanaal. Een melding van zo'n watch komt alleen aan als beide hem doorlaten.

Een melding over een kwetsbaarheid gaat alleen naar de kanalen van een project als dat project een getroffen versie installeert. Een project op een opgeloste versie blijft stil, ook als een ander project van het team dezelfde software draait. Software die je zelf aan een project toevoegde, telt voor de versies die je koos.

[CVE-regels](https://ladon.hackindex.io/nl/docs/cve-rules.md) zijn de uitzondering: een regel noemt zijn eigen kanalen en zijn voorwaarden bepalen wat er uitgaat, dus deze filters gelden daar niet.

## Routeren op tag {#tags}

Geef een kanaal een tagfilter en het krijgt alleen de meldingen van watches met minstens één van die tags. Laat het leeg en het kanaal krijgt de meldingen van elke watch van het project. Stuur bijvoorbeeld alles over `production` naar het Slack-kanaal van wie dienst heeft, en alles naar je eigen ticketsysteem.

Tags stel je per watch en per project in, zie [Software volgen](https://ladon.hackindex.io/nl/docs/watches.md#tags). Een watch zonder tags bereikt alleen kanalen zonder tagfilter.

## Meerdere projecten op één plek {#projects}

Een kanaal hoort alleen over zijn eigen project. Wil je de meldingen van meerdere projecten in hetzelfde Slack-kanaal, dezelfde inbox of hetzelfde endpoint, voeg dan in elk van die projecten een kanaal toe met hetzelfde adres. Elk kanaal houdt zijn eigen filters, dus het ene project stuurt alles en het andere alleen kritieke meldingen. Elk van die kanalen telt mee voor de kanalen in je abonnement.

Teams die al kanalen hadden voordat er projecten waren, zijn voor je overgezet. Een kanaal dat over meerdere of alle projecten hoorde, kreeg een kopie in elk van die projecten, met hetzelfde adres, dezelfde ontvangers en dezelfde instellingen. Die kopieën nemen geen extra plek in je abonnement in.

## Testen

Gebruik **Test sturen** op de kanaalpagina om een `ping`-bericht te sturen. Je kunt maximaal 5 tests per minuut sturen.

## Bezorglog

De kanaalpagina laat de laatste 50 pogingen zien: wanneer, hoe lang het duurde, de statuscode en het begin van het antwoord. Hoe lang Ladon dit log bewaart, hangt af van je abonnement, zie [Abonnementen en limieten](https://ladon.hackindex.io/nl/docs/plans-and-limits.md).

## Als bezorgen mislukt

Ladon probeert een mislukte bezorging ongeveer drie dagen opnieuw. Na de derde mislukte poging krijgen de owners en admins van het team een mail. Mislukt elke bezorging vijf dagen lang, of antwoordt het endpoint `410 Gone`, dan zet Ladon het kanaal uit en laat dat weten. Slack-, Discord- en Teams-kanalen gaan ook uit zodra de app antwoordt dat de webhook niet meer bestaat. Herstel het endpoint en zet het kanaal weer aan op de kanaalpagina.

### Opnieuw versturen {#send-again}

Staat het kanaal weer aan, dan stuurt **Opnieuw versturen** op de kanaalpagina elke melding die mislukte of werd opgegeven sinds een moment dat je kiest, tot 30 dagen terug. Tests blijven buiten beschouwing. De meldingen gaan binnen een minuut de deur uit, in hun oorspronkelijke vorm, en het bezorglog laat zien hoe het ging. Owners en admins kunnen dit, via de API is het `POST /endpoints/{id}/recover`.

Je kunt een kanaal ook zelf pauzeren. Een gepauzeerd kanaal ontvangt niets, en meldingen uit die tijd worden niet later nagestuurd.

## Wie kanalen beheert

Owners en admins van een team kunnen de kanalen van elk project van het team toevoegen, wijzigen en verwijderen, en de huisstijl instellen. Members zien de meldingen van een project, maar niet de kanalen ervan. Zie [Teams en beveiliging](https://ladon.hackindex.io/nl/docs/teams-and-security.md).

Een project verwijderen haalt ook de kanalen ervan weg.
