Guida introduttiva all'API di OnDMARC

L'API di OnDMARC è perfetta per eseguire attività massive o ripetitive che devono essere svolte rapidamente, spesso e senza errori – e non è necessario essere sviluppatori o saper programmare per utilizzarla. In questo articolo, ti guiderò attraverso l'esecuzione dell'attività comune di aggiornamento della policy dei sottodomini per i domini già in reject, utilizzando Dynamic DMARC di Red Sift, l'API di OnDMARC e Make (precedentemente conosciuto come Integromat). In questo esempio utilizziamo Make, ma potresti facilmente usare qualsiasi altro strumento di automazione no-code come Zapier o Retool.

Quando OnDMARC configura per la prima volta un record DMARC su un dominio che precedentemente non ne aveva uno, crea sempre una policy p="none" (solo reporting DMARC) e sp=none. Ciò significa che anche la policy dei sottodomini è impostata su solo reporting. Questo significa che se un'email proveniente dal dominio o da uno qualsiasi dei suoi sottodomini che non ha una policy specifica non supera il controllo DMARC, il destinatario non dovrebbe intraprendere nessuna azione (di blocco). L'email dovrebbe essere consegnata normalmente e un report DMARC inviato a noi per l'analisi. A meno che il sottodominio non abbia una propria policy DMARC, ma su questo trovi maggiori informazioni nella nostra utile guida DMARC qui.

Questa policy passiva è ottima mentre un dominio e le sue fonti di invio vengono configurati, ma una volta completata questa fase, oppure se il dominio e i suoi sottodomini non inviano email, la policy dovrebbe essere rapidamente modificata in p=reject. In questo caso, le email che non superano il controllo DMARC verranno rifiutate dal destinatario, bloccando i tentativi di spoofing.

Nel nostro esempio, abbiamo 4 domini in un account OnDMARC. Abbiamo diligentemente modificato 3 domini a p=reject ma abbiamo dimenticato di aggiornare la policy dei sottodomini, che rimane a sp=none. Un dominio rimanente è ancora a p=none perché stiamo ancora lavorando su di esso. Dobbiamo quindi tornare indietro e aggiornare la policy dei sottodomini per 3 dei 4 domini a sp=reject. Con l'interfaccia di OnDMARC e Dynamic DMARC, questo è in realtà abbastanza semplice e richiederebbe circa 12 clic. Ma cosa succederebbe se, invece di 3 domini su 4, ne avessimo 36 su 73? Sarebbe molto meno divertente. Ecco che entra in gioco l'API di OnDMARC.

Per prima cosa, dobbiamo ottenere una chiave API per OnDMARC. Vai su Amministrazione nel pannello Utente e Account facendo clic sull'icona del profilo in alto a destra dello schermo.

Poi fai clic sulla scheda OnDMARC e assicurati di selezionare l'istanza corretta dal selettore di istanze. Se hai accesso solo a un'istanza OnDMARC, non devi preoccuparti di selezionare l'istanza corretta.

Scorri verso il basso fino alla tabella delle chiavi API in fondo alla schermata e fai clic su Aggiungi. Assicurati di assegnare il ruolo Super Admin a questa chiave durante il processo. Copia la chiave API in un luogo sicuro. La schermata delle tue Chiavi API dovrebbe ora avere questo aspetto:

Nella schermata I miei domini, fai clic sul pulsante di esportazione evidenziato di seguito e scarica il tuo elenco di domini come CSV.

Poi, vai su Google Sheets (o Microsoft Office 365) e caricalo in un nuovo foglio. Elimina tutte le colonne tranne quella dei domini per poterci concentrare su quella. Dovrebbe avere ora un aspetto simile a questo:

Nota, avremmo potuto anche ottenere l'elenco dei domini dall'API utilizzando l'endpoint API GET /domains invece del metodo CSV.

Ora che abbiamo configurato il nostro foglio di controllo, andiamo su Make per impostare il nostro scenario di automazione. Se non hai già un account, puoi crearne uno qui.

Ora vai su Scenari e fai clic su "Crea un nuovo scenario". Aggiungi il primo modulo e seleziona il modulo Google Sheets "Get Range Values". Se è la prima volta, Make ti chiederà di autenticarti con Google Sheets prima di procedere.

Una volta fatto ciò, configuriamo il modulo affinché recuperi l'intervallo corretto di righe dal nostro specifico file e scheda di Google Sheets. Dovrebbe avere questo aspetto:

Possiamo testare questo facendo clic destro sul modulo e selezionando "Esegui solo questo modulo" per verificare l'output.

Come previsto, otteniamo un pacchetto per ogni riga, contenente ciascun dominio. Ciò ci permette di iterare attraverso ogni dominio nell'elenco nei passaggi successivi.

Successivamente, contatteremo l'API di OnDMARC, prima per verificare le impostazioni Dynamic DMARC attuali, e poi per aggiornarle se necessario. Verifichiamo le impostazioni attuali prima di aggiornarle perché vogliamo aggiornare la policy dei sottodomini a reject solo per i domini in cui la policy di primo livello è in reject.

Per ottenere le impostazioni della policy Dynamic DMARC esistenti, utilizzeremo l'endpoint GET domainDMARC. Questo recupera le impostazioni Dynamic DMARC attuali di un dominio specifico nell'istanza OnDMARC.

Crea un nuovo modulo, collegandolo al primo modulo Google Sheets, e seleziona l'app HTTP e l'azione "Make a Basic Auth request" come indicato di seguito:

Nel campo URL, digita l'URL base dell'API per la tua area geografica, seguito dall'estensione "/domain/{domain}/dmarc". Puoi ottenere l'URL base corretto dalla parte superiore della documentazione API; varia in base alla posizione della tua istanza (UE, Regno Unito o USA). Per l'istanza del Regno Unito, avrebbe questo aspetto https://api.ondmarc.com/domain/{domain}/dmarc

Ora sostituisci {domain} con un riferimento alla colonna dominio nel foglio Google Sheets del modulo precedente, così:

Assicurati di impostare il Metodo su GET, e poi possiamo passare al passaggio successivo di configurazione di questa chiamata API: l'Autorizzazione. Affinché la chiamata API funzioni, dovrà essere autorizzata utilizzando la tua chiave API. Per farlo dobbiamo aggiungere un'Intestazione di Autorizzazione.

Dai all'elemento 1 nella sezione Intestazioni il nome "Authorization", e nel campo valore, digita Api-Key, seguito da uno spazio, seguito dalla chiave API che avevi salvato nel passo 1. Assicurati di seguire esattamente questi passaggi come specificato, sono sensibili al maiuscolo/minuscolo. Il risultato finale dovrebbe avere l'aspetto dello screenshot sopra.

Come ultimo passo, imposta il tipo di Body su Raw, il tipo di Contenuto su JSON (application/json), e imposta "Parse response" su sì, poi fai clic su OK per salvare.

Ora eseguiamo l'intero scenario per testarlo.

Ottimo successo. Analizzando l'output, l'API restituisce un oggetto dati che contiene un Array chiamato "entries", il primo elemento (elemento 1) contiene la policy di primo livello e il terzo elemento (elemento 3) contiene la policy dei sottodomini. Per evitarci la manipolazione degli array, faremo la supposizione sicura che gli elementi arriveranno sempre in questo ordine, e creeremo mappature semplici per i nostri filtri.

Tornando al nostro foglio Google, nell'intestazione della colonna B, digita "p=" e nella colonna C digita "previous sp=", nella D aggiungiamo "Codice stato aggiornamento" e nella E "new sp=". Il risultato dovrebbe avere questo aspetto:

Ora creiamo il nostro primo writeback su Google Sheets per scrivere le impostazioni attuali nel nostro foglio a scopo di conferma. Aggiungi un modulo Google Sheets "Update Row" e configuralo come segue:

Nota il riferimento al numero di riga del primo modulo, questo garantisce che i risultati vengano aggiunti alla riga corretta. E nelle colonne B e C ci riferiamo ai valori degli elementi 1 e 3 dell'array "Entries" restituito dall'API di OnDMARC. Se ora eseguiamo lo scenario, i risultati dovrebbero avere questo aspetto:

Possiamo ora vedere chiaramente che i domini nelle righe 2, 4 e 5 necessitano che la loro policy dei sottodomini venga modificata a reject, ma non quello nella riga 3. Continuiamo al passo successivo.

Ora creiamo un modulo router per creare due possibili percorsi per il nostro scenario. Fai clic sul segno + accanto all'ultimo modulo nello scenario e cerca "Router". Nel primo percorso, filtreremo per far passare solo le righe in cui la policy p= ha il valore "reject", e nel secondo, tutti gli altri risultati.

Configuriamo il primo filtro facendo clic sul 1° percorso dopo il router. Nomina il filtro e configuralo come segue:

Questo significa che solo gli elementi in cui la policy è p=reject verranno lasciati passare attraverso questo percorso. Sul secondo percorso, impostiamo il filtro inverso:

Nota l'operatore "Diverso da".

Configuriamo prima il secondo percorso poiché è il più semplice. Qui, non abbiamo bisogno di aggiornare la policy, semplicemente scriveremo nella riga che non è stato necessario alcun aggiornamento. Clona il modulo Update row e trascinalo nel secondo percorso, modificalo per configurarlo così:

Ricorda, la colonna D è il nostro campo "Codice stato aggiornamento".

Ora rivolgiamo la nostra attenzione al primo percorso, dove effettueremo una chiamata di aggiornamento all'API di OnDMARC. Invece di configurare un nuovo modulo HTTP da zero, clona e rinomina il primo, e poi trascinalo nel percorso. I percorsi dovrebbero avere questo aspetto:

Ora dobbiamo modificare la chiamata API perché non vogliamo più ottenere le impostazioni attuali, ma invece vogliamo inviare nuove impostazioni. Utilizzeremo lo stesso endpoint API ma invece di una chiamata GET, utilizzeremo una chiamata PATCH, con alcune informazioni aggiuntive nel body per specificare le impostazioni modificate che desideriamo. Configuralo come segue:

Ricordati di cambiare il Metodo in PATCH, mantieni le stesse intestazioni di Autorizzazione, e includi quanto segue nel contenuto o body della richiesta:

Questo aggiorna la policy dei sottodomini del dominio in questione, lasciando tutto il resto invariato.

Ora, aggiungiamo un writeback finale di conferma su Google Sheets. Clona, rinomina e trascina il modulo Google Sheets "Update a Row" dal percorso sottostante, e configuralo così:

Questo scriverà il codice di stato della risposta nella colonna D, e se lo stato è di successo (codice 200), allora il valore aggiornato ("reject") verrà scritto nella colonna E, altrimenti verrà lasciato vuoto.

Lo scenario completo dovrebbe avere questo aspetto:

Eseguiamolo!

Se tutto è configurato correttamente, i domini in reject dovrebbero seguire il percorso 1, e quelli non in reject vengono incanalati nel percorso 2. Ed ecco il risultato in Google Sheets, perfetto:

Questo è un ottimo esempio di un caso d'uso reale per l'API di OnDMARC. Abbiamo visto come chiunque possa utilizzarla con software di fogli di calcolo come Google Sheets o Microsoft Office 365 come foglio di controllo, e Make o Zapier come strumento di automazione per effettuare le chiamate API. In questo esempio, abbiamo utilizzato l'API per aggiornare condizionalmente le impostazioni Dynamic DMARC per una serie di domini, ma è possibile anche qualsiasi altra azione. Per avere qualche idea, puoi consultare la documentazione dell'API di OnDMARC oppure ricordare semplicemente che qualsiasi cosa tu possa fare manualmente nell'interfaccia utente, probabilmente puoi anche trovare un endpoint API corrispondente con cui orchestrarla automaticamente.