Prise en main de l'API OnDMARC

L'API OnDMARC est idéale pour effectuer des tâches répétitives ou en masse qui doivent être exécutées rapidement, fréquemment et sans erreur – et vous n'avez pas besoin d'être développeur ni même de savoir coder pour l'utiliser. Ici, je vais vous expliquer comment effectuer la tâche courante de mise à jour de la politique de sous-domaine des domaines déjà en reject, en utilisant le Dynamic DMARC de Red Sift, l'API OnDMARC et Make (anciennement Integromat). Nous utilisons Make dans cet exemple, mais vous pourriez tout aussi bien utiliser un autre outil d'automatisation sans code comme Zapier ou Retool.

Lorsque OnDMARC configure pour la première fois un enregistrement DMARC sur un domaine qui n'en avait pas auparavant, il crée toujours une politique p="none" (rapport DMARC uniquement) et sp=none. Cela signifie que la politique de sous-domaine est également réglée sur rapport uniquement. Ainsi, si un e-mail provenant du domaine ou de l'un de ses sous-domaines n'ayant pas de politique spécifique échoue au DMARC, aucune action (de blocage) ne doit être entreprise par le destinataire. L'e-mail doit être délivré normalement, et un rapport DMARC nous est renvoyé pour analyse. Sauf si le sous-domaine possède sa propre politique DMARC, pour en savoir plus, consultez notre guide DMARC ici.

Cette politique passive est utile pendant la configuration d'un domaine et de ses sources d'envoi, mais une fois cela fait, ou si le domaine et ses sous-domaines n'envoient pas de courrier, la politique doit rapidement être modifiée en p=reject. Ici, les e-mails échouant au DMARC seront rejetés par le destinataire, bloquant ainsi les tentatives de spoofing.

Dans notre exemple, nous avons 4 domaines dans un compte OnDMARC. Nous avons méthodiquement modifié 3 domaines pour passer à p=reject, mais avons oublié de mettre à jour la politique de sous-domaine qui reste à sp=none. Un domaine restant est toujours à p=none car nous travaillons encore sur celui-ci. Nous devons donc revenir en arrière et mettre à jour la politique de sous-domaine pour 3 des 4 domaines vers sp=reject. Avec l'interface OnDMARC et Dynamic DMARC, c'est en fait assez simple et cela prendrait environ 12 clics. Mais que se passerait-il si, au lieu de 3 domaines sur 4, nous en avions 36 sur 73 ? Ce serait beaucoup moins amusant. C'est là qu'intervient l'API OnDMARC.

Tout d'abord, nous devons obtenir une clé API pour OnDMARC. Rendez-vous dans Administration dans le panneau Utilisateur et Compte en cliquant sur l'icône de profil en haut à droite de l'écran.

Cliquez ensuite sur l'onglet OnDMARC et assurez-vous de sélectionner la bonne instance dans le sélecteur d'instance. Si vous n'avez accès qu'à une seule instance OnDMARC, vous n'avez pas besoin de vous en préoccuper.

Faites défiler jusqu'au tableau des clés API en bas de l'écran et cliquez sur Ajouter. Assurez-vous d'attribuer le rôle Super Admin à cette clé pendant le processus. Copiez la clé API dans un emplacement sécurisé. Votre écran de clés API devrait maintenant ressembler à ceci :

Sur l'écran My Domains, cliquez sur le bouton d'exportation mis en évidence ci-dessous et téléchargez votre liste de domaines au format CSV.

Ensuite, rendez-vous sur Google Sheets (ou Microsoft Office 365) et téléchargez-le dans une nouvelle feuille. Supprimez toutes les colonnes sauf la colonne des domaines afin de nous concentrer sur celle-ci. Cela devrait maintenant ressembler à ceci :

Notez que nous aurions également pu obtenir la liste des domaines depuis l'API en utilisant l'endpoint API GET /domains au lieu de la méthode CSV.

Maintenant que notre feuille de contrôle est configurée, rendons-nous sur Make pour configurer notre scénario d'automatisation. Si vous n'avez pas encore de compte, vous pouvez en créer un ici.

Allez maintenant dans Scénarios et cliquez sur « Créer un nouveau scénario ». Ajoutez le premier module et sélectionnez le module Google Sheets « Get Range Values ». Si c'est votre première fois, Make vous demandera de vous authentifier avec Google Sheets avant de continuer.

Une fois cela fait, nous configurons le module pour qu'il récupère la bonne plage de lignes de notre fichier Google Sheets et de l'onglet spécifiques. Cela devrait ressembler à ceci :

Nous pouvons tester cela en faisant un clic droit sur le module et en sélectionnant « Run this module only » pour vérifier le résultat.

Comme prévu, nous obtenons un bundle par ligne, contenant chaque domaine. Cela nous permet d'itérer sur chaque domaine de la liste dans les étapes suivantes.

Ensuite, nous allons interroger l'API OnDMARC, d'abord pour vérifier les paramètres actuels de Dynamic DMARC, puis pour les mettre à jour si nécessaire. Nous vérifions les paramètres actuels avant de les mettre à jour car nous ne souhaitons mettre à jour la politique de sous-domaine vers reject que pour les domaines dont la politique de premier niveau est déjà en reject.

Pour obtenir les paramètres actuels de la politique Dynamic DMARC, nous utiliserons l'endpoint GET domainDMARC. Celui-ci récupère les paramètres actuels de Dynamic DMARC d'un domaine spécifique dans l'instance OnDMARC.

Créez un nouveau module, en le liant au premier module Google Sheets, et sélectionnez l'application HTTP et l'action « Make a Basic Auth request » comme ci-dessous :

Dans le champ URL, saisissez l'URL de base de l'API pour votre région, suivie de l'extension « /domain/{domain}/dmarc ». Vous pouvez obtenir l'URL de base correcte en haut de la documentation de l'API, elle varie selon l'emplacement de votre instance (UE, Royaume-Uni ou États-Unis). Pour l'instance britannique, cela ressemblerait à ceci https://api.ondmarc.com/domain/{domain}/dmarc

Remplacez maintenant {domain} par une référence à la colonne domaine dans la Google Sheet du module précédent, comme suit :

Assurez-vous de régler la méthode sur GET, puis nous pouvons passer à l'étape suivante de configuration de cet appel API : l'autorisation. Pour que l'appel API fonctionne, il devra être autorisé à l'aide de votre clé API. Pour ce faire, nous devons ajouter un en-tête d'autorisation.

Donnez à l'élément 1 de la section En-têtes le nom « Authorization », et dans le champ valeur, saisissez Api-Key, suivi d'un espace, suivi de la clé API que vous aviez sauvegardée à l'étape 1. Veillez à suivre ces étapes exactement comme spécifié, elles sont sensibles à la casse. Le résultat final devrait ressembler à la capture d'écran ci-dessus.

Comme dernière étape, réglez le type de Body sur Raw, le type de contenu sur JSON (application/json), et réglez « Parse response » sur yes, puis cliquez sur OK pour enregistrer.

Maintenant, exécutons l'ensemble du scénario pour le tester.

Excellent résultat. En analysant la sortie, l'API renvoie un objet de données contenant un tableau appelé « entries », le premier élément (élément 1) contient la politique de premier niveau et le troisième élément (élément 3) contient la politique de sous-domaine. Pour nous éviter la manipulation de tableaux, nous ferons l'hypothèse raisonnable que les éléments arriveront toujours dans cet ordre, et créerons des correspondances simples pour nos filtres.

Retournons à notre feuille Google, dans l'en-tête de la colonne B, saisissez « p= » et dans la colonne C saisissez « previous sp= », dans D ajoutons « Update status code » et E « new sp= ». Le résultat devrait ressembler à ceci :

Créons maintenant notre premier écriture de retour vers Google Sheets pour réécrire les paramètres actuels dans notre feuille à titre de confirmation. Ajoutez un module Google Sheets « Update Row » et configurez-le comme suit :

Notez la référence au numéro de ligne du premier module, cela garantit que les résultats sont ajoutés à la bonne ligne. Et dans les colonnes B et C, nous faisons référence aux valeurs des éléments 1 et 3 du tableau « Entries » renvoyé par l'API OnDMARC. Si nous exécutons maintenant le scénario, les résultats devraient ressembler à ceci :

Nous pouvons maintenant voir clairement que les domaines des lignes 2, 4 et 5 nécessitent que leur politique de sous-domaine soit ajustée vers reject, mais pas celui de la ligne 3. Passons à l'étape suivante.

Créons maintenant un module de routeur pour créer deux chemins possibles pour notre scénario. Cliquez sur le signe + en regard du dernier module du scénario et recherchez « Router ». Dans le premier chemin, nous filtrerons pour ne laisser passer que les lignes où la politique p= a la valeur « reject », et dans le second, tous les autres résultats.

Configurons le premier filtre en cliquant sur le 1er chemin après le routeur. Nommez le filtre et configurez-le comme suit :

Cela signifie que seuls les éléments où la politique est p=reject seront autorisés à passer par ce chemin. Sur le second chemin, nous configurons le filtre inverse :

Notez l'opérateur « Not equal to ».

Configurons d'abord le second chemin puisqu'il est le plus simple. Ici, nous n'avons pas besoin de mettre à jour la politique, nous allons simplement réécrire dans la ligne qu'aucune mise à jour n'était nécessaire. Clonez le module Update row et faites-le glisser vers le second chemin, modifiez-le pour le configurer comme ceci :

Rappelez-vous, la colonne D est notre champ « Update status code ».

Tournons maintenant notre attention vers le premier chemin, où nous effectuerons un appel de mise à jour vers l'API OnDMARC. Au lieu de configurer un nouveau module HTTP à partir de zéro, clonez et renommez le premier, puis faites-le glisser vers le chemin. Les chemins devraient ressembler à ceci :

Nous devons maintenant modifier l'appel API car nous ne voulons plus obtenir les paramètres actuels, mais plutôt pousser de nouveaux paramètres. Nous utiliserons le même endpoint API mais au lieu d'un appel GET, nous utiliserons un appel PATCH, avec quelques informations supplémentaires dans le body pour spécifier les paramètres modifiés que nous souhaitons. Configurez-le comme suit :

N'oubliez pas de changer la méthode en PATCH, de conserver les mêmes en-têtes d'autorisation, et d'inclure ce qui suit dans le contenu ou le body de la requête :

Cela met à jour la politique de sous-domaine du domaine en question, en laissant tout le reste inchangé.

Ajoutons maintenant une dernière écriture de confirmation vers Google Sheets. Clonez, renommez, et faites glisser le module Google Sheets « Update a Row » depuis le chemin ci-dessous, et configurez-le comme ceci :

Cela écrira le code de statut de la réponse dans la colonne D, et si le statut est un succès (code 200), alors la valeur mise à jour (« reject ») sera écrite dans la colonne E, sinon elle sera laissée vide.

Le scénario complet devrait ressembler à ceci :

Exécutons-le !

Si tout est configuré correctement, les domaines en reject devraient suivre la route 1, et ceux qui ne sont pas en reject seront dirigés vers la route 2. Et voici le résultat dans Google Sheets, parfait :

Voici un excellent exemple de cas d'usage réel de l'API OnDMARC. Nous avons vu comment n'importe qui peut l'utiliser avec un logiciel de tableur comme Google Sheets ou Microsoft Office 365 comme feuille de contrôle, et Make ou Zapier comme outil d'automatisation pour effectuer les appels API. Dans cet exemple, nous avons utilisé l'API pour mettre à jour de manière conditionnelle les paramètres Dynamic DMARC pour une série de domaines, mais toute autre action est également possible. Pour trouver des idées, vous pouvez consulter la documentation de l'API OnDMARC ou simplement vous rappeler que tout ce que vous pouvez faire manuellement dans l'interface, vous pouvez probablement aussi trouver un endpoint API correspondant pour l'orchestrer automatiquement.