Oplossingen voor aangepast grafiekplatform ontwikkelen

Opmerking

Deze functie is momenteel beschikbaar als preview-versie. Zie aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews.

Een Microsoft Sentinel aangepaste grafiekoplossing is een oplossing op basis van notebooks waarmee knooppunten en randen van Microsoft Sentinel Data Lake-tabellen worden gedefinieerd, een grafiek wordt gemaakt en gebruikers die grafiek kunnen doorzoeken met Graph Query Language (GQL).

Gebruik deze handleiding voor het bouwen, testen, materialiseren, verpakken en publiceren van een aangepaste grafiekoplossing als een SaaS-aanbieding in Microsoft Partnercentrum, zodat klanten deze kunnen ontdekken in Microsoft Beveiliging Store.

Prerequisites

U moet zijn aangesloten op de data lake om Custom Graph-oplossingen te creëren. Zie Onboarding voor de Microsoft Sentinel data lake voor meer informatie.

Permissions

De volgende tabel bevat de vereiste machtigingen voor elke bewerking of elk bereik in deze handleiding.

Operation	Vereiste rol
Aan de slag met de Sentinel data lake	Microsoft Entra ID - Beveiligingsbeheerder of globale beheerder
Sentinel-werkruimte integreren in de Defender-portal	Abonnementseigenaar, of Beheerder voor gebruikerstoegang op abonnementsniveau en Microsoft Sentinel-bijdrager op abonnements- of resourcegroepniveau
Sentinel-workspace koppelen aan data lake	Abonnementseigenaar of Microsoft Sentinel-inzender op het niveau van het abonnement of de resourcegroep
Een notebookgrafiek modelleren en bouwen	Aangepaste uniforme Microsoft Defender XDR RBAC-rol met `data (manage)` machtiging voor de Microsoft Sentinel-gegevensverzameling
Een grafiek behouden (materialiseren)	Beveiligingsoperator, beveiligingsbeheerder of globale beheerder
Een query uitvoeren op een persistente grafiek	Aangepaste Microsoft Defender XDR-geïntegreerde RBAC-rol voor de gegevensverzameling van Microsoft Sentinel met `security data basics (read)`
De aangepaste Graph-oplossing publiceren	Marketplace-Publisher-account op Microsoft Partnercentrum

Tools

De volgende hulpprogramma's zijn vereist voor het bouwen en publiceren van een aangepaste grafiekoplossing:

Visual Studio Code.
Microsoft Sentinel extensie voor Visual Studio Code. Voor meer informatie, zie Install Visual Studio Code en de Microsoft Sentinel-extensie.
Jupyter-extensie voor Visual Studio Code.
GitHub Copilot uitbreiding en een GitHub Copilot Business- of Enterprise-abonnement.
Python 3.10 of hoger op uw lokale computer.

Tip

Gebruik een bestaande data lake opnieuw als uw tenant al is ingericht voor KQL-query's, notebooks of een Security Copilot-agent. Er is één data lake voor elke tenant. Ga in de Defender-portal naarSysteeminstellingen>>Microsoft Sentinel>Data lake. Als de status Ingericht is, sla taak 1 over.

Werkstroom bouwen

De volgende werkstroom bevat een overzicht van de stappen voor het bouwen en publiceren van een aangepaste grafiekoplossing.

Voorbeeldgegevens opnemen in de tabellen die uw grafiekmodellen bevatten.
Valideer de connectiviteit met een eenvoudig notebook.
Ontwerp de aangepaste grafiek.
Test het grafieknotitieblok.
Plan een grafiektaak om de grafiek te materialiseren.
Query's uitvoeren en de grafiek visualiseren vanuit Graph Explorer.
De aangepaste grafiekoplossing verpakken en publiceren.

Voorbeeldgegevens opnemen

Deze taak neemt Microsoft Entra ID assettabellen op die worden gebruikt door de voorbeeldgrafiek in deze handleiding: EntraUsers, EntraGroups, EntraServicePrincipalsen EntraMembers.

Ga in de Defender-portal naarSysteeminstellingen>>Microsoft Sentinel>Data-connectors.
Schakel de Microsoft Entra ID-connector in, zodat Entra-assettabellen worden opgenomen in de Data Lake. Voor meer informatie, zie Asset data in Microsoft Sentinel data lake.
Controleer of deze tabellen worden weergegeven in Data Lake Explorer:
- EntraUsers
- EntraGroups
- EntraServicePrincipals
- EntraMembers
Deze tabellen komen terecht in de werkruimte Systeemtabellen .
Optioneel: neem andere connectors op en vervang tabelnamen in latere stappen als in uw scenario verschillende gegevens worden gebruikt.

Opmerking

Als een tabel niet wordt weergegeven in Data Lake Explorer, kunt u deze niet gebruiken voor het ontwerpen van grafieken en wordt er niet naar ai-hulp verwezen.

Connectiviteit valideren met een eenvoudig notebook

Maak en voer een minimaal notebook uit om data lake-connectiviteit te controleren voordat u grafiek ontwerpt.

Open Visual Studio Code en meld u aan bij de Microsoft Sentinel-extensie met hetzelfde account dat toegang heeft tot de data lake.
Selecteer in Visual Studio Code onder Sentinel Extension–Graphs de optie Nieuw notitieblok maken.
Sla de notebook op, bijvoorbeeld hello-world-show-tables.ipynb.
Selecteer Selecteer kernel, selecteer Microsoft Sentinel en selecteer een beschikbare Spark-pool.
Voeg de volgende cellen in volgorde toe.

Cel 1 - Markdown:

# Hello World: Show Tables
A minimal connectivity test for the Microsoft Sentinel data lake.
If every cell below runs without error, your environment is ready
to author custom graphs.
Steps:
1. Connect to the data lake with the Microsoft Sentinel provider
2. Point at your workspace
3. Read a table and show a few rows

Cel 2- Code (verbinding maken en uw werkruimte instellen):

from sentinel_lake.providers import MicrosoftSentinelProvider
# The provider gives the notebook access to data lake tables.
lake_provider = MicrosoftSentinelProvider(spark=spark)
# >>> ADD YOUR WORKSPACE HERE <<<
# Replace with the Log Analytics workspace that holds your tables.
# Entra asset tables (EntraUsers, EntraGroups, ...) live in "System tables".
LOG_ANALYTICS_WORKSPACE = "System tables"
print(f"Using workspace: {LOG_ANALYTICS_WORKSPACE}")

Cel 3 - Markdown:

## Read a table and show rows
Reading a known table is the fastest way to confirm the extension
can reach the lake with your permissions. Swap EntraGroups for any
table that exists in your workspace.

Cel 4- Code (een tabel lezen en rijen weergeven):

# Read a table from the data lake into a Spark DataFrame.
df_groups = lake_provider.read_table("EntraGroups", LOG_ANALYTICS_WORKSPACE)
# Show a sample. .df exposes the underlying Spark DataFrame.
df_groups.df.select("id", "displayName", "mailEnabled").show(20, truncate=False)

Cel 5- Code (optionele saniteitsaantallen):

# Confirm the read returned data and inspect the schema.
print("Row count:", df_groups.df.count())
df_groups.df.printSchema()

Voer alle cellen van boven naar beneden uit.
Controleer of elke cel is voltooid zonder een rode tracering, de voorbeeldgegevens van een tabel worden weergegeven en het aantal rijen is niet nul.

Opmerking

Als leesacties mislukken of geen rijen retourneren, controleer dan of de connector uit de sectie Voorbeeldgegevens opnemen de eerste snapshot heeft voltooid, LOG_ANALYTICS_WORKSPACE overeenkomt met een bestaande werkruimte en uw account leestoegang heeft. Controleer de inhoud van de tabel met KQL in de Defender-portal om te bevestigen dat er gegevens aanwezig zijn. Zie KQL-query's uitvoeren op de Microsoft Sentinel data lake voor meer informatie.

De aangepaste grafiek ontwerpen

Creëer op een van de volgende manieren:

Ontwerpen van ai-ondersteunde grafieken.
Handmatig maken

Ontwerpen van ai-ondersteunde grafieken

Voer de volgende stappen uit om een grafiek te maken met AI-hulp:

Open GitHub Copilot Chat in Visual Studio Code.

Start uw prompt met de helper @sentinel /graph-authoring voor het ontwerpen van grafieken en beschrijf uw grafiek in eenvoudige taal:

@sentinel /graph-authoring Create a graph that maps Entra groups to
their member users, groups, and service principals using EntraGroups,
EntraUsers, EntraServicePrincipals, and EntraMembers from the
"System tables" workspace.

Copilot genereert de volgende cellen voor de levenscyclus van het ontwerpen van grafieken:

Levenscyclusfase	Gegenereerde uitvoer
Omgevingsconfiguratie	Controleert de vereiste pakketten en verbindingsgegevens
Gegevens laden	Leest benoemde tabellen uit Sentinel data lake
Gegevenstransformatie	Knooppunt- en edge-gegevens voorbereiden
Grafiekschema	Definieert knooppunten en randen
Schemavalidatie	Valideert de grafiekdefinitie
Grafiekopbouw	Genereert de grafiek voor de sessie
Graafquery	Voert een voorbeeld van een GQL-query uit en visualiseert het resultaat

Ga door met het verfijnen van het notitieblok met prompts zoals deze:

Doel	Prompt
Een relatie toevoegen	`@sentinel Add an edge from User to IPAddress`
Gegevens filteren	`@sentinel Filter the data to show only failed sign-ins`
Tijdsbereik wijzigen	`@sentinel Change the time range to the last 7 days`
Buildfout oplossen	`@sentinel Fix the error in the graph build step`
Code begrijpen	`@sentinel Explain how edge keys are defined`
Een API opzoeken zonder te bewerken	`What parameters does build_graph_with_data() accept? #Sentinel`

Tip

Gebruik @sentinel /graph-authoring om notebookcellen te maken of te wijzigen. Als u API-uitleg of voorbeeldquery's nodig hebt, vraag het Copilot en voeg #Sentinel toe voor Sentinel-specifieke antwoorden.

Handmatig maken

Als u handmatig een grafiek wilt maken, voert u de volgende stappen uit:

Assettabellen verbinden en lezen.

from pyspark.sql import functions as F
from sentinel_lake.providers import MicrosoftSentinelProvider
lake_provider = MicrosoftSentinelProvider(spark=spark)
# Entra asset tables live in the "System tables" workspace.
# If your data is elsewhere, update this and ensure the tables exist.
LOG_ANALYTICS_WORKSPACE = "System tables"
# Use the latest snapshot of EntraUsers as the point-in-time for all tables.
snapshot_time = (
    lake_provider.read_table("EntraUsers", LOG_ANALYTICS_WORKSPACE)
    .df.agg(F.max("_SnapshotTime").alias("max_snapshot"))
    .collect()[0]["max_snapshot"]
    .strftime("%Y-%m-%dT%H:%M:%SZ")
)
print(f"Using snapshot_time: {snapshot_time}")
snapshot_filter = (F.col("_SnapshotTime") == F.lit(snapshot_time).cast("timestamp"))
# Edges: group contains user / group / servicePrincipal
df_members = (
    lake_provider.read_table("EntraMembers", LOG_ANALYTICS_WORKSPACE)
    .filter(
        snapshot_filter
        & (F.col("sourceType") == "group")
        & (F.col("targetType").isin("user", "group", "servicePrincipal"))
    )
)
# Nodes
df_groups = (
    lake_provider.read_table("EntraGroups", LOG_ANALYTICS_WORKSPACE)
    .filter(snapshot_filter)
    .select("id", "displayName", "mailEnabled")
)
df_users = (
    lake_provider.read_table("EntraUsers", LOG_ANALYTICS_WORKSPACE)
    .filter(snapshot_filter)
    .select("id", "accountEnabled", "displayName", "department",
            "userPrincipalName", "usageLocation")
)

Knooppunt- en edge-dataframes voorbereiden.

# NODES
user_nodes = df_users.df.select(
    "id", "displayName", "accountEnabled", "department",
    "userPrincipalName", "usageLocation")
group_nodes = df_groups.df.select("id", "displayName", "mailEnabled")
# EDGES
edge_group_contains_user = (
    df_members.df.filter(F.col("targetType") == "user")
    .select(F.col("sourceId").alias("SourceGroupId"),
            F.col("targetId").alias("TargetUserId"))
    .distinct()
    .withColumn("EdgeKey", F.concat_ws("_", F.col("SourceGroupId"), F.col("TargetUserId")))
)
edge_group_contains_group = (
    df_members.df.filter(F.col("targetType") == "group")
    .select(F.col("sourceId").alias("SourceGroupId"),
            F.col("targetId").alias("TargetGroupId"))
    .distinct()
    .withColumn("EdgeKey", F.concat_ws("_", F.col("SourceGroupId"), F.col("TargetGroupId")))
)

Grafiekschema definiëren en DataFrames binden.

from sentinel_graph import GraphSpecBuilder, Graph
entra_group_graph_spec = (
    GraphSpecBuilder.start()
    # === NODES ===
    .add_node("EntraUser").from_dataframe(user_nodes)
    .with_columns("id", "displayName", "accountEnabled", "department",
                  "userPrincipalName", "usageLocation",
                  key="id", display="displayName")
    .add_node("EntraGroup").from_dataframe(group_nodes)
    .with_columns("id", "displayName", "mailEnabled",
                  key="id", display="displayName")
    # === EDGES ===
    .add_edge("ContainsUser").from_dataframe(edge_group_contains_user)
    .source(id_column="SourceGroupId", node_type="EntraGroup")
    .target(id_column="TargetUserId", node_type="EntraUser")
    .with_columns("SourceGroupId", "TargetUserId", "EdgeKey",
                  key="EdgeKey", display="EdgeKey")
    .add_edge("ContainsGroup").from_dataframe(edge_group_contains_group)
    .source(id_column="SourceGroupId", node_type="EntraGroup")
    .target(id_column="TargetGroupId", node_type="EntraGroup")
    .with_columns("SourceGroupId", "TargetGroupId", "EdgeKey",
                  key="EdgeKey", display="EdgeKey")
).done()
# Validate the schema before building.
entra_group_graph_spec.show_schema()

Bouw de grafiek.
```
# Build = prepare data + publish for the session.
entra_group_graph = Graph.build(entra_group_graph_spec)
print(entra_group_graph.build_status.status)   # "published" or "prepared"
```
Opmerking

Graph.build() bereidt gegevens voor en publiceert in één gesprek. Om voorbereide knooppunten en randen te inspecteren voordat u publiceert, roept u Graph.prepare(spec) aan, controleert u graph.nodes en graph.edges, en roept u vervolgens graph.publish() aan.

Voer een GQL-query uit.

# Find nested group relationships up to 8 levels deep. 
# Update the Entra Group name that you want to traverse from 

query_nested_groups = """ 
MATCH p=(g1:EntraGroup)-[cg]->{1,8}(g2) 
WHERE g1.displayName = 'tmplevel3' 
RETURN * 
""" 
entra_group_graph.query(query_nested_groups).show()

Het Graph-notebook testen

Test het notebook om ervoor te zorgen dat deze de verwachte grafiekuitvoer produceert:

Start de kernel opnieuw en voer alle cellen van boven naar beneden uit.
Controleer of elke cel succesvol wordt voltooid.
Als transformatiecellen langer dan 5 minuten op een kleine pool draaien, stel de snapshotfilters en kolomprojectie dan strakker af voordat u opschaalt.
Bevestig dat show_schema() de verwachte knooppunten en randen retourneert.
Voer een voorbeeld van een GQL-query uit en controleer visualisatie- en tabellaire uitvoer.
Randgevallen valideren:
- Lege invoer.
- Schema-afwijking.
- Geen toegang tot de tabel.

Tip

Voeg markdown-cellen toe boven elke codesectie voor documentdoel, invoer, uitvoer en de knooppunten of randen die worden geproduceerd.

Een grafiektaak plannen om de grafiek te materialiseren

Grafieken die in een interactieve sessie zijn gemaakt, zijn kortstondig. Plan een grafiektaak om de grafiek te behouden en te vernieuwen. Zie Microsoft Sentinel grafiektaken plannen en beheren voor meer informatie.

Selecteer in uw grafieknotitieblok Geplande taak maken>Een grafiektaak maken.
Voer de naam en beschrijving van de grafiek in en controleer het notebookpad.
Selecteer een planning:
- Op aanvraag: bouwt één keer, met een standaardretentieperiode van 30 dagen.
- Gepland: selecteer herhalingsfrequentie en begin-/eindtijden.
Klik op Verzenden.
Open de grafiek in de Sentinel-extensie en bewaak taakdetails.
Gebruik Nu uitvoeren om indien nodig buiten het schema uit te voeren.
Bevestig het statusverloop van Queued naar In Progress naar Ready.

Important

Ingediende taken worden losgekoppeld van uw lokale notebook. Als u de lokale .ipynb taak bewerkt, wordt de geplande taak niet bijgewerkt. Als u een taaknotitieblok wilt bijwerken, downloadt u het in het deelvenster Graphs, bewerkt u het en gebruikt u vervolgens Taak bewerken>Verzenden.

Query's uitvoeren en visualiseren vanuit Graph Explorer

Nadat de taakstatus van de grafiek isReady, kunt u query's uitvoeren en visualiseren in de Defender-portal, notebooks en REST API's.

Open in de Defender-portal onder Microsoft Sentinel de grafiekweergave en selecteer uw gematerialiseerde grafiek.
Voer GQL-query's uit, inspecteer het schema, schakel visuele en tabellaire uitvoer in en ga door de volgende hop.
Gebruik deze GQL-snelzoekgids:

Patroon of clausule	Voorbeeld
Knooppunt met label	`(g:EntraGroup)`
Getypeerde, gerichte rand	`-[c:ContainsUser]->`
Pad met variabele lengte (1 tot 8 hops)	`(a)-[e]->{1,8}(b)`
Filter	`WHERE g.displayName = 'Finance Admins'`
Projecteren, sorteren, beperken	`RETURN g.displayName ORDER BY g.displayName LIMIT 10`
Labelexpressies	`(:EntraUser \\| EntraServicePrincipal)`

Opmerking

Elke GQL-query begint met MATCH. De engine werkt in UTC. Gebruiken ZONED_DATETIME(...) voor letterlijke datum/tijd. INSERT en CREATE worden niet ondersteund. Grafieken zijn alleen-leesbaar.

Query's uitvoeren vanuit een notebook.

from sentinel_graph import Graph
# Attach to an already-materialized graph by name.
graph = Graph.get("entra_group_membership")
graph.query("MATCH (g:EntraGroup)-[c:ContainsUser]->(u:EntraUser) RETURN g, c, u").show()
# Purpose-built security algorithms are available too:
graph.blast_radius(source_property_value="Finance Admins", min_hop_count=1).show()

Query's uitvoeren met behulp van Graph REST API's.

GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom
Authorization: Bearer <access_token>

POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Authorization: Bearer <access_token>
Content-Type: application/json
{
  "query": "MATCH (g:EntraGroup)-[c:ContainsUser]->(u) RETURN g, c, u LIMIT 100",
  "responseFormats": ["Table", "Graph"],
  "queryLanguage": "GQL"
}

responseFormats bepaalt de uitvoervorm. "Table" retourneert rijen, "Graph" retourneert knooppunten en randen en ["Table", "Graph"] retourneert beide.

Zie Graph REST API's voor aangepaste grafieken voor meer informatie.

Uw grafiekoplossing verpakken en publiceren

Zodra uw grafiek is getest en gerealiseerd, verpakt u deze voor implementatie aan klanten. Raadpleeg Microsoft Sentinel-grafiek- en notebookoplossingen verpakken en publiceren voor gedetailleerde instructies voor het maken van pakketten.

Probleemoplossingsproces

Gebruik de volgende tabellen om veelvoorkomende problemen op symptoom te diagnosticeren.

Grafieken maken

Symptom	Waarschijnlijke oorzaak en oplossing
`MicrosoftSentinelProvider` of `sentinel_graph` niet gevonden	Meld u opnieuw aan bij de extensie en bevestig dat er een Microsoft Sentinel kernel is geselecteerd.
Cel loopt vast bij 'Spark-sessie starten'	Het opstarten kan 3 tot 5 minuten duren. Als deze langer is dan 6 minuten, controleert u de poolcapaciteit en probeert u het opnieuw.
`show_schema()` is leeg of `Graph.build()` mislukt	Controleer of de sleutel- en weergavekolommen bestaan en niet null zijn en of de bron- en doelwaarden `node_type` overeenkomen met knooppuntaliassen.
GQL-query retourneert geen rijen	Controleer of er filterwaarden aanwezig zijn in de geselecteerde momentopname en controleer het filteren van momentopnamen.
`publish()` mislukt vanwege geweigerde toegang	Controleer of u de rol Beveiligingsoperator, Beveiligingsbeheerder of Globale beheerder hebt.

AI-ondersteund auteurschap

Symptom	Waarschijnlijke oorzaak en oplossing
`@sentinel /graph-authoring` doet niets	Controleer of GitHub Copilot- en Jupyter-extensies zijn geïnstalleerd en actief zijn en of u een Copilot Business- of Enterprise-abonnement hebt.
Gegenereerde code verwijst naar een ontbrekende tabel	Controleer of de connector is ingesteld en controleer of de tabel wordt weergegeven in de Data Lake Explorer.

Taakplanning

Symptom	Waarschijnlijke oorzaak en oplossing
Wijzigingen in lokale notitieblokken worden niet weergegeven in de taak	Download het jobnotebook uit het deelvenster Grafieken, bewerk het en gebruik vervolgens Taak bewerken>Verzenden.
Gematerialiseerde grafiek is verdwenen	Grafieken op aanvraag hebben 30 dagen retentie. Plan een terugkerende taak of voer een nieuwe build uit.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-07-21

Oplossingen voor aangepast grafiekplatform ontwikkelen

Prerequisites

Permissions

Tools

Werkstroom bouwen

Voorbeeldgegevens opnemen

Connectiviteit valideren met een eenvoudig notebook

De aangepaste grafiek ontwerpen

Ontwerpen van ai-ondersteunde grafieken

Handmatig maken

Het Graph-notebook testen

Een grafiektaak plannen om de grafiek te materialiseren

Query's uitvoeren en visualiseren vanuit Graph Explorer

Uw grafiekoplossing verpakken en publiceren

Probleemoplossingsproces

Grafieken maken

AI-ondersteund auteurschap

Taakplanning

Verwante onderwerpen

Feedback

Aanvullende resources