Creare un connettore senza codice legacy per Microsoft Sentinel

Articolo
12/19/2023

Importante

È disponibile una versione più recente di Codeless Connessione or Platform (CCP). Per altre informazioni sul nuovo CCP, vedere Creare un connettore senza codice (anteprima).

Fare riferimento a questo documento se è necessario mantenere o aggiornare un connettore dati basato su questa versione precedente e legacy del CCP.

Il CCP offre ai partner, agli utenti avanzati e agli sviluppatori la possibilità di creare connettori personalizzati, connetterli e inserire dati a Microsoft Sentinel. Connessione ors creati tramite CCP possono essere distribuiti tramite API, un modello arm o come soluzione nell'hub del contenuto di Microsoft Sentinel.

Connessione ors creati con CCP sono completamente SaaS, senza requisiti per le installazioni di servizi e includono anche il monitoraggio dell'integrità e il supporto completo di Microsoft Sentinel.

Creare il connettore dati definendo le configurazioni JSON, con le impostazioni per l'aspetto della pagina del connettore dati in Microsoft Sentinel insieme alle impostazioni di polling che definiscono le funzioni di connessione.

Importante

Questa versione di Codeless Connessione or Platform (CCP) è in ANTEPRIMA, ma è considerata anche Legacy. Le condizioni aggiuntive per l'anteprima di Azure includono termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, anteprima o diversamente non ancora disponibili a livello generale.

Usare la procedura seguente per creare il connettore CCP e connettersi all'origine dati da Microsoft Sentinel:

Configurare l'interfaccia utente del connettore
Configurare le impostazioni di polling del connettore
Distribuire il connettore nell'area di lavoro di Microsoft Sentinel
Connessione Microsoft Sentinel all'origine dati e iniziare a inserire dati

Questo articolo descrive la sintassi usata nelle configurazioni e nelle procedure JSON CCP per la distribuzione del connettore tramite API, un modello di Resource Manager o una soluzione Microsoft Sentinel.

Prerequisiti

Prima di creare un connettore, è consigliabile comprendere il comportamento dell'origine dati e esattamente il modo in cui Microsoft Sentinel dovrà connettersi.

Ad esempio, è necessario conoscere i tipi di autenticazione, impaginazione e endpoint API necessari per le connessioni riuscite.

Creare un file di configurazione JSON del connettore

Il connettore CCP personalizzato include due sezioni JSON principali necessarie per la distribuzione. Compilare queste aree per definire il modo in cui il connettore viene visualizzato nel portale di Azure e come connette Microsoft Sentinel all'origine dati.

connectorUiConfig. Definisce gli elementi visivi e il testo visualizzati nella pagina del connettore dati in Microsoft Sentinel. Per altre informazioni, vedere Configurare l'interfaccia utente del connettore.
pollingConfig. Definisce il modo in cui Microsoft Sentinel raccoglie i dati dall'origine dati. Per altre informazioni, vedere Configurare le impostazioni di polling del connettore.

Quindi, se si distribuisce il connettore senza codice tramite ARM, si eseguirà il wrapping di queste sezioni nel modello arm per i connettori dati.

Esaminare altri connettori dati CCP come esempi o scaricare il modello di esempio Data Connessioneor_API_CCP_template.json (anteprima).

Configurare l'interfaccia utente del connettore

Questa sezione descrive le opzioni di configurazione disponibili per personalizzare l'interfaccia utente della pagina del connettore dati.

L'immagine seguente mostra una pagina del connettore dati di esempio, evidenziata con numeri che corrispondono alle aree rilevanti dell'interfaccia utente:

Screenshot of a sample data connector page.

Titolo. Titolo visualizzato per il connettore dati.
Logo. Icona visualizzata per il connettore dati. La personalizzazione di questa opzione è possibile solo quando si esegue la distribuzione come parte di una soluzione.
Stato. Indica se il connettore dati è connesso o meno a Microsoft Sentinel.
Grafici dati. Visualizza le query pertinenti e la quantità di dati inseriti nelle ultime due settimane.
Scheda Istruzioni. Include una sezione Prerequisiti , con un elenco di convalide minime prima che l'utente possa abilitare il connettore e Istruzioni, per guidare l'abilitazione dell'utente del connettore. Questa sezione può includere testo, pulsanti, moduli, tabelle e altri widget comuni per semplificare il processo.
Scheda Passaggi successivi. Include informazioni utili per comprendere come trovare i dati nei log eventi, ad esempio le query di esempio.

Ecco le sezioni e la connectorUiConfig sintassi necessarie per configurare l'interfaccia utente:

Nome proprietà	Type	Descrizione
availability	`{` `"status": 1,` `"isPreview":` Boolean `}`	status: 1 Indica che il connettore è disponibile a livello generale per i clienti. isPreview Indica se includere (anteprima) il suffisso al nome del connettore.
connectivityCriteria	`{` `"type": SentinelKindsV2,` `"value": APIPolling` `}`	Oggetto che definisce come verificare se il connettore è definito correttamente. Usare i valori indicati qui.
Tipi	dataTypes[]	Elenco di tutti i tipi di dati per il connettore e una query per recuperare l'ora dell'ultimo evento per ogni tipo di dati.
descriptionMarkdown	String	Descrizione per il connettore con la possibilità di aggiungere il linguaggio markdown per migliorarlo.
graphQueries	graphQueries[]	Query che presentano l'inserimento dati nelle ultime due settimane nel riquadro Grafici dati . Specificare una query per tutti i tipi di dati del connettore dati o una query diversa per ogni tipo di dati.
graphQueriesTableName	String	Definisce il nome della tabella di Log Analytics da cui vengono estratti i dati per le query. Il nome della tabella può essere qualsiasi stringa, ma deve terminare in `_CL`. Ad esempio: `TableName_CL`
instructionsSteps	instructionSteps[]	Matrice di parti del widget che spiegano come installare il connettore, visualizzata nella scheda Istruzioni .
metadata	metadata	Metadati visualizzati sotto la descrizione del connettore.
autorizzazioni	autorizzazioni[]	Le informazioni visualizzate nella sezione Prerequisiti dell'interfaccia utente in cui sono elencate le autorizzazioni necessarie per abilitare o disabilitare il connettore.
publisher	String	Questo è il testo illustrato nella sezione Provider .
sampleQueries	sampleQueries[]	Query di esempio per il cliente per comprendere come trovare i dati nel registro eventi da visualizzare nella scheda Passaggi successivi.
title	String	Titolo visualizzato nella pagina del connettore dati.

Mettere insieme tutti questi pezzi è complicato. Usare lo strumento di convalida dell'esperienza utente della pagina del connettore per testare i componenti inseriti.

Tipi

Valore matrice	Tipo	Descrizione
name	string	Descrizione significativa per , incluso il`lastDataReceivedQuery` supporto per una variabile. Esempio: `{{graphQueriesTableName}}`
lastDataReceivedQuery	String	Una query KQL che restituisce una riga e indica l'ultima volta che sono stati ricevuti i dati o nessun dato se non sono presenti dati pertinenti. Esempio: `{{graphQueriesTableName}}\n \| summarize Time = max(TimeGenerated)\n \| where isnotempty(Time)`

graphQueries

Definisce una query che presenta l'inserimento dati nelle ultime due settimane nel riquadro Grafici dati .

Specificare una query per tutti i tipi di dati del connettore dati o una query diversa per ogni tipo di dati.

Valore matrice	Tipo	Descrizione
metricName	String	Nome significativo per il grafico. Esempio: `Total data received`
Leggenda	String	Stringa visualizzata nella legenda a destra del grafico, incluso un riferimento a una variabile. Esempio: `{{graphQueriesTableName}}`
baseQuery	String	Query che filtra gli eventi pertinenti, incluso un riferimento a una variabile. Ad esempio: `TableName_CL \| where ProviderName == "myprovider"` o `{{graphQueriesTableName}}`

instructionSteps

Questa sezione fornisce parametri che definiscono il set di istruzioni visualizzate nella pagina del connettore dati in Microsoft Sentinel.

Array, proprietà	Tipo	Descrizione
title	String	Facoltativo. Definisce un titolo per le istruzioni.
description	Stringa	Facoltativo. Definisce una descrizione significativa per le istruzioni.
innerSteps	Matrice	Facoltativo. Definisce una matrice di passaggi interni dell'istruzione.
Istruzioni	Matrice di istruzioni	Obbligatorio. Definisce una matrice di istruzioni di un tipo di parametro specifico.
bottomBorder	Booleano	Facoltativo. Quando `true`, aggiunge un bordo inferiore all'area delle istruzioni nella pagina del connettore in Microsoft Sentinel
isComingSoon	Booleano	Facoltativo. Quando `true`, aggiunge un titolo presto disponibile nella pagina del connettore in Microsoft Sentinel

istruzioni

Visualizza un gruppo di istruzioni, con varie opzioni come parametri e la possibilità di annidare più istruzioniSteps in gruppi.

Parametro	Proprietà Array	Descrizione
APIKey	APIKey	Aggiungere segnaposto al file di configurazione JSON del connettore.
CopyableLabel	CopyableLabel	Mostra un campo di testo con un pulsante di copia alla fine. Quando il pulsante è selezionato, il valore del campo viene copiato.
InfoMessage	InfoMessage	Definisce un messaggio informativo inline.
InstructionStepsGroup	InstructionStepsGroup	Visualizza un gruppo di istruzioni, facoltativamente espanso o comprimibile, in una sezione separata delle istruzioni.
InstallAgent	InstallAgent	Visualizza un collegamento ad altre parti di Azure per soddisfare vari requisiti di installazione.

APIKey

È possibile creare un modello di file di configurazione JSON, con parametri segnaposto, riutilizzarli in più connettori o anche creare un connettore con dati attualmente non disponibili.

Per creare parametri segnaposto, definire una matrice aggiuntiva denominata userRequestPlaceHoldersInput nella sezione Istruzioni del file di configurazione JSON CCP usando la sintassi seguente:

"instructions": [
                {
                  "parameters": {
                    "enable": "true",
                    "userRequestPlaceHoldersInput": [
                      {
                        "displayText": "Organization Name",
                        "requestObjectKey": "apiEndpoint",
                        "placeHolderName": "{{placeHolder}}"
                      }
                    ]
                  },
                  "type": "APIKey"
                }
              ]

Il userRequestPlaceHoldersInput parametro include gli attributi seguenti:

Nome	Tipo	Descrizione
DisplayText	String	Definisce il valore di visualizzazione della casella di testo visualizzato all'utente durante la connessione.
RequestObjectKey	String	Definisce l'ID nella sezione della richiesta di pollingConfig per sostituire il valore segnaposto con il valore specificato dall'utente. Se non si usa questo attributo, usare invece l'attributo `PollingKeyPaths` .
PollingKeyPaths	String	Definisce una matrice di oggetti JsonPath che indirizza la chiamata API a qualsiasi punto del modello, per sostituire un valore segnaposto con un valore utente. Esempio:`"pollingKeyPaths":["$.request.queryParameters.test1"]` Se non si usa questo attributo, usare invece l'attributo `RequestObjectKey` .
PlaceHolderName	String	Definisce il nome del parametro segnaposto nel file modello JSON. Può trattarsi di qualsiasi valore univoco, ad esempio `{{placeHolder}}`.

CopyableLabel

Esempio:

Screenshot of a copy value button in a field.

Codice di esempio:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

Valore matrice	Tipo	Descrizione
fillWith	ENUM	Facoltativo. Matrice di variabili di ambiente usate per popolare un segnaposto. Separare più segnaposto con virgole. Ad esempio: `{0},{1}` Valori supportati: `workspaceId`, `workspaceName`, `primaryKey`, `MicrosoftAwsAccount`, `subscriptionId`
etichetta	String	Definisce il testo per l'etichetta sopra una casella di testo.
value	String	Definisce il valore da presentare nella casella di testo, supporta i segnaposto.
rows	Righe	Facoltativo. Definisce le righe nell'area dell'interfaccia utente. Per impostazione predefinita, impostare su 1.
wideLabel	Booleano	Facoltativo. Determina un'etichetta wide per stringhe lunghe. Per impostazione predefinita, impostare su `false`.

InfoMessage

Ecco un esempio di messaggio informativo inline:

Screenshot of an inline information message.

Al contrario, l'immagine seguente mostra un messaggio informativo non inline:

Screenshot of a non-inline information message.

Valore matrice	Tipo	Descrizione
Testo	String	Definire il testo da visualizzare nel messaggio.
Visibile	Booleano	Determina se il messaggio viene visualizzato.
Inline	Booleano	Determina la modalità di visualizzazione del messaggio informativo. - `true`: (Scelta consigliata) Mostra il messaggio informativo incorporato nelle istruzioni. - `false`: aggiunge uno sfondo blu.

InstructionStepsGroup

Di seguito è riportato un esempio di gruppo di istruzioni espandibile:

Screenshot of an expandable, extra instruction group.

Valore matrice	Tipo	Descrizione
title	String	Definisce il titolo per il passaggio dell'istruzione.
canCollapseAllSections	Booleano	Facoltativo. Determina se la sezione è o meno una fisarmonica collapible.
noFxPadding	Booleano	Facoltativo. Se `true`, riduce la spaziatura interna dell'altezza per risparmiare spazio.
Espanso	Booleano	Facoltativo. Se `true`, viene visualizzato come espanso per impostazione predefinita.

Per un esempio dettagliato, vedere il codice JSON di configurazione per il connettore DNS Windows.

InstallAgent

Alcuni tipi InstallAgent vengono visualizzati come pulsante, altri verranno visualizzati come collegamento. Ecco alcuni esempi di entrambi:

Screenshot of a link added as inline text.

Valori di matrice	Tipo	Descrizione
linkType	ENUM	Determina il tipo di collegamento, come uno dei valori seguenti: `InstallAgentOnWindowsVirtualMachine` `InstallAgentOnWindowsNonAzure` `InstallAgentOnLinuxVirtualMachine` `InstallAgentOnLinuxNonAzure` `OpenSyslogSettings` `OpenCustomLogsSettings` `OpenWaf` `OpenAzureFirewall` `OpenMicrosoftAzureMonitoring` `OpenFrontDoors` `OpenCdnProfile` `AutomaticDeploymentCEF` `OpenAzureInformationProtection` `OpenAzureActivityLog` `OpenIotPricingModel` `OpenPolicyAssignment` `OpenAllAssignmentsBlade` `OpenCreateDataCollectionRule`
policyDefinitionGuid	String	Obbligatorio quando si usa il linkType OpenPolicyAssignment . Per i connettori basati su criteri, definisce il GUID della definizione di criteri predefinita.
assignMode	ENUM	Facoltativo. Per i connettori basati su criteri, definisce la modalità di assegnazione, come uno dei valori seguenti: `Initiative`, `Policy`
dataCollectionRuleType	ENUM	Facoltativo. Per i connettori basati su DCR, definisce il tipo di regola di raccolta dati come uno dei seguenti: `SecurityEvent`, `ForwardEvent`

metadata

Questa sezione fornisce i metadati nell'interfaccia utente del connettore dati nell'area Descrizione .

Valore raccolta	Tipo	Descrizione
kind	String	Definisce il tipo di modello di Resource Manager che si sta creando. Usare sempre `dataConnector`.
source	String	Descrive l'origine dati usando la sintassi seguente: `{` `"kind":`Stringa `"name":`Stringa `}`
Autore	String	Descrive l'autore del connettore dati usando la sintassi seguente: `{` `"name":`Stringa `}`
support	String	Descrivere il supporto fornito per il connettore dati usando la sintassi seguente: `{` `"tier":`Stringa `"name":`Stringa `"email":`Stringa `"link":`Stringa URL `}`

autorizzazioni

Valore della matrice	Tipo	Descrizione
dogana	String	Descrive le autorizzazioni personalizzate necessarie per la connessione dati, nella sintassi seguente: `{` `"name":`string`,` `"description":`Stringa `}` Esempio: il valore doganale viene visualizzato nella sezione Prerequisiti di Microsoft Sentinel con un'icona informativa blu. Nell'esempio di GitHub questo è correlato alla riga Chiave del token personale dell'API GitHub: è necessario accedere al token personale di GitHub...
Licenze	ENUM	Definisce le licenze necessarie, come uno dei valori seguenti: `OfficeIRM`,`OfficeATP` , `Office365`, `AadP1P2AatpMcas`, `Mdatp`, , `MtpIoT` Esempio: il valore delle licenze viene visualizzato in Microsoft Sentinel come: Licenza: Obbligatorio Azure AD Premium P2
resourceProvider	resourceProvider	Descrive tutti i prerequisiti per la risorsa di Azure. Esempio: il valore resourceProvider viene visualizzato nella sezione Prerequisiti di Microsoft Sentinel come: Area di lavoro: è necessaria l'autorizzazione di lettura e scrittura. Chiavi: sono necessarie le autorizzazioni di lettura per le chiavi condivise per l'area di lavoro.
tenant	matrice di valori ENUM Esempio: `"tenant": [` `"GlobalADmin",` `"SecurityAdmin"` `]`	Definisce le autorizzazioni necessarie, come uno o più dei valori seguenti: `"GlobalAdmin"`, `"SecurityAdmin"`, `"SecurityReader"`, `"InformationProtection"` Esempio: visualizza il valore del tenant in Microsoft Sentinel come: Autorizzazioni tenant: Richiede `Global Administrator` o `Security Administrator` nel tenant dell'area di lavoro

resourceProvider

valore della matrice secondaria	Tipo	Descrizione
provider	ENUM	Descrive il provider di risorse, con uno dei valori seguenti: - `Microsoft.OperationalInsights/workspaces` - `Microsoft.OperationalInsights/solutions` - `Microsoft.OperationalInsights/workspaces/datasources` - `microsoft.aadiam/diagnosticSettings` - `Microsoft.OperationalInsights/workspaces/sharedKeys` - `Microsoft.Authorization/policyAssignments`
providerDisplayName	String	Voce di elenco in Prerequisiti che visualizzerà un segno di spunta rosso "x" o verde quando le richiestePermission vengono convalidate nella pagina del connettore. Esempio `"Workspace"`
permissionsDisplayText	String	Visualizzare il testo per le autorizzazioni lettura, scrittura o lettura e scrittura che devono corrispondere ai valori configurati in requiredPermissions
requiredPermissions	`{` `"action":`Booleano`,` `"delete":`Booleano`,` `"read":`Booleano`,` `"write":`Boolean `}`	Descrive le autorizzazioni minime necessarie per il connettore.
ambito	ENUM	Descrive l'ambito del connettore dati, come uno dei valori seguenti: `"Subscription"`, `"ResourceGroup"`, `"Workspace"`

sampleQueries

valore della matrice	Tipo	Descrizione
description	Stringa	Descrizione significativa per la query di esempio. Esempio: `Top 10 vulnerabilities detected`
query	String	Query di esempio usata per recuperare i dati del tipo di dati. Esempio: `{{graphQueriesTableName}}\n \| sort by TimeGenerated\n \| take 10`

Configurare altre opzioni di collegamento

Per definire un collegamento inline usando markdown, usare l'esempio seguente. Di seguito è riportato un collegamento in una descrizione dell'istruzione:

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

Per definire un collegamento come modello di Resource Manager, usare l'esempio seguente come guida:

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

Convalidare l'esperienza utente della pagina del connettore dati

Seguire questa procedura per eseguire il rendering e convalidare l'esperienza utente del connettore.

È possibile accedere all'utilità di test tramite questo URL: https://aka.ms/sentineldataconnectorvalidateurl
Passare a Microsoft Sentinel -> Connessione ors di dati
Fare clic sul pulsante "importa" e selezionare un file JSON che contiene solo la connectorUiConfig sezione del connettore dati.

Per altre informazioni su questo strumento di convalida, vedere le istruzioni per compilare il connettore nella guida alla compilazione di GitHub.

Nota

Poiché il parametro dell'istruzione APIKey è specifico del connettore senza codice, rimuovere temporaneamente questa sezione per usare lo strumento di convalida o non riuscirà.

Configurare le impostazioni di polling del connettore

Questa sezione descrive la configurazione per il polling dei dati dall'origine dati per un connettore dati senza codice.

Il codice seguente illustra la sintassi della pollingConfig sezione del file di configurazione CCP.

"pollingConfig": {
    "auth": {
    },
    "request": {
    },
    "response": {
    },
    "paging": {
    }
 }

La pollingConfig sezione include le proprietà seguenti:

Nome	Tipo	Descrizione
Auth	String	Descrive le proprietà di autenticazione per il polling dei dati. Per altre informazioni, vedere Configurazione dell'autenticazione.
auth.authType	String	Obbligatorio. Definisce il tipo di autenticazione, annidato all'interno dell'oggetto `auth` , come uno dei valori seguenti: `Basic`, `APIKey`, `OAuth2`
request	JSON annidato	Obbligatorio. Descrive il payload della richiesta per il polling dei dati, ad esempio l'endpoint API. Per altre informazioni, vedere Configurazione della richiesta.
Risposta	JSON annidato	Obbligatorio. Descrive l'oggetto risposta e il messaggio annidato restituito dall'API durante il polling dei dati. Per altre informazioni, vedere Configurazione della risposta.
Paging	JSON annidato	Facoltativo. Descrive il payload di paginazione durante il polling dei dati. Per altre informazioni, vedere Configurazione del paging.

Per altre informazioni, vedere Codice pollingConfig di esempio.

Configurazione dell'autenticazione

La auth sezione della configurazione pollingConfig include i parametri seguenti, a seconda del tipo definito nell'elemento authType :

Parametri authType di base

Nome	Tipo	Descrizione
Nome utente	String	Obbligatorio. Definisce il nome utente.
Password	String	Obbligatorio. Definisce la password utente.

Parametri apiKey authType

Nome	Tipo	Descrizione
APIKeyName	String	Facoltativo. Definisce il nome della chiave API, come uno dei valori seguenti: - `XAuthToken` - `Authorization`
IsAPIKeyInPostPayload	Booleano	Determina la posizione in cui è definita la chiave API. True: la chiave API è definita nel payload della richiesta POST False: la chiave API è definita nell'intestazione
APIKeyIdentifier	String	Facoltativo. Definisce il nome dell'identificatore per la chiave API. Ad esempio, dove l'autorizzazione è definita come `"Authorization": "token <secret>"`, questo parametro viene definito come : `{APIKeyIdentifier: “token”})`

Parametri OAuth2 authType

La piattaforma di Connessione or senza codice supporta la concessione del codice di autorizzazione OAuth 2.0.

Il tipo di concessione del codice di autorizzazione viene usato dai client riservati e pubblici per scambiare un codice di autorizzazione per un token di accesso.

Dopo che l'utente torna al client tramite l'URL di reindirizzamento, l'applicazione otterrà il codice di autorizzazione dall'URL e lo userà per richiedere un token di accesso.

Nome	Tipo	Descrizione
FlowName	String	Obbligatorio. Definisce un flusso OAuth2. Valore supportato: `AuthCode` - richiede un flusso di autorizzazione
AccessToken	String	Facoltativo. Definisce un token di accesso OAuth2, rilevante quando il token di accesso non scade.
AccessTokenPrepend	String	Facoltativo. Definisce un token di accesso OAuth2 anteporto. Il valore predefinito è `Bearer`.
RefreshToken	String	Obbligatorio per i tipi di autenticazione OAuth2. Definisce il token di aggiornamento OAuth2.
TokenEndpoint	String	Obbligatorio per i tipi di autenticazione OAuth2. Definisce l'endpoint del servizio token OAuth2.
AuthorizationEndpoint	String	Facoltativo. Definisce l'endpoint del servizio di autorizzazione OAuth2. Usato solo durante l'onboarding o quando si rinnova un token di aggiornamento.
RedirectionEndpoint	String	Facoltativo. Definisce un endpoint di reindirizzamento durante l'onboarding.
AccessTokenExpirationDateTimeInUtc	String	Facoltativo. Definisce un valore datetime di scadenza del token di accesso, in formato UTC. Rilevante per quando il token di accesso non scade e pertanto ha un valore datetime elevato in formato UTC o quando il token di accesso ha una data/ora di scadenza elevata.
RefreshTokenExpirationDateTimeInUtc	String	Obbligatorio per i tipi di autenticazione OAuth2. Definisce il valore datetime di scadenza del token di aggiornamento in formato UTC.
TokenEndpointHeaders	Stringa dizionario<, oggetto>	Facoltativo. Definisce le intestazioni quando si chiama un endpoint del servizio token OAuth2. Definire una stringa nel formato serializzato `dictionary<string, string>` : `{'<attr_name>': '<val>', '<attr_name>': '<val>'... }`
AuthorizationEndpointHeaders	Stringa dizionario<, oggetto>	Facoltativo. Definisce le intestazioni quando si chiama un endpoint del servizio di autorizzazione OAuth2. Usato solo durante l'onboarding o quando si rinnova un token di aggiornamento. Definire una stringa nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }`
AuthorizationEndpointQueryParameters	Stringa dizionario<, oggetto>	Facoltativo. Definisce i parametri di query quando si chiama un endpoint del servizio di autorizzazione OAuth2. Usato solo durante l'onboarding o quando si rinnova un token di aggiornamento. Definire una stringa nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }`
TokenEndpointQueryParameters	Stringa dizionario<, oggetto>	Facoltativo. Definire i parametri di query quando si chiama l'endpoint del servizio token OAuth2. Definire una stringa nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }`
IsTokenEndpointPostPayloadJson	Booleano	Facoltativa, l'impostazione predefinita è false. Determina se i parametri di query sono in formato JSON e impostati nel payload POST della richiesta.
IsClientSecretInHeader	Booleano	Facoltativa, l'impostazione predefinita è false. Determina se i `client_id` valori e `client_secret` sono definiti nell'intestazione, come avviee nello schema di autenticazione di base, anziché nel payload POST.
RefreshTokenLifetimeinSecAttributeName	String	Facoltativo. Definisce il nome dell'attributo dalla risposta dell'endpoint del token, specificando la durata del token di aggiornamento, in secondi.
IsJwtBearerFlow	Booleano	Facoltativa, l'impostazione predefinita è false. Determina se si usa JWT.
JwtHeaderInJson	Stringa dizionario<, oggetto>	Facoltativo. Definire le intestazioni JWT in formato JSON. Definire una stringa nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': <serialized val>, '<attr_name>': <serialized val>...}`
JwtClaimsInJson	Stringa dizionario<, oggetto>	Facoltativo. Definisce le attestazioni JWT in formato JSON. Definire una stringa nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ...}`
JwtPem	String	Facoltativo. Definisce una chiave privata in formato PEM Pkcs1: `'-----BEGIN RSA PRIVATE KEY-----\r\n{privatekey}\r\n-----END RSA PRIVATE KEY-----\r\n'` Assicurarsi di mantenere il `'\r\n'` codice sul posto.
RequestTimeoutInSeconds	Intero	Facoltativo. Determina il timeout in secondi quando si chiama l'endpoint del servizio token. Il valore predefinito è 180 secondi

Di seguito è riportato un esempio dell'aspetto di una configurazione OAuth2:

"pollingConfig": {
    "auth": {
        "authType": "OAuth2",
        "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent",
        "redirectionEndpoint": "https://portal.azure.com/TokenAuthorize",
        "tokenEndpoint": "https://oauth2.googleapis.com/token",
        "authorizationEndpointQueryParameters": {},
        "tokenEndpointHeaders": {
            "Accept": "application/json"
        },
        "TokenEndpointQueryParameters": {},
        "isClientSecretInHeader": false,
        "scope": "https://www.googleapis.com/auth/admin.reports.audit.readonly",
        "grantType": "authorization_code",
        "contentType": "application/x-www-form-urlencoded",
        "FlowName": "AuthCode"
    },

Parametri session authType

Nome	Tipo	Descrizione
QueryParameters	Stringa dizionario<, oggetto>	Facoltativo. Elenco di parametri di query, nel formato serializzato `dictionary<string, string>` : `{'<attr_name>': '<val>', '<attr_name>': '<val>'... }`
IsPostPayloadJson	Booleano	Facoltativo. Determina se i parametri di query sono in formato JSON.
Intestazioni	Stringa dizionario<, oggetto>	Facoltativo. Definisce l'intestazione usata quando si chiama l'endpoint per ottenere l'ID sessione e quando si chiama l'API dell'endpoint. Definire la stringa nel formato serializzato `dictionary<string, string>` : `{'<attr_name>': '<val>', '<attr_name>': '<val>'... }`
SessionTimeoutInMinutes	String	Facoltativo. Definisce un timeout di sessione, espresso in minuti.
SessionIdName	String	Facoltativo. Definisce un nome ID per la sessione.
SessionLoginRequestUri	String	Facoltativo. Definisce un URI della richiesta di accesso di sessione.

Richiedere la configurazione

La request sezione della configurazione di pollingConfig include i parametri seguenti:

Nome	Tipo	Descrizione
apiEndpoint	String	Obbligatorio. Definisce l'endpoint da cui eseguire il pull dei dati.
httpMethod	String	Obbligatorio. Definisce il metodo API: `GET` o `POST`
queryTimeFormat	String o UnixTimestamp o UnixTimestampInMills	Obbligatorio. Definisce il formato usato per definire l'ora della query. Questo valore può essere una stringa o in formato UnixTimestamp o UnixTimestampInMills per indicare l'ora di inizio e di fine della query in UnixTimestamp.
startTimeAttributeName	String	Facoltativo. Definisce il nome dell'attributo che definisce l'ora di inizio della query.
endTimeAttributeName	String	Facoltativo. Definisce il nome dell'attributo che definisce l'ora di fine della query.
queryTimeIntervalAttributeName	String	Facoltativo. Definisce il nome dell'attributo che definisce l'intervallo di tempo della query.
queryTimeIntervalDelimiter	String	Facoltativo. Definisce il delimitatore dell'intervallo di tempo della query.
queryWindowInMin	Intero	Facoltativo. Definisce la finestra di query disponibile, espressa in minuti. Valore minimo: `5`
queryParameters	Stringa dizionario<, oggetto>	Facoltativo. Definisce i parametri passati nella query nel `eventsJsonPaths` percorso. Definire la stringa nel formato serializzato `dictionary<string, string>` : `{'<attr_name>': '<val>', '<attr_name>': '<val>'... }`.
queryParametersTemplate	String	Facoltativo. Definisce il modello di parametri di query da usare quando si passano parametri di query in scenari avanzati. Ad esempio: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"` `{_QueryWindowStartTime}` e `{_QueryWindowEndTime}` sono supportati solo nei parametri di `queryParameters` richiesta e `queryParametersTemplate` . `{_APIKeyName}` e `{_APIKey}` sono supportati solo nel `queryParametersTemplate` parametro di richiesta.
isPostPayloadJson	Booleano	Facoltativo. Determina se il payload POST è in formato JSON.
rateLimitQPS	Double	Facoltativo. Definisce il numero di chiamate o query consentite in un secondo.
timeoutInSeconds	Intero	Facoltativo. Definisce il timeout della richiesta, espresso in secondi.
retryCount	Intero	Facoltativo. Definisce il numero di tentativi di richiesta da provare, se necessario.
headers	Stringa dizionario<, oggetto>	Facoltativo. Definisce il valore dell'intestazione della richiesta nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': '<serialized val>', '<attr_name>': '<serialized val>'... }`

Configurazione della risposta

La response sezione della configurazione di pollingConfig include i parametri seguenti:

Nome	Tipo	Descrizione
eventsJsonPaths	Elenco di stringhe	Obbligatorio. Definisce il percorso del messaggio nel codice JSON della risposta. Un'espressione di percorso JSON specifica un percorso di un elemento o un set di elementi in una struttura JSON
successStatusJsonPath	String	Facoltativo. Definisce il percorso del messaggio di operazione riuscita nel codice JSON della risposta.
successStatusValue	String	Facoltativo. Definisce il percorso del valore del messaggio di operazione riuscita nel codice JSON della risposta
isGzipCompressed	Booleano	Facoltativo. Determina se la risposta è compressa in un file gzip.

Il codice seguente mostra un esempio del valore eventsJsonPaths per un messaggio di primo livello:

"eventsJsonPaths": [
              "$"
            ]

Configurazione del paging

La paging sezione della configurazione di pollingConfig include i parametri seguenti:

Nome	Tipo	Descrizione
pagingType	String	Obbligatorio. Determina il tipo di paging da usare nei risultati, come uno dei valori seguenti: `None`, `LinkHeaderNextPageToken`, `NextPageUrlOffset`
linkHeaderTokenJsonPath	String	Facoltativo. Definisce il percorso JSON per collegare l'intestazione nel codice JSON della risposta, se `LinkHeader` non è definito nell'intestazione della risposta.
nextPageTokenJsonPath	String	Facoltativo. Definisce il percorso di un token di pagina successivo JSON.
hasNextFlagJsonPath	String	Facoltativo. Definisce il percorso dell'attributo `HasNextPage` flag.
nextPageTokenResponseHeader	String	Facoltativo. Definisce il nome dell'intestazione del token di pagina successivo nella risposta.
nextPageParaName	String	Facoltativo. Determina il nome della pagina successiva nella richiesta.
nextPageRequestHeader	String	Facoltativo. Determina il nome dell'intestazione di pagina successiva nella richiesta.
nextPageUrl	String	Facoltativo. Determina l'URL della pagina successiva, se è diverso dall'URL della richiesta iniziale.
nextPageUrlQueryParameters	String	Facoltativo. Determina i parametri di query dell'URL della pagina successiva se è diverso dall'URL della richiesta iniziale. Definire la stringa nel formato serializzato `dictionary<string, object>` : `{'<attr_name>': <val>, '<attr_name>': <val>... }`
offsetParaName	String	Facoltativo. Definisce il nome del parametro offset.
pageSizeParaName	String	Facoltativo. Definisce il nome del parametro dimensioni pagina.
Pagesize	Intero	Definisce le dimensioni del paging.

Codice pollingConfig di esempio

Il codice seguente illustra un esempio della pollingConfig sezione del file di configurazione CCP:

"pollingConfig": {
    "auth": {
        "authType": "APIKey",
        "APIKeyIdentifier": "token",
        "APIKeyName": "Authorization"
     },
     "request": {
        "apiEndpoint": "https://api.github.com/../{{placeHolder1}}/audit-log",
        "rateLimitQPS": 50,
        "queryWindowInMin": 15,
        "httpMethod": "Get",
        "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
        "retryCount": 2,
        "timeoutInSeconds": 60,
        "headers": {
           "Accept": "application/json",
           "User-Agent": "Scuba"
        },
        "queryParameters": {
           "phrase": "created:{_QueryWindowStartTime}..{_QueryWindowEndTime}"
        }
     },
     "paging": {
        "pagingType": "LinkHeader",
        "pageSizeParaName": "per_page"
     },
     "response": {
        "eventsJsonPaths": [
          "$"
        ]
     }
}

Distribuire il connettore in Microsoft Sentinel e avviare l'inserimento di dati

Dopo aver creato il file di configurazione JSON, inclusa l'interfaccia utente e la configurazione di polling, distribuire il connettore nell'area di lavoro di Microsoft Sentinel.

Usare una delle opzioni seguenti per distribuire il connettore dati.

Suggerimento

Il vantaggio della distribuzione tramite un modello di Azure Resource Manager (ARM) è che diversi valori sono incorporati nel modello e non è necessario definirli manualmente in una chiamata API.
- Eseguire la distribuzione tramite un modello di Resource Manager
- Distribuire tramite API
Eseguire il wrapping delle raccolte di configurazioni JSON in un modello di Resource Manager per distribuire il connettore. Per assicurarsi che il connettore dati venga distribuito nell'area di lavoro corretta, assicurarsi di definire l'area di lavoro nel modello di Resource Manager o di selezionare l'area di lavoro durante la distribuzione del modello di Resource Manager.
1. Preparare un file JSON del modello di Resource Manager per il connettore. Ad esempio, vedere i file JSON del modello di Resource Manager seguenti:
  - Connettore dati nella soluzione Slack
  - Connettore dati nella soluzione GitHub
2. Nella portale di Azure cercare Distribuisci un modello personalizzato.
3. Nella pagina Distribuzione personalizzata selezionare Compila un modello personalizzato nel file di caricamento dell'editor>. Passare a e selezionare il modello di Resource Manager locale e quindi salvare le modifiche.
4. Selezionare la sottoscrizione e il gruppo di risorse e quindi immettere l'area di lavoro Log Analytics in cui si vuole distribuire il connettore personalizzato.
5. Selezionare Rivedi e crea per distribuire il connettore personalizzato in Microsoft Sentinel.
6. In Microsoft Sentinel passare alla pagina Connettori dati, cercare il nuovo connettore. Configurarlo per avviare l'inserimento dei dati.
Per altre informazioni, vedere Distribuire un modello locale nella documentazione di Azure Resource Manager.
1. Eseguire l'autenticazione all'API di Azure. Per altre informazioni, vedere Introduzione a REST.
2. Richiamare una chiamata ALL'API CREATE o UPDATE a Microsoft Sentinel per distribuire il nuovo connettore. Nel corpo della richiesta definire il kind valore come APIPolling.
Il connettore dati viene distribuito nell'area di lavoro di Microsoft Sentinel ed è disponibile nella pagina Connettori dati.

Configurare il connettore dati per connettere l'origine dati e avviare l'inserimento di dati in Microsoft Sentinel. È possibile connettersi all'origine dati tramite il portale, come con i connettori dati predefiniti o tramite l'API.

Quando si usa il portale di Azure per connettersi, i dati utente vengono inviati automaticamente. Quando ci si connette tramite API, è necessario inviare i parametri di autenticazione pertinenti nella chiamata API.

Connessione tramite il portale di Azure
Connessione tramite API

Nella pagina del connettore dati di Microsoft Sentinel seguire le istruzioni fornite per connettersi al connettore dati.

La pagina del connettore dati in Microsoft Sentinel è controllata dalla configurazione InstructionSteps nell'elemento connectorUiConfig del file di configurazione JSON CCP. Se si verificano problemi con la connessione all'interfaccia utente, assicurarsi di avere la configurazione corretta per il tipo di autenticazione.

Usare l'endpoint CONNECT per inviare un metodo PUT e passare la configurazione JSON direttamente nel corpo del messaggio. Per altre informazioni, vedere Configurazione dell'autenticazione.

Usare gli attributi API seguenti, a seconda del tipo di autenticazione definito. Per ogni authType parametro, tutti gli attributi elencati sono obbligatori e sono valori stringa.

Authtype	Attributi
Base	Definire: - `kind` Come `Basic` - `userName` come nome utente, tra virgolette - `password` come password, tra virgolette
APIKey	Definire: - `kind` Come `APIKey` - `APIKey` come stringa di chiave API completa, tra virgolette

Se si usa un segnaposto nel modello, inviare i dati insieme agli placeHolderValue attributi che contengono i dati utente. Ad esempio:

"requestConfigUserInputValues": [
    {
       "displayText": "<A display name>",
       "placeHolderName": "<A placeholder name>",
       "placeHolderValue": "<A value for the placeholder>",
       "pollingKeyPaths": "<Array of items to use in place of the placeHolderName>"
     }
]

In Microsoft Sentinel passare alla pagina Log e verificare di visualizzare i log dall'origine dati che passano all'area di lavoro.

Se non viene visualizzato il flusso di dati in Microsoft Sentinel, controllare la documentazione dell'origine dati e le risorse per la risoluzione dei problemi, controllare i dettagli della configurazione e controllare la connettività. Per altre informazioni, vedere Monitorare l'integrità dei connettori dati.

Disconnettere il connettore

Se i dati del connettore non sono più necessari, disconnettere il connettore per arrestare il flusso di dati.

Usa uno dei seguenti metodi:

portale di Azure: nella pagina del connettore dati di Microsoft Sentinel selezionare Disconnetti.

API: usare l'API DISCONNECT per inviare una chiamata PUT con un corpo vuoto all'URL seguente:

https://management.azure.com /subscriptions/{{SUB}}/resourceGroups/{{RG}}/providers/Microsoft.OperationalInsights/workspaces/{{WS-NAME}}/providers/Microsoft.SecurityInsights/dataConnectors/{{Connector_Id}}/disconnect?api-version=2021-03-01-preview

Passaggi successivi

Se non è ancora stato fatto, condividere il nuovo connettore dati senza codice con la community di Microsoft Sentinel. Creare una soluzione per il connettore dati e condividerla in Microsoft Sentinel Marketplace.

Per altre informazioni, vedere

Informazioni sulle soluzioni di Microsoft Sentinel.
Informazioni di riferimento sul modello arm del connettore dati

Condividi tramite