Entwickler-Referenz

Subdomain-Finder

Entdecken Sie die API-Dokumentation zu Subdomain-Finder, Anfrageparameter, Antwortfelder, Codebeispiele und Fehlerbehandlung für DomScan-Integrationen.

Subdomain-Finder

Liefert eine Best-Effort-Auswahl öffentlicher Hostnamenhinweise. Der Parameter sources=ct wählt die Kompatibilitätspipeline, die zuerst crt.sh abfragt und auf HackerTarget, ThreatMiner, die Wayback Machine und CertSpotter ausweichen kann. DomScan errät keine Namen per Brute Force und durchsucht die Zielwebsite nicht. Das Ergebnis ist daher kein vollständiges Inventar. Cache-only-Fehltreffer geben HTTP 202 zurück, Ausfälle aller Quellen HTTP 503. In beiden Fällen werden die Credits erstattet.

GET /v1/subdomains

Abfrageparameter

Parameter	Typ	Beschreibung
domain erforderlich	string	Root-Domain zur Suche nach Subdomains (z. B. "github.com")
prefer_cache optional	boolean token	Nur gecachte Ergebnisse ausliefern. Wenn kein frischer oder veralteter Cache vorhanden ist, gibt die API 202 zurück, startet eine Hintergrundaktualisierung und erstattet die Credits der Anfrage. Zulässige Werte: true, false, 1, 0, yes und no. Standard: false.
sources optional	string	Kompatibilitätsauswahl. Nur `ct` wird akzeptiert. Dieser Wert startet die passive Entdeckungspipeline, aber jedes Ergebnis nennt den Anbieter des Hinweises: `crtsh`, `hackertarget`, `threatminer`, `wayback` oder `certspotter`. Ältere Cache-Einträge können `ct` melden.
verify optional	boolean token	Prüft per DNS nur die Namen, die bereits für die Antwort ausgewählt wurden. Die Verifizierung entdeckt keine weiteren Namen. Zulässige Werte: `true`, `false`, `1`, `0`, `yes` und `no`. Standard: `false`.
include_wildcards optional	boolean token	Gibt Hinweise aus Wildcard-Zertifikaten in einem separaten `wildcards`-Array zurück. Wildcards werden nicht mit konkreten Hostnamenergebnissen vermischt. Zulässige Werte: `true`, `false`, `1`, `0`, `yes` und `no`. Standard: `false`.
limit optional	integer	Maximale Anzahl konkreter Hostnameneinträge in der Antwort. Geben Sie eine ganze Zahl von 1 bis 2000 ein. Standard: 500.

Anwendungsfälle

Angriffsflächen-Mapping und Sicherheitsprüfungen
Mögliche vergessene Hostnamen oder Shadow-IT-Hostnamen prüfen
Technische Due-Diligence vor Übernahme
Wettbewerbsanalyse der Infrastruktur
Bug-Bounty-Aufklärung

Antwort-Felder

Feld	Beschreibung
`subdomains[].name`	Zurückgegebener Hostname. Die Apex-Domain kann erscheinen, wenn eine Quelle sie einschließt.
`subdomains[].source`	Anbieter des Hinweises. Mögliche Werte sind crtsh, hackertarget, threatminer, wayback, certspotter sowie ct bei älteren Cache-Einträgen.
`subdomains[].first_seen`	Bei Hinweisen von crt.sh und CertSpotter der früheste gültige not-before-Wert eines Zertifikats für den Hostnamen. Einträge passiver Ausweichquellen geben null zurück, weil diese Quellen keinen vergleichbaren Zertifikatszeitpunkt liefern.
`subdomains[].verified`	true nur, wenn verify aktiviert ist und die DNS-Abfrage für den zurückgegebenen Hostnamen einen A- oder CNAME-Eintrag findet. Andernfalls false.
`subdomains[].dns_records`	A- oder CNAME-Einträge aus der optionalen Verifizierung des zurückgegebenen Hostnamens oder null. Dieses Feld fügt dem Ergebnis keine Namen hinzu.
`summary.total_found`	Gesamtzahl konkreter Hostnameneinträge vor dem Antwortlimit, einschließlich der Apex-Domain, wenn eine Quelle sie einschließt.
`summary.verified_count`	Anzahl der zurückgegebenen Hostnamen, für die bei der optionalen DNS-Verifizierung ein A- oder CNAME-Eintrag gefunden wurde.

HTTP-Statuscodes

HTTP-Statuscodes	Beschreibung
`200` OK	Anfrage erfolgreich
`202` Akzeptiert	Cache-only-Subdomain-Fehltreffer für eine Hintergrundaktualisierung akzeptiert. Es werden keine Credits berechnet; versuche es nach der Retry-After-Wartezeit erneut.
`400` Bad Request	Ungültige Parameter
`402` Zahlung erforderlich	Nicht genügend Credits für diese Anfrage.
`503` Dienst nicht verfügbar	Der Upstream-Dienst ist nicht verfügbar oder drosselt vorübergehend.
`504` Gateway-Zeitüberschreitung	Die Upstream-Abfrage hat das Zeitlimit überschritten.

Beispielanfrage

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}`));

Beispielantwort

{
  "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 Akzeptiert

{
  "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

Body-Parameter

Parameter	Typ	erforderlich
domains	string[]	erforderlich
verify	boolean	optional
include_wildcards	boolean	optional
limit	integer	optional

Antwort-Felder

Feld	Typ
`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

Beispielanfrage

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
}'

Beispielantwort

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