Référence Développeur

Chercheur de Sous-domaines

Consultez la documentation de l'API Chercheur de Sous-domaines, ses paramètres de requête, les champs de réponse, les exemples de code et la gestion des erreurs pour les intégrations DomScan.

Chercheur de Sous-domaines

Renvoie un ensemble au mieux d’indices publics sur les noms d’hôte. Le paramètre sources=ct sélectionne le pipeline de compatibilité, qui interroge d’abord crt.sh et peut se rabattre sur HackerTarget, ThreatMiner, la Wayback Machine et CertSpotter. DomScan ne recherche pas de noms par force brute et ne parcourt pas le site cible. Le résultat n’est donc pas un inventaire complet. Les échecs en mode cache uniquement renvoient HTTP 202 et les échecs de toutes les sources renvoient HTTP 503. Les crédits sont remboursés dans les deux cas.

GET /v1/subdomains

Paramètres de Requête

Paramètre	Type	Description
domain requis	string	Domaine racine pour lequel trouver les sous-domaines (par exemple, "github.com")
prefer_cache optionnel	boolean token	Sert uniquement les résultats en cache. Si aucun cache frais ou ancien n’existe, l’API renvoie 202, lance une actualisation en arrière-plan et rembourse les crédits de la requête. Valeurs acceptées: true, false, 1, 0, yes et no. Valeur par défaut: false.
sources optionnel	string	Sélecteur de compatibilité. Seul `ct` est accepté. Il lance le pipeline de découverte passive, mais chaque résultat indique le fournisseur de l’indice: `crtsh`, `hackertarget`, `threatminer`, `wayback` ou `certspotter`. Les anciennes entrées en cache peuvent indiquer `ct`.
verify optionnel	boolean token	Vérifie par DNS uniquement les noms déjà sélectionnés pour la réponse. La vérification ne découvre pas d’autres noms. Valeurs acceptées: `true`, `false`, `1`, `0`, `yes` et `no`. Valeur par défaut: `false`.
include_wildcards optionnel	boolean token	Renvoie les indices de certificats wildcard dans un tableau `wildcards` séparé. Les wildcards ne sont pas mélangés aux résultats de noms d’hôte concrets. Valeurs acceptées: `true`, `false`, `1`, `0`, `yes` et `no`. Valeur par défaut: `false`.
limit optionnel	integer	Nombre maximal d’entrées de noms d’hôte concrets à renvoyer. Saisissez un entier compris entre 1 et 2000. Valeur par défaut: 500.

Cas d'utilisation

Mappage de la surface d'attaque et audits de sécurité
Examiner les noms d’hôte potentiellement oubliés ou issus du shadow IT
Diligence raisonnable technique pré-acquisition
Analyse concurrentielle de l'infrastructure
Reconnaissance de programme de bounty sur les bugs

Champs de Réponse

Champ	Description
`subdomains[].name`	Nom d’hôte renvoyé. Le domaine apex peut apparaître si une source l’inclut.
`subdomains[].source`	Fournisseur de l’indice. Les valeurs possibles sont crtsh, hackertarget, threatminer, wayback, certspotter et ct pour les anciennes entrées en cache.
`subdomains[].first_seen`	Pour les indices de crt.sh et CertSpotter, première valeur not-before valide du certificat trouvée pour le nom d’hôte. Les sources passives de secours renvoient null, car elles ne fournissent pas de date de certificat comparable.
`subdomains[].verified`	true uniquement lorsque verify est activé et que la requête DNS du nom d’hôte renvoyé trouve un enregistrement A ou CNAME. Sinon, false.
`subdomains[].dns_records`	Enregistrements A ou CNAME issus de la vérification facultative du nom d’hôte renvoyé, ou null. Ce champ n’ajoute aucun nom au résultat.
`summary.total_found`	Nombre total d’entrées de noms d’hôte concrets trouvées avant la limite de la réponse, domaine apex compris si une source l’inclut.
`summary.verified_count`	Nombre de noms d’hôte renvoyés pour lesquels la vérification DNS facultative a trouvé un enregistrement A ou CNAME.

Codes de Statut HTTP

Codes de Statut HTTP	Description
`200` OK	Requête réussie
`202` Accepté	Absence de cache de sous-domaines en mode cache uniquement acceptée pour une actualisation en arrière-plan. Aucun crédit n’est facturé; réessayez après le délai Retry-After.
`400` Requête incorrecte	Paramètres invalides
`402` Paiement requis	Crédits insuffisants pour exécuter cette requête.
`503` Service indisponible	Le service amont est indisponible ou limite temporairement les requêtes.
`504` Délai d’attente de la passerelle dépassé	La requête amont a expiré.

Exemple de Requête

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&sources=ct&include_wildcards=yes&limit=100"

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&sources=ct&verify=yes&limit=50"

curl -H "X-API-Key: your-api-key" "https://domscan.net/v1/subdomains?domain=example.com&prefer_cache=1"

import requests

domscan = requests.Session()
domscan.headers.update({"X-API-Key": "your-api-key"})

response = domscan.get(
    "https://domscan.net/v1/subdomains",
    params={
        "domain": "example.com",
        "sources": "ct",
        "verify": "yes",
        "include_wildcards": "yes",
        "limit": 100
    }
)
data = response.json()

print(f"Returned {data['summary']['returned']} hostname entries")
print(f"Verified: {data['summary']['verified_count']}")

live_subs = [s for s in data['subdomains'] if s['verified']]
for sub in live_subs[:10]:
    print(f"  {sub['name']}")

const domscanFetch = (url, options = {}) =>
  fetch(url, {
    ...options,
    headers: { ...options.headers, "X-API-Key": "your-api-key" },
  });

const response = await domscanFetch(
  'https://domscan.net/v1/subdomains?' + new URLSearchParams({
    domain: 'example.com',
    sources: 'ct',
    verify: 'yes',
    include_wildcards: 'yes',
    limit: '100'
  })
);
const data = await response.json();

console.log(`Returned ${data.summary.returned} hostname entries`);
console.log(`Verified: ${data.summary.verified_count}`);

data.subdomains
  .filter(s => s.verified)
  .forEach(s => console.log(`  ${s.name}`));

Exemple de Réponse

{
  "domain": "example.com",
  "subdomains": [
    {
      "name": "api.example.com",
      "source": "crtsh",
      "first_seen": "2025-01-15T00:00:00Z",
      "verified": true,
      "dns_records": {
        "A": ["192.0.2.10"],
        "CNAME": null
      }
    }
  ],
  "wildcards": [
    {
      "pattern": "*.example.com",
      "source": "crtsh",
      "first_seen": "2024-11-20T00:00:00Z"
    }
  ],
  "summary": {
    "total_found": 1,
    "returned": 1,
    "verified_count": 1,
    "unverified_count": 0,
    "sources_used": ["crtsh"],
    "apex_included": false,
    "wildcard_suppressed_count": 1,
    "wildcard_returned_count": 1
  },
  "intelligence_summary": {
    "data_sources": ["crtsh"],
    "source_count": 1,
    "cache_status": "live",
    "returned_count": 1,
    "total_found": 1,
    "truncated": false,
    "limit": 100,
    "verification_requested": true,
    "include_wildcards": true,
    "verified_count": 1,
    "verified_ratio": 1,
    "live_dns_record_count": 1,
    "apex_included": false,
    "wildcard_suppressed_count": 1,
    "wildcard_returned_count": 1,
    "first_seen_oldest": "2025-01-15T00:00:00Z",
    "first_seen_newest": "2025-01-15T00:00:00Z",
    "warning_count": 0
  },
  "meta": {
    "query_time_ms": 184,
    "cached": false
  }
}

202 Accepté

{
  "status": "pending",
  "code": "CACHE_MISS_REFRESH_QUEUED",
  "message": "Try again in a moment",
  "domain": "example.com",
  "retry_after": 30,
  "credits_charged": 0,
  "billing_status": "not_charged",
  "request_id": "m8abc12-x9y8"
}

POST /v1/subdomains/bulk

Paramètres du Corps

Paramètre	Type	requis
domains	string[]	requis
verify	boolean	optionnel
include_wildcards	boolean	optionnel
limit	integer	optionnel

Champs de Réponse

Champ	Type
`results[]`	unknown[]
`meta`	object
`meta.total`	integer
`meta.succeeded`	integer
`meta.failed`	integer
`meta.max_items`	integer
`meta.credits_per_item`	integer
`meta.duration_ms`	integer

Exemple de Requête

curl -X POST "https://domscan.net/v1/subdomains/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "domains": [
    "example.com",
    "cloudflare.com"
  ],
  "verify": false,
  "limit": 500
}'

Exemple de Réponse

{
  "results": [
    null
  ],
  "meta": {
    "total": 1,
    "succeeded": 1,
    "failed": 1,
    "max_items": 10,
    "credits_per_item": 1,
    "duration_ms": 1
  }
}