Een Codeless Connector Platform (CCP) data-connector bouwen: deel 2

In deze blogserie laat ik je zien hoe je je eigen Sentinel Codeless Connector Platform (CCP) connector kunt maken. Als je het eerste deel van deze serie nog niet hebt gelezen, zorg er dan voor dat je dat doet: Leer een Codeless Connector Platform (CCP) bouwen. Het zal je enorm helpen om te begrijpen wat we doen en waarom we dingen op deze manier aanpakken. De vorige keer hebben we de API verkend en hebben we geleerd hoe deze omgaat met zaken als authenticatie, de vereiste verzoeken, paginering en welke delen van de respons we nodig hebben. In deze blog gaan we die kennis gebruiken om de Grafische Gebruikersinterface (GUI) van onze CCP-connector op te zetten. Laten we beginnen!

 

Over de Codeless Connector Platform (CCP)

Het Codeless Connector Platform komt in twee varianten: Versie 1 en Versie 2. De V1-variant (ook wel de “legacy” variant genoemd) maakt gebruik van de Data Collector API, die volgend jaar wordt uitgefaseerd. Daarom richten we ons op de V2-versie van de CCP, hoewel deze een stuk lastiger is om mee te beginnen.

Voor de V2 CCP hebben we vier verschillende bestanden nodig:

1. Een connectorDefinition-bestand, waarin onze Grafische Gebruikersinterface (GUI) is gedefinieerd. Dit is de pagina die je ziet wanneer je de connector in het Sentinel connector-tabblad bekijkt.
2. Een connectorPoller-bestand, dat de daadwerkelijke logica bevat voor het ophalen van gegevens uit de API.
3. Een Data Collection Rule-bestand, waarin de transformatielogica is vastgelegd om de loggegevens correct naar de juiste Sentinel-tabel te sturen.
4. Een Tabelbestand, dat de structuur en definitie van de tabel bevat.

In deze blog richten we ons op de connectorDefinition en de connectorPoller, omdat deze de kern vormen van de CCP-connector.

 

Het connectorDefinition-bestand: de GUI

Het connectorDefinition-bestand bevat alles wat zichtbaar is in de GUI. Als je eerder met Sentinel hebt gewerkt, ben je hier waarschijnlijk al bekend mee. Dit omvat alles van de titel en beschrijving van de connector tot de grafieken en ondersteunde gegevenstypen. De GUI is ook de plaats waar de connector gebruikersinvoer kan ontvangen. Dit is essentieel, omdat we bijvoorbeeld de 1Password-basis-URL en API-token van de gebruiker moeten verkrijgen. We moeten dus zorgen voor een invoerveld waarin de gebruiker deze waarden kan opgeven. Laten we beginnen met het eenvoudige deel: het uitklapmenu aan de zijkant van een connector.

 

 

Je ziet een hoop lijnen en kaders, maar daar hoef je niet van te schrikken. Hier is een korte uitleg van de belangrijkste eigenschappen:

• id: De unieke identificatie van je connector. Dit koppelt het connectorDefinition-bestand aan de connectorPoller. Dit ID moet uniek zijn binnen je Sentinel-omgeving.
• title: De titel die op de connectorpagina wordt weergegeven.
• publisher: Geeft aan wie de connector heeft gemaakt.
• descriptionMarkdown: Biedt een beschrijving van je connector. Dit veld ondersteunt Markdown-opmaak.
• graphQueriesTableName: De naam van de tabel waarin de connector gegevens zal opslaan.
• graphQueries: Hiermee kun je een Kusto Query Language (KQL)-query definiëren die op de GUI wordt weergegeven. Dit wordt vaak gebruikt om het aantal ontvangen gebeurtenissen over een bepaalde tijdsperiode te tonen.
• dataTypes: Geeft aan welke gegevenstypen deze connector ondersteunt. Dit bepaalt ook wanneer de statusindicator van de connector op groen (verbonden) of grijs (niet verbonden) wordt gezet.
• connectivityCriteria: Controleert of de connector correct is geconfigureerd en verbinding heeft met de API. Als de API een foutstatuscode teruggeeft (zoals 401 of 403), zal de connector niet als verbonden worden weergegeven.
• availability: Hiermee kun je aangeven of de connector zich in preview bevindt. Dit voegt simpelweg “(preview)” toe achter de titel.

Hieronder vind je mijn versie van de dataConnectorDefinition, wat resulteert in een GUI zoals weergegeven in de bovenstaande afbeelding.

 

 

Neem de tijd om de bovenstaande template zorgvuldig door te nemen en probeer de verschillende eigenschappen te koppelen aan de bijbehorende GUI-componenten. Als je meedoet, experimenteer dan later: probeer de titel, beschrijving of uitgever aan te passen. De bovenstaande code dekt slechts een deel van de GUI: het regelt alleen het uitklapmenu bij het bladeren door dataconnectors in Sentinel. Maar als we de connectorpagina daadwerkelijk openen, komen we op een pagina waar we de gebruiker kunnen begeleiden bij het implementatieproces. Laten we dat gedeelte als volgende aanpakken.

 

Zoals hierboven weergegeven, bevat onze template een eigenschap genaamd “permissions”. Met deze eigenschap kunnen we specificeren aan welke vereisten een gebruiker moet voldoen voordat hij een connector kan implementeren. In ons geval heeft de gebruiker lees- en schrijfrechten nodig voor de werkruimte. Dit kunnen we aangeven door de resourceProvider-sectie in te vullen. Als de gebruiker daadwerkelijk over deze rechten beschikt, verandert het icoon voor de vereiste automatisch in een groen vinkje, wat een handige visuele indicator is. Daarnaast kunnen we ook aangepaste vereisten definiëren. Deze kunnen niet automatisch groen of rood worden weergegeven, omdat Sentinel niet kan verifiëren of aan deze voorwaarden is voldaan. Ze zijn echter een uitstekende plek om aanvullende vereisten te vermelden. Let op dat deze ook Markdown-URL’s ondersteunen, waardoor je eenvoudig naar documentatie kunt linken. Bijvoorbeeld, je kunt een link opnemen naar de handleiding over hoe een API-token aan te vragen.

 

 

Nu komen we bij het belangrijkste aspect van onze GUI: het verstrekken en ontvangen van informatie van en naar de gebruiker. De eigenschap InstructionSteps is een array waarin we stappen kunnen definiëren. Elke stap kan een titel en een beschrijving bevatten (beide ondersteunen Markdown), zodat je de gebruiker kunt begeleiden tijdens het implementatieproces. Je kunt binnen zo’n stap ook de eigenschap instructions opnemen. Ondanks de naam wordt deze eigenschap meer gebruikt om invoer van de gebruiker te verkrijgen dan om instructies te geven. We definiëren hier een Textbox-type instructie, waarmee een tekstvak in de GUI wordt weergegeven.

• label: De titel boven het tekstvak.
• placeholder: De tekst die binnen het tekstvak wordt weergegeven.
• type: Bepaalt hoe de invoer wordt verwerkt: als platte tekst (String) of als beveiligde invoer (SecureString).
• name: Deze eigenschap wordt later in de template gebruikt om de waarden door te geven aan de daadwerkelijke API-implementatie. Onthoud dit goed voor het volgende deel!

Daarnaast hebben we de ConnectionToggleButton. Zoals de naam al aangeeft, voegt dit element een “Verbinden” en “Verbreken”-knop toe. De gebruiker moet op “Verbinden” klikken om de invoer te voltooien en de verbinding daadwerkelijk op te zetten. Zodra deze knop wordt ingedrukt, worden alle ingevoerde gegevens doorgestuurd naar het CCP, waarna het pollingproces start volgens de instructies in het connectorPoller-bestand. Dit bestand gaan we in de volgende blog maken.

Conclusie

In deze blog hebben we onze GUI geconfigureerd. We hebben:

• Gegevenstypen, grafieken en documentatielinks toegevoegd.
• Een veilige methode voor gebruikersinvoer geïmplementeerd.
• Een verbindingsknop toegevoegd waarmee gebruikers hun instellingen kunnen bevestigen en de connector kunnen activeren.

De volledige code voor deze template kun je hier op GitHub vinden.

In het volgende deel gaan we verder met de gebruikersinvoer en deze direct doorsturen naar de dataConnectorPoller-template, waarin we de daadwerkelijke API-aanroep-logica zullen verwerken.

Bedankt voor het lezen, en tot de volgende blog!