[Deprecato] Creare un connettore senza codice legacy per Microsoft Sentinel
Importante
La raccolta di log da molti dispositivi e appliance è ora supportata da Common Event Format (CEF) tramite AMA, syslog tramite AMA o log personalizzati tramite il connettore dati AMA in Microsoft Sentinel. Per altre informazioni, vedere Trovare il connettore dati di Microsoft Sentinel.
Importante
È disponibile una versione più recente di Codeless Connector 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. È possibile distribuire i connettori creati tramite CCP con API, un modello di ARM o come soluzione nell'hub dei contenuti di Microsoft Sentinel.
I connettori 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 Connector 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 connettere l'origine dati a 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
- Connettere Microsoft Sentinel all'origine dati e iniziare l'inserimento di dati
Questo articolo descrive la sintassi usata nelle configurazioni e nelle procedure JSON CCP per la distribuzione del connettore tramite API, un modello di ARM 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 di ARM per i connettori dati.
Esaminare altri connettori dati CCP come esempi o scaricare il modello di esempio DataConnector_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:
- 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 connectorUiConfig e la sintassi necessarie per configurare l'interfaccia utente:
| Nome proprietà | Type | Descrizione |
|---|---|---|
| availability | {"status": 1,"isPreview": Booleano} |
stato: 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. |
| dataTypes | 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 differente 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[] | Array 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.
dataTypes
| Valore array | Tipo | Descrizione |
|---|---|---|
| name | string | Descrizione significativa per lastDataReceivedQuery, incluso il 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 differente per ogni tipo di dati.
| Valore array | Tipo | Descrizione |
|---|---|---|
| metricName | String | Nome significativo per il grafico. Esempio: Total data received |
| legenda | 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 un array di passaggi interni dell'istruzione. |
| istruzioni | Array di istruzioni | Obbligatorio. Definisce un array 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ù instructionSteps 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 link 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 un array aggiuntivo denominato 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 parametro userRequestPlaceHoldersInput 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 un array 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:
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 array | 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 |
| label | 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:
Al contrario, l'immagine seguente mostra un messaggio informativo non-inline:
| Valore array | Tipo | Descrizione |
|---|---|---|
| Testo | String | Definire il testo da visualizzare nella finestra di 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:
| Valore array | Tipo | Descrizione |
|---|---|---|
| title | String | Definisce il titolo per il passaggio dell'istruzione. |
| canCollapseAllSections | Booleano | Facoltativo. Determina se la sezione è o meno una fisarmonica comprimibile. |
| noFxPadding | Booleano | Facoltativo. Se true, riduce la spaziatura interna dell'altezza per risparmiare spazio. |
| esteso | 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 link. Ecco alcuni esempi di entrambi:
| Valori di matrice | Tipo | Descrizione |
|---|---|---|
| linkType | ENUM | Determina il tipo di link, come uno dei valori seguenti: InstallAgentOnWindowsVirtualMachineInstallAgentOnWindowsNonAzureInstallAgentOnLinuxVirtualMachineInstallAgentOnLinuxNonAzureOpenSyslogSettingsOpenCustomLogsSettingsOpenWafOpenAzureFirewall 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 ARM 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 array | 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, AadP1P2 Aatp Mcas, Mdatp, Mtp, IoT Esempio: il valore licenze viene visualizzato in Microsoft Sentinel come Licenza: Obbligatoria 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 | array 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 array 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 requiredPermissions sono 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":Booleano} |
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 array | 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 link
Per definire un link inline usando markdown, usare l'esempio seguente. Di seguito è riportato un link 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 link come modello di ARM, usare l'esempio seguente come guida:
{
"title": "Azure Resource Manager (ARM) template",
"description": "1. Click the **Deploy to Azure** button below.\n\n\t[]({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
- Andare a Microsoft Sentinel -> Connettori dati
- Fare clic sul pulsante "importa" e selezionare un file JSON che contiene solo la sezione
connectorUiConfigdel 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 sezione pollingConfig del file di configurazione CCP.
"pollingConfig": {
"auth": {
},
"request": {
},
"response": {
},
"paging": {
}
}
La sezione pollingConfig include le proprietà seguenti:
| Nome | Tipo | Descrizione |
|---|---|---|
| aut | String | Descrive le proprietà di autenticazione per il polling dei dati. Per altre informazioni, vedere le Configurazione dell'autenticazione. |
| auth.authType | String | Obbligatorio. Definisce il tipo di autenticazione, annidata 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 sezione auth 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 del connettore Codeless 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 | Dizionario<stringa,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 | Dizionario<stringa,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 | Dizionario<stringa,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 | Dizionario<stringa,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 valori client_id e client_secret vengono definiti nell'intestazione, come avviene 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 | Dizionario<stringa,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 | Dizionario<stringa,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 | Dizionario<stringa,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 | Dizionario<stringa,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 sezione request della configurazione 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 | Dizionario<stringa,oggetto> | Facoltativo. Definisce i parametri passati nella query nel percorso eventsJsonPaths. 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 richiesta queryParameters e queryParametersTemplate. {_APIKeyName} e {_APIKey} sono supportati solo nel parametro di richiesta queryParametersTemplate. |
| 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 | Dizionario<stringa,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 sezione response della configurazione pollingConfig include i parametri seguenti:
Il codice seguente mostra un esempio del valore eventsJsonPaths per un messaggio di primo livello:
"eventsJsonPaths": [
"$"
]
Configurazione del paging
La sezione paging della configurazione 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, LinkHeader NextPageToken, NextPageUrl Offset |
| 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 flag HasNextPage. |
| nextPageTokenResponseHeader | String | Facoltativo. Definisce il nome dell'intestazione del token della pagina successiva nella risposta. |
| nextPageParaName | String | Facoltativo. Determina il nome della pagina successiva nella richiesta. |
| nextPageRequestHeader | String | Facoltativo. Determina il nome dell'intestazione della 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 sezione pollingConfig 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 il wrapping delle raccolte di configurazioni JSON in un modello di ARM 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 ARM o di selezionare l'area di lavoro durante la distribuzione del modello di ARM.
Preparare un file JSON del modello di ARM per il connettore. Ad esempio, vedere i file JSON del modello di ARM seguenti:
- Connettore dati nella soluzione Slack
- Connettore dati nella soluzione GitHub
Nel portale di Azure cercare Distribuire un modello personalizzato.
Nel riquadro Distribuzione personalizzata, selezionare Compila un modello personalizzato nell'editor>Carica file. Andare a e selezionare il modello di ARM locale e quindi salvare le modifiche.
Selezionare la sottoscrizione e il gruppo di risorse e quindi immettere l'area di lavoro Log Analytics in cui si desidera distribuire il connettore personalizzato.
Selezionare Rivedi + crea per distribuire il connettore personalizzato in Microsoft Sentinel.
In Microsoft Sentinel andare alla pagina Connettori dati e 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.
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.
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
connectorUiConfigdel 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.In Microsoft Sentinel andare 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 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 ulteriori informazioni, vedere,