Aller au contenu principal

Guide d’intégration

Blocklist AdGuard Home de domaines malveillants, en liste de blocage DNS authentifiée

AdGuard Home récupère ses listes avec le client HTTP de Go, qui transmet en HTTP Basic les identifiants placés dans l’URL : la liste isMalicious complète se charge. Réglez la mise à jour sur 12 heures pour suivre les régénérations.

Aucune carte bancaire requise · Clé API gratuite

Chemin des données
  1. isMalicious

    api.ismalicious.com

    blocklist-domains-critical-adguard.txt

    Régénérée toutes les 12 h

    1. Relais

      Étape 6

      Garder la clé hors d’AdGuard Home (facultatif)

  2. AdGuard Home

    Étape 3

    L’ajouter en liste personnalisée

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.

ListeEntréesRégénéréeOffres
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 millionstoutes les 12 hBasic, 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 000toutes les 12 hBasic, Pro et Enterprise
blocklist-domains-ransomware-adguard.txtDomaines de la catégorie ransomware, quel que soit leur niveau.environ 3 600toutes les 12 hBasic, 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 millionstoutes les 12 hBasic, 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.

Comparer les offres

Ce que renvoie un téléchargementHTTP

GET https://api.ismalicious.com/blocklist/download/blocklist-domains-critical-adguard.txt

Liste complète ou échantillon de 10 %

ChampBasic, Pro et EnterpriseFree
X-Blocklist-Version:fulllite
X-Blocklist-Percentage:10010
Total entries:<COUNT><COUNT> (Lite Version - 10% of <TOTAL>)

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

  1. 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 %.
  2. 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. Utilisez api.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.txt
  3. L’ajouter en liste personnalisée

    Filtres › Listes de blocage DNS › Ajouter liste de blocage › Ajouter une liste personnalisée. Saisissez le nom isMalicious 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.
  4. 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.
  5. Ou passer par un script (facultatif)

    L’API /control prend 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é. Dans AdGuardHome.yaml, fusionnez l’extrait avec les clés filters et filtering existantes, AdGuard Home arrêté : une seconde clé filters ou filtering l’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: 12
  6. Garder 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

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 count du 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 filter dans 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.
Vérificationssh
# 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 -12

Dé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.txt pè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.

Commencer

Prêt à commencer ?

Aucune carte bancaire requise · Clé API gratuite