Vývoj vlastních řešení platformy Graph

Note

Tato funkce je aktuálně dostupná jako ukázková verze. Viz Supplementální podmínky použití pro verze Preview Microsoft Azure.

Microsoft Sentinel vlastní řešení grafu je řešení založené na poznámkových blocích, které definuje uzly a hrany z tabulek Microsoft Sentinel data lake, sestaví graf a umožní uživatelům dotazovat se na tento graf pomocí jazyka Graph Query Language (GQL).

V tomto průvodci můžete vytvářet, testovat, materializovat, balit a publikovat vlastní řešení grafů jako nabídku SaaS v Partnerské centrum Microsoftu, aby ji zákazníci mohli objevit v zabezpečení od Microsoftu Storu.

Předpoklady

Abyste mohli vytvářet řešení Custom Graph, musíte být zaregistrováni v datovém jezeře. Další informace najdete v článku Jak se připojit k datovému jezeru Microsoft Sentinel.

Povolení

Následující tabulka uvádí požadovaná oprávnění pro každou operaci nebo obor v této příručce.

Operation	Požadovaná role
Začlenění do datového jezera Sentinel	Microsoft Entra ID – správce zabezpečení nebo globální správce
Připojení pracovního prostoru služby Sentinel k portálu Defender	Vlastník předplatného nebo správce přístupu uživatelů v rozsahu předplatného a Přispěvatel Microsoft Sentinel v rozsahu předplatného nebo skupiny prostředků
Připojit pracovní prostor Sentinel k datovému jezeru	Vlastník předplatného nebo Přispěvatel Microsoft Sentinel v rozsahu předplatného nebo skupiny prostředků
Modelování a sestavení grafu poznámkového bloku	Vlastní sjednocená role RBAC Microsoft Defenderu XDR s oprávněním data (manage) pro shromažďování dat v Microsoft Sentinelu
Zachování grafu (materializace)	Operátor zabezpečení, správce zabezpečení nebo globální správce
Dotazování na uložený graf	Vlastní sjednocená role RBAC Microsoft Defender XDR s security data basics (read) ke shromažďování dat Microsoft Sentinel
Publikace vlastního řešení pro Graph	Účet Publisher Marketplace na Partnerské centrum Microsoftu

Tools

K sestavení a publikování vlastního řešení grafu jsou potřeba následující nástroje:

• Visual Studio Code.
• Rozšíření Microsoft Sentinel pro Visual Studio Code. Pro více informací viz Instalace Visual Studio Code a rozšíření Microsoft Sentinel.
• Rozšíření Jupyter pro Visual Studio Code.
• rozšíření GitHub Copilot a tarif GitHub Copilot Business nebo Enterprise.
• Python 3.10 nebo novější na místním počítači.

Tip

Použijte znovu existující datové jezero, pokud už je váš tenant zprovozněný pro dotazy KQL, poznámkové bloky nebo agenta Security Copilot. Pro každého tenanta existuje jedno datové jezero. Na portálu Defender přejděte dočásti Nastavení>systému>Microsoft Sentinel>Data Lake. Pokud je stav Zřízeno, přeskočte úlohu 1.

Postup sestavení

Následující pracovní postup popisuje kroky pro sestavení a publikování vlastního řešení grafu.

1. Načtěte ukázková data do tabulek, které odpovídají vašemu grafovému modelu.
2. Ověřte připojení pomocí jednoduchého notebooku.
3. Vytvořte vlastní graf.
4. Otestujte grafový poznámkový blok.
5. Naplánujte úlohu pro graf k materializaci grafu.
6. Dotazování a vizualizace grafu z Graph Exploreru
7. Zabalte a publikujte vlastní řešení grafu.

Ingestace ukázkových dat

Tento úkol načítá tabulky prostředků Microsoft Entra ID, které používá ukázkový graf v této příručce: EntraUsers, EntraGroups, EntraServicePrincipals a EntraMembers.

1. Na portálu Defender přejděte naNastavení>systému>Microsoft Sentinel>Data konektory.
2. Povolte konektor Microsoft Entra ID, aby se tabulky assetů Entra načítaly do datového jezera. Pro více informací viz Data o majetku v datovém jezeře Microsoft Sentinel.
3. Ověřte, že se tyto tabulky zobrazují v Průzkumníku data Lake:
   • EntraUsers
   • EntraGroups
   • EntraServicePrincipals
   • EntraMembers
4. Tyto tabulky se objeví v pracovním prostoru Systémové tabulky.
5. Volitelné: ingestování dalších konektorů a nahrazení názvů tabulek v pozdějších krocích, pokud váš scénář používá jiná data.

Note

Pokud se v Průzkumníku data lake nezobrazí tabulka, nemůžete ji použít k vytváření grafů a pomoc s AI na ni neodkazuje.

Ověřit připojení pomocí jednoduchého notebooku

Vytvořte a spusťte minimální notebook, abyste před tvorbou grafu ověřili připojení k datovému jezeru.

1. Otevřete Visual Studio Code a přihlaste se k rozšíření Microsoft Sentinel pomocí stejného účtu, který má přístup k datovému jezeře.

2. V Visual Studio Code v části Sentinel Extension–Graphs (Grafy rozšíření služby Sentinel) vyberte Vytvořit nový poznámkový blok.

3. Uložte poznámkový blok, například hello-world-show-tables.ipynb.

4. Vyberte Vybrat jádro, vyberte Microsoft Sentinel a vyberte dostupný fond Sparku.

5. Přidejte následující buňky v pořadí.

Buňka 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

Buňka 2 – Kód (připojení a nastavení pracovního prostoru):

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}")

Buňka 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.

Buňka 4 – kód (čtení tabulky a zobrazení řádků):

# 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)

Buňka 5 – Kód (volitelné kontrolní počty):

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

1. Spusťte všechny buňky odshora dolů.
2. Potvrďte, že se každá buňka dokončí bez červeného zpětného trasování, zobrazí se data náhledu tabulky a počet řádků není nulový.

Note

Pokud čtení selže nebo nevrátí žádné řádky, ověřte, že konektor z oddílu s ukázkovými daty Ingest dokončil svůj první snímek, LOG_ANALYTICS_WORKSPACE odpovídá skutečnému pracovnímu prostoru a váš účet má přístup ke čtení. Zkontrolujte obsah tabulky pomocí KQL na portálu Defender a ověřte, že jsou data k dispozici. Další informace najdete v tématu Spouštění dotazů KQL na Microsoft Sentinel data lake.

Vytvoření vlastního grafu

Autor jedním z těchto způsobů:

• Vytváření grafů s asistencí umělé inteligence
• Autor ručně.

Vytváření grafů s asistencí umělé inteligence

Pokud chcete vytvořit graf s pomocí AI, postupujte takto:

1. V Visual Studio Code otevřete Copilot Chat GitHubu.

2. Spusťte výzvu pomocí pomocníka @sentinel /graph-authoring pro vytváření grafů a popište graf v prostém jazyce:

   @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 vygeneruje následující buňky pro životní cyklus vytváření grafu:

   Fáze životního cyklu	Vygenerovaný výstup
   Nastavení prostředí	Ověřuje požadované balíčky a informace o připojení.
   Načítání dat	Přečte pojmenované tabulky ze služby Sentinel Data Lake.
   Převod dat	Připravuje data uzlů a hran.
   Schéma grafu	Definuje uzly a hrany.
   Ověřování schématu	Ověří definici grafu.
   Sestavení graphu	Materializuje graf pro relaci.
   Grafové dotazy	Spustí ukázkový dotaz GQL a vizualizuje výsledek.

3. Pokračujte v upřesňování poznámkového bloku výzvami, jako jsou tyto:

   Goal	Výzva
   Přidat relaci	@sentinel Add an edge from User to IPAddress
   Filtrování dat	@sentinel Filter the data to show only failed sign-ins
   Změna časového rozsahu	@sentinel Change the time range to the last 7 days
   Oprava chyby sestavení	@sentinel Fix the error in the graph build step
   Principy kódu	@sentinel Explain how edge keys are defined
   Vyhledání rozhraní API bez úprav	What parameters does build_graph_with_data() accept? #Sentinel

Tip

Slouží @sentinel /graph-authoring k vytvoření nebo úpravě buněk poznámkového bloku. Pokud potřebujete vysvětlení rozhraní API nebo ukázkové dotazy, zeptejte se Copilota a pro odpovědi specifické pro Sentinel zahrňte #Sentinel.

Autor ručně

Pokud chcete graf vytvořit ručně, postupujte takto:

1. Připojení a čtení tabulek prostředků

   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")
   )
   

2. Příprava uzlů a hraničních datových rámců

   # 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")))
   )
   

3. Definujte schéma grafu a vytvořte vazbu datových rámců.

   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()
   

4. Sestavte graf.

   # 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"
   

   Note

   Graph.build() připraví data a zveřejní je jediným voláním. Chcete-li před publikováním zkontrolovat připravené uzly a hrany, zavolejte Graph.prepare(spec), zkontrolujte graph.nodes a graph.edgespak zavolejte graph.publish().

5. Spusťte dotaz GQL.

   # 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()
   

Otestujte grafový poznámkový blok

Otestujte poznámkový blok, abyste zajistili, že vytvoří očekávaný výstup grafu:

1. Restartujte jádro a spusťte všechny buňky shora dolů.

2. Ověřte, že se každá buňka úspěšně dokončila.

3. Pokud transformace buněk běží déle než 5 minut v malém fondu, utáhněte filtry snímků a projekce sloupců před vertikálním navýšením kapacity.

4. Potvrďte, že show_schema() vrací očekávané uzly a hrany.

5. Spusťte ukázkový dotaz GQL a ověřte vizualizaci a tabulkový výstup.

6. Ověřte hraniční případy:

   • Prázdný vstup.
   • Odchylka schématu
   • Chybějící přístup k tabulce

Tip

Přidejte buňky Markdown nad každou část kódu pro zdokumentování účelu, vstupů, výstupů a vytvořených uzlů nebo hran.

Naplánujte úlohu grafu pro materializaci grafu

Grafy vytvořené v interaktivní relaci jsou dočasné. Naplánujte úlohu grafu, která bude uchovávat a aktualizovat graf. Další informace najdete v tématu Naplánování a správa grafových úloh Microsoft Sentinel.

1. V grafovém poznámkovém bloku vyberte Vytvořit naplánovanou úlohu>Vytvořit úlohu grafu.

2. Zadejte název a popis grafu a ověřte cestu k poznámkovému bloku.

3. Vyberte plán:

   • Na požádání: sestaví se jednou s výchozí dobou uchování 30 dní.
   • Naplánované: Vyberte četnost opakování a časy zahájení/ukončení.

4. Vyberte Odeslat.

5. Otevřete graf v rozšíření Sentinel a sledujte podrobnosti úlohy.

6. Pomocí možnosti Spustit nyní spusťte úlohu podle potřeby mimo plán.

7. Potvrďte průběh stavu od Queued do In ProgressReady .

Important

Odeslané úlohy jsou oddělené od místního poznámkového bloku. Úprava místního .ipynb nastavení neaktualizuje naplánovanou úlohu. Chcete-li aktualizovat poznámkový blok úlohy, stáhněte si ho z panelu Grafy, upravte ho a pak použijte Upravit úlohu>Odeslat.

Dotazování a vizualizace z Graph Exploreru

Jakmile je stav úlohy grafu Ready, můžete dotazovat a vizualizovat v portálu Defender, v poznámkových blocích a prostřednictvím rozhraní REST API.

1. Na portálu Defender v části Microsoft Sentinel otevřete grafové prostředí a vyberte materializovaný graf.
2. Spouštějte dotazy GQL, prozkoumejte schéma, přepínejte mezi vizuálním a tabulkovým výstupem a procházejte další uzel.
3. Použijte tuto stručnou referenční příručku GQL:

Vzorec nebo klauzule	Příklad
Uzel s popiskem	(g:EntraGroup)
Typovaný, směrovaný okraj	-[c:ContainsUser]->
Cesta s proměnnou délkou (1 až 8 skoků)	(a)-[e]->{1,8}(b)
Filter	WHERE g.displayName = 'Finance Admins'
Projekt, řazení, omezení	RETURN g.displayName ORDER BY g.displayName LIMIT 10
Výrazy popisků	(:EntraUser \| EntraServicePrincipal)

Note

Každý dotaz GQL začíná na MATCH. Engine pracuje v časovém pásmu UTC. Pro literály data a času použijte ZONED_DATETIME(...). INSERT a CREATE nejsou podporovány. Grafy jsou jen pro čtení.

1. Dotaz z poznámkového bloku

   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()
   

2. Dotazování pomocí rozhraní Graph REST API

   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 ovládá tvar výstupu. "Table" vrátí řádky, "Graph" vrátí uzly a hrany a ["Table", "Graph"] vrátí obojí.

Další informace najdete v tématu Rozhraní Graph REST API pro vlastní grafy.

Zabalení a publikování řešení grafu

Jakmile je graf otestovaný a materializovaný, zabalte ho pro nasazení zákazníkům. Podrobné pokyny k balení najdete v článku Balení a publikování řešení grafů a poznámkových bloků Microsoft Sentinel.

Řešení problémů

Pomocí následujících tabulek můžete diagnostikovat běžné problémy podle příznaků.

Vytváření grafů

Příznak	Pravděpodobná příčina a oprava
MicrosoftSentinelProvider nebo sentinel_graph nenalezena	Znovu se přihlaste k rozšíření a potvrďte, že je vybrané jádro Microsoft Sentinel.
Buňka se zasekne na „Starting Spark session“	První spuštění může trvat 3 až 5 minut. Pokud překročí 6 minut, zkontrolujte kapacitu fondu a zkuste to znovu.
show_schema() je prázdná nebo Graph.build() selže.	Ověřte, že klíčové sloupce a sloupce pro zobrazení existují a neobsahují hodnotu null a že hodnoty node_type ve zdroji i cíli odpovídají aliasům uzlů.
Dotaz GQL nevrací žádné řádky.	Ověřte, že ve vybraném snímku existují hodnoty filtru, a ověřte filtrování snímků.
publish() selže kvůli odepření přístupu	Ověřte, že máte roli operátora zabezpečení, správce zabezpečení nebo globálního správce.

Vytváření s asistencí umělé inteligence

Příznak	Pravděpodobná příčina a oprava
@sentinel /graph-authoring nedělá nic	Ověřte, že jsou nainstalovaná a aktivní rozšíření GitHub Copilot a jupyter a máte plán Copilot Business nebo Enterprise.
Vygenerovaný kód odkazuje na chybějící tabulku.	Potvrďte nastavení konektoru a ověřte, že se tabulka zobrazí v Průzkumníku data Lake.

Plánování úlohy

Příznak	Pravděpodobná příčina a oprava
Úpravy místního poznámkového bloku se v úloze neprojeví.	Stáhněte si notebook úlohy z panelu Grafy, upravte ho a potom použijte Upravit úlohu>Odeslat.
Materializovaný graf zmizel	Grafy na vyžádání mají 30denní uchovávání. Naplánujte opakovanou úlohu nebo spusťte nové sestavení.

Související obsah

• Přehled vlastních grafů v Microsoft Sentinel
• Začínáme s vlastními grafy
• Vlastní vytváření grafů s asistencí umělé inteligence
• Referenční informace k poskytovateli grafu Microsoft Sentinel
• Referenční informace ke GQL pro vlastní graf služby Sentinel
• Rozhraní GRAPH REST API pro vlastní grafy
• Připojení k datovému jezeru Microsoft Sentinel
• Spouštění poznámkových bloků v Microsoft Sentinel Data Lake
• Publikujte agenta Security Copilot nebo analytické řešení v obchodě Security Store
• Partnerské centrum Microsoftu