Guide d’intégration
Blocklist AdGuard Home de domaines malveillants, en liste de blocage DNS authentifiée
Aucune carte bancaire requise · Clé API gratuite
Sur cette page08
Ce que vous obtenez
AdGuard Home filtre des noms : seules les listes de domaines s’appliquent. La forme adblock, ||domaine^, bloque chaque domaine et ses sous-domaines ; chargez une seule forme par niveau.
| Liste | Entrées | Régénérée | Offres |
|---|---|---|---|
| blocklist-domains-critical-adguard.txtPar défaut. Domaines signalés par 6 sources de menaces ou plus, ou par 3 ou plus avec une catégorie critique, sous-domaines compris. | environ 2 millions | toutes les 12 h | Basic, Pro et Enterprise |
| blocklist-domains-c2-adguard.txtDomaines de commande et contrôle (C2) signalés par des trackers de C2, quel que soit leur niveau. | environ 22 000 | toutes les 12 h | Basic, Pro et Enterprise |
| blocklist-domains-ransomware-adguard.txtDomaines de la catégorie ransomware, quel que soit leur niveau. | environ 3 600 | toutes les 12 h | Basic, Pro et Enterprise |
| blocklist-domains-critical.txtLe niveau critical en syntaxe domaines seuls : noms exacts, sans sous-domaines. À charger à la place de la forme adblock, pas en plus. | environ 2 millions | toutes les 12 h | Basic, Pro et Enterprise |
Nombres arrondis d’après la génération du ; chaque liste est régénérée toutes les 12 heures. Les chiffres du jour sont publics et ne demandent aucune clé.
Ce que reçoit chaque offre
- FreeCompte Free, ou aucune clé : les premiers 10 % de chaque liste, signalés par
X-Blocklist-Version: lite. - Basic, Pro et EnterpriseBasic, Pro et Enterprise : toutes les listes, complètes.
- Pro et EnterpriseCollections TAXII 2.1, pour les plateformes qui lisent les indicateurs STIX : Pro et Enterprise.
GET https:/
Liste complète ou échantillon de 10 %
| Champ | Basic, Pro et Enterprise | Free |
|---|---|---|
X-Blocklist-Version: | full | lite |
X-Blocklist-Percentage: | 100 | 10 |
Total entries: | <COUNT> | <COUNT> |
Premières lignes du fichier
! IsMalicious.com Blocklist - Domains (Critical)
! Format: AdGuard
! Generated: <BUILD_TIME>
! Total entries: <COUNT>
! Update frequency: every 12 hours
! Category: All
! Threat level: Critical
! Website: https://ismalicious.com
! © <YEAR> IsMalicious (compilation). Licensed to the downloading account under https://ismalicious.com/terms; redistribution of the compilation prohibited. Third-party entries remain under their providers' licences — see https://ismalicious.com/sources.
!Les valeurs entre chevrons sont fixées à chaque génération.
Prérequis
- AdGuard Home v0.107.0 ou ultérieur.
- Les identifiants d’administration d’AdGuard Home, pour l’API ou le fichier de configuration.
- Une clé API et son secret isMalicious, dans Compte › Accès API.
- Un accès HTTPS sortant (TCP 443) en IPv4 depuis AdGuard Home vers
api.ismalicious.com, qui n’a pas d’adresse IPv6.
Mise en place
Copier la clé API et le secret
Ouvrez Compte › Accès API et copiez la Clé API et le Secret API. La liste complète demande une offre Basic, Pro ou Enterprise ; une clé Free charge l’échantillon de 10 %.Construire l’URL de la liste
Placez la clé, deux-points et le secret devant l’hôte, suivis de@. Clés et secrets sont des UUID : aucun encodage n’est nécessaire. Utilisezapi.ismalicious.com: le frontal d’ismalicious.com refuse certaines sources avec une erreur 403.URL de la listeURL https://<API_KEY>:<API_SECRET>@api.ismalicious.com/blocklist/download/blocklist-domains-critical-adguard.txtL’ajouter en liste personnalisée
Filtres › Listes de blocage DNS › Ajouter liste de blocage › Ajouter une liste personnalisée. Saisissez le nomisMalicious critical, collez l’URL dans Entrez une URL ou un chemin absolu de la liste, puis Enregistrer. AdGuard Home télécharge aussitôt la liste et affiche son nombre de règles.Régler la mise à jour sur 12 heures
Paramètres › Paramètres généraux › Intervalle de mise à jour des filtres : 12 heures. Les choix vont de désactivé à 7 jours ; le réglage s’enregistre dès qu’il change. La valeur par défaut est d’un jour, et l’intervalle vaut pour toutes les listes chargées.Ou passer par un script (facultatif)
L’API/controlprend la même liste et le même intervalle avec les identifiants d’administration ; lancez-la sur l’hôte d’AdGuard Home, où l’interface répond en HTTP simple tant que le chiffrement n’est pas configuré. DansAdGuardHome.yaml, fusionnez l’extrait avec les clésfiltersetfilteringexistantes, AdGuard Home arrêté : une seconde cléfiltersoufilteringl’empêche de démarrer, et il écrase les changements faits pendant son exécution.API d’AdGuard Homesh # On the AdGuard Home host: the interface is plain HTTP unless encryption is # configured. curl asks for the admin password, so it stays out of ps. AGH=http://127.0.0.1:<ADMIN_PORT> # body.json (mode 600), written with an editor, holds the list with the key: # {"name":"isMalicious critical","url":"https://<API_KEY>:<API_SECRET>@api.ismalicious.com/blocklist/download/blocklist-domains-critical-adguard.txt","whitelist":false} curl -fsS -u '<AGH_USER>' -H 'Content-Type: application/json' \ -X POST "$AGH/control/filtering/add_url" --data @body.json curl -fsS -u '<AGH_USER>' -H 'Content-Type: application/json' \ -X POST "$AGH/control/filtering/config" --data '{"enabled":true,"interval":12}'AdGuardHome. yaml (extrait à fusionner)yaml # Excerpt to MERGE into the existing keys, with AdGuard Home stopped: # never add a second filters: or filtering: key; keep filter ids unique. # v0.107.36 and older: filters_update_interval sits under dns:. filters: # ...your existing entries... - enabled: true url: https://<API_KEY>:<API_SECRET>@api.ismalicious.com/blocklist/download/blocklist-domains-critical-adguard.txt name: isMalicious critical id: 1700000001 filtering: # ...existing keys stay; change only: filters_update_interval: 12Garder la clé hors d’AdGuard Home (facultatif)
- AdGuard Home stocke l’URL en clair dans
AdGuardHome.yaml, l’affiche dans le tableau des listes et l’écrit quand une mise à jour échoue. - Pour l’éviter, récupérez la liste avec le script ci-dessous, réservé à root, qui refuse une erreur, un contenu qui n’est pas une liste, l’échantillon de 10 % et un fichier dont le nombre d’entrées diffère de son en-tête, et ajoutez le chemin absolu du fichier à la place de l’URL.
- AdGuard Home relit le fichier quand la liste arrive à échéance, ou sur Vérifier les mises à jour.
- Depuis la v0.107.53, le fichier doit se trouver dans un répertoire couvert par
filtering.safe_fs_patterns:userfilters/dans le répertoire de travail pour une configuration créée par l’assistant d’installation,data/userfilters/pour une configuration migrée depuis une version antérieure.
Créer le fichier, réservé à rootsh install -d -m 700 /etc/ismalicious [ -e /etc/ismalicious/netrc ] || install -m 600 /dev/null /etc/ismalicious/netrc chmod 600 /etc/ismalicious/netrc # Then write the three lines below into it with an editor, unless it holds them already./ etc/ ismalicious/ netrcnetrc machine api.ismalicious.com login <API_KEY> password <API_SECRET>/ usr/ local/ sbin/ ismalicious-fetch. shsh #!/bin/sh # Runs as root every 12 hours. /etc/ismalicious/netrc (mode 600) holds the key. # DIR must match filtering.safe_fs_patterns; on Docker, use the host directory # mounted on /opt/adguardhome/work, plus /userfilters. set -eu NETRC=/etc/ismalicious/netrc DIR=/opt/AdGuardHome/userfilters FILE=blocklist-domains-critical-adguard.txt # fetch_list LIST OUT: download one list to OUT and check it. # On any failure OUT is removed and the function returns 1. fetch_list() { if ! code=$(curl --silent --show-error --fail --netrc-file "$NETRC" \ --proto '=https' --max-time 300 --retry 2 \ --output "$2" --write-out '%{http_code}' "https://api.ismalicious.com/blocklist/download/$1"); then rm -f "$2"; echo "$1: download failed" >&2; return 1 fi if [ "$code" != 200 ]; then rm -f "$2"; echo "$1: HTTP $code" >&2; return 1 fi if ! head -n 1 "$2" | grep -q '^[#!] IsMalicious.com Blocklist'; then rm -f "$2"; echo "$1: not an isMalicious list" >&2; return 1 fi if grep -q 'Lite Version' "$2"; then rm -f "$2"; echo "$1: lite list received, check the API key and the plan" >&2 return 1 fi # Every entry ends with a newline, and one header counts them: refuse a # cut, doubled or empty file. if [ -n "$(tail -c 1 "$2")" ]; then rm -f "$2"; echo "$1: cut short, no final newline" >&2; return 1 fi if [ "$(grep -c '^[#!] Total entries:' "$2")" != 1 ]; then rm -f "$2"; echo "$1: not one Total entries line" >&2; return 1 fi total=$(sed -n 's/^[#!] Total entries: \([0-9,]*\)$/\1/p' "$2" | tr -d ,) got=$(grep -c '^[^#!]' "$2" || true) if [ -z "$total" ] || [ "$total" = 0 ] || [ "$got" != "$total" ]; then rm -f "$2"; echo "$1: $got entries, the header says ${total:-none}" >&2 return 1 fi } mkdir -p "$DIR" tmp=$(mktemp "$DIR/.$FILE.XXXXXX") trap 'rm -f "$tmp"' EXIT fetch_list "$FILE" "$tmp" chmod 644 "$tmp" mv -f "$tmp" "$DIR/$FILE" # Schedule it in /etc/cron.d/ismalicious-adguard: # 7 5,17 * * * root /usr/local/sbin/ismalicious-fetch.sh # List path in AdGuard Home: /opt/AdGuardHome/userfilters/blocklist-domains-critical-adguard.txt- AdGuard Home stocke l’URL en clair dans
Vérifier le résultat
- Filtres › Listes de blocage DNS affiche le Nombre des règles et la Dernière mise à jour de la liste.
- Le nombre de règles correspond au
countdu fichier simple du même niveau dans /blocklist/stats, à une régénération près ; les statistiques ne listent que les fichiers simples. Environ un dixième, c’est l’échantillon de 10 %. - La Dernière mise à jour ne prouve pas la réussite : la date bouge aussi sur un échec quand une autre liste s’est mise à jour au même passage. Cherchez plutôt les erreurs
updating filterdans le journal. - Filtres › Règles de filtrage personnalisées › Vérification du filtrage, avec un domaine de la liste, nomme la liste et la règle qui l’a bloqué.
- Dans le Journal des requêtes, les requêtes bloquées indiquent le nom de la liste.
# Rules count and last update of every list (curl asks for the password):
curl -fsS -u '<AGH_USER>' "http://127.0.0.1:<ADMIN_PORT>/control/filtering/status"
# The list itself, as root with the netrc file: no "Lite Version" in its header.
sudo curl -sS --netrc-file /etc/ismalicious/netrc "https://api.ismalicious.com/blocklist/download/blocklist-domains-critical-adguard.txt" | head -12Dépannage
« got status code 401, want 200 »
La clé ou le secret est faux ou incomplet. Le message apparaît à l’ajout de la liste, et sous forme de ligne updating filter dans le journal lors d’une mise à jour planifiée ; les deux affichent l’URL, identifiants compris : effacez-les des journaux que vous partagez. La copie précédente reste active. Le corps de la réponse indique « Blocklist not found or empty » ; fiez-vous au code HTTP. Recopiez les deux valeurs depuis Compte › Accès API.
Seules 10 % des règles environ se chargent
L’URL ne contient pas d’identifiants, ou l’offre est Free ou interrompue : un abonnement impayé, en retard de paiement, annulé, incomplet ou suspendu compte comme Free. Comparez le nombre de règles avec /blocklist/stats.
Le script de copie locale affiche « entries, the header says », « cut short, no final newline » ou « not one Total entries line »
Le fichier était vide, tronqué ou n’était pas une des listes, comme quand un proxy ou un portail captif répond. Le script garde la copie précédente et sort en erreur ; l’exécution suivante réessaie.
Délai dépassé ou erreur 502
Un téléchargement qui prend plus de 30 secondes de notre côté finit en délai dépassé ou en 502 : prenez une liste par niveau ou par catégorie du tableau.
« cannot read more than 268435456 bytes »
AdGuard Home v0.107.78 et ultérieur refusent une liste plus grande que filtering.max_http_size, 256 Mo par défaut : l’ajout échoue, ou une mise à jour échoue et la copie précédente reste. Prenez un niveau plus petit plutôt que de relever la limite. Les versions antérieures n’ont pas de plafond.
503 Service Unavailable
La liste est en cours de première génération, et la réponse porte Retry-After: 600. AdGuard Home l’ignore et garde la copie précédente.
La liste ne se recharge pas une fois la cause corrigée
Si d’autres listes se sont mises à jour au même passage, AdGuard Home marque la nôtre comme tentée et attend un intervalle complet. Si toutes les listes dues échouent, il double son intervalle de vérification à partir d’une heure, sans plafond : 2 heures, 4, 8… Cliquez sur Vérifier les mises à jour une fois la cause corrigée.
« data is HTML, not plain text »
Une page a répondu par un 200 à la place de la liste : un portail captif, un proxy ou une page d’inspection TLS. Un refus du frontal d’un miroir ismalicious.com donne plutôt un 403 (« got status code 403, want 200 »). Utilisez api.ismalicious.com, et exemptez-le de l’inspection TLS.
« likely binary character »
Les lignes d’en-tête n’y sont pour rien : AdGuard Home saute les lignes # et !. Un caractère de contrôle signale un téléchargement corrompu : relancez Vérifier les mises à jour.
x509: certificate signed by unknown authority
AdGuard Home vérifie toujours le certificat. Mettez à jour le magasin de certificats du système (sur les routeurs Entware, /opt/etc/ssl/certs), vérifiez l’horloge et exemptez api.ismalicious.com de l’inspection TLS.
« net/url: invalid userinfo » ou « bad http(s) url »
Des chevrons restés du modèle donnent « net/url: invalid userinfo » : retirez-les, ainsi que tout espace. « bad http(s) url » signale une erreur de schéma, ou une adresse file:// : une liste locale prend un chemin absolu simple.
Limites
- AdGuard Home conserve l’URL, identifiants compris, dans
AdGuardHome.yaml, dans le tableau des listes et dans l’état de ses filtres. Il l’écrit dans le journal quand une mise à jour échoue, et dans le message d’erreur quand un ajout échoue. La variante en fichier local de la dernière étape l’évite. - Un seul intervalle couvre toutes les listes : 12 heures s’applique aussi aux autres listes chargées.
- Seule la forme adblock bloque les sous-domaines ; les formes simple et hosts bloquent les noms exacts. Aucune entrée générique n’est servie, et AdGuard Home n’en a pas besoin :
||domaine^couvre les sous-domaines. - AdGuard Home v0.107.78 et ultérieur refusent une liste au-delà de 256 Mo (
filtering.max_http_size).blocklist-domains-all.txtpèse environ 386 Mo sous forme simple : ne la chargez pas. - AdGuard Home n’est pas un pare-feu : il peut bloquer une réponse DNS selon son adresse, mais une ligne d’IP seule dans une liste est un motif, pas une adresse à bloquer. Ne chargez pas les listes
blocklist-ips-*; gardez-les pour un pare-feu. - L’échantillon de 10 % est le premier dixième d’un fichier non trié, pas le dixième le plus risqué.
- Ni RPZ ni CIDR ne sont servis ; AdGuard Home n’en a pas besoin pour des listes de domaines.
Questions fréquentes
AdGuard Home peut-il envoyer une clé API pour une blocklist ?
Oui. Placez la clé et le secret devant l’hôte dans l’URL de la liste, séparés par deux-points et suivis de @. AdGuard Home récupère la liste avec le client HTTP de Go, qui les envoie en HTTP Basic. L’URL est stockée en clair dans AdGuardHome.yaml ; un fichier local récupéré par un script garde la clé à l’écart.
Quel fichier bloque les sous-domaines ?
La forme -adguard.txt. AdGuard Home lit ses règles ||domaine^ comme le domaine et tous ses sous-domaines. Les formes simple et hosts ne bloquent que les noms exacts.
À quelle fréquence AdGuard Home recharge-t-il la liste ?
À son intervalle de mise à jour des filtres, un jour par défaut, qui vaut pour toutes les listes. Réglez-le sur 12 heures : les listes sont régénérées toutes les 12 heures, et recharger plus souvent retélécharge le même fichier.
AdGuard Home peut-il utiliser les listes d’IP ?
Ne chargez que les listes de domaines. AdGuard Home n’est pas un pare-feu : une ligne d’IP seule dans une liste est un motif, pas une adresse à bloquer. Bloquez les adresses IP sur un pare-feu.
Que charge un compte gratuit dans AdGuard Home ?
Les premiers 10 % de chaque liste. AdGuard Home les charge sans erreur : comparez donc le nombre de règles au nombre publié. La liste complète demande une offre Basic, Pro ou Enterprise.
À voir aussi
Domaines malveillants en adlist authentifiée
Toutes les listes, niveaux et catégories
Collections TAXII 2.1 pour SIEM et TIP
Authentification, endpoints et limites
Vérifier un domaine avant de le bloquer
Commencer
Prêt à commencer ?
Aucune carte bancaire requise · Clé API gratuite