Ontwikkelaarsreferentie

Subdomeinfinder

Bekijk de API-documentatie voor Subdomeinfinder, aanvraagparameters, responsvelden, codevoorbeelden en foutafhandeling voor DomScan-integraties.

Subdomeinfinder

Geeft een best-effortverzameling van openbare aanwijzingen voor hostnamen terug. De parameter sources=ct selecteert de compatibiliteitspipeline, die eerst crt.sh bevraagt en kan uitwijken naar HackerTarget, ThreatMiner, de Wayback Machine en CertSpotter. DomScan raadt geen namen met brute force en crawlt de doelsite niet. Het resultaat is daarom geen volledige inventaris. Cache-only missers geven HTTP 202 terug en uitval van alle bronnen geeft HTTP 503 terug. Bij beide antwoorden worden de credits terugbetaald.

GET /v1/subdomains

Queryparameters

Parameter	Type	Beschrijving
domain vereist	string	Rootdomein om subdomeinen voor te vinden (bijv. "github.com")
prefer_cache optioneel	boolean token	Levert alleen gecachte resultaten. Als er geen verse of oude cache bestaat, geeft de API 202 terug, zet een achtergrondvernieuwing in de wachtrij en betaalt de credits van de aanvraag terug. Geaccepteerde waarden: true, false, 1, 0, yes en no. Standaard: false.
sources optioneel	string	Compatibiliteitsselector. Alleen `ct` wordt geaccepteerd. Deze waarde start de passieve ontdekkingspipeline, maar elk resultaat vermeldt de aanbieder van de aanwijzing: `crtsh`, `hackertarget`, `threatminer`, `wayback` of `certspotter`. Oudere cachevermeldingen kunnen `ct` melden.
verify optioneel	boolean token	Controleert via DNS alleen de namen die al voor het antwoord zijn geselecteerd. Verificatie ontdekt geen extra namen. Geaccepteerde waarden: `true`, `false`, `1`, `0`, `yes` en `no`. Standaard: `false`.
include_wildcards optioneel	boolean token	Geeft aanwijzingen uit wildcardcertificaten terug in een afzonderlijke `wildcards`-array. Wildcards worden niet met concrete hostnaamresultaten gemengd. Geaccepteerde waarden: `true`, `false`, `1`, `0`, `yes` en `no`. Standaard: `false`.
limit optioneel	integer	Maximaal aantal concrete hostnaamvermeldingen om terug te geven. Voer een geheel getal van 1 tot en met 2000 in. Standaard: 500.

Gebruikssituaties

Attack surface mapping en beveiligingsaudits
Mogelijk vergeten hostnamen of hostnamen van schaduw-IT beoordelen
Technische due diligence vóór aankoop
Concurrentieanalyse van infrastructuur
Bug bounty verkenning

Antwoordvelden

Veld	Beschrijving
`subdomains[].name`	Teruggegeven hostnaam. Het hoofddomein kan verschijnen als een bron dit opneemt.
`subdomains[].source`	Aanbieder van de aanwijzing. Mogelijke waarden zijn crtsh, hackertarget, threatminer, wayback, certspotter en ct voor oudere cachevermeldingen.
`subdomains[].first_seen`	Voor aanwijzingen van crt.sh en CertSpotter de vroegste geldige not-before-waarde van een certificaat die voor de hostnaam is gevonden. Passieve uitwijkbronnen geven null terug omdat ze geen vergelijkbaar certificaattijdstip leveren.
`subdomains[].verified`	true alleen wanneer verify is ingeschakeld en de DNS-query voor de teruggegeven hostnaam een A- of CNAME-record vindt. Anders false.
`subdomains[].dns_records`	A- of CNAME-records uit de optionele verificatie van de teruggegeven hostnaam, of null. Dit veld voegt geen namen aan het resultaat toe.
`summary.total_found`	Totaal aantal concrete hostnaamvermeldingen dat vóór de antwoordlimiet is gevonden, inclusief het hoofddomein als een bron dit opneemt.
`summary.verified_count`	Aantal teruggegeven hostnamen waarvoor de optionele DNS-verificatie een A- of CNAME-record vond.

HTTP-statuscodes

HTTP-statuscodes	Beschrijving
`200` OK	Aanvraag geslaagd
`202` Geaccepteerd	Cache-only subdomeinmisser geaccepteerd voor vernieuwing op de achtergrond. Er worden geen credits gerekend; probeer opnieuw na de Retry-After-vertraging.
`400` Ongeldig verzoek	Ongeldige parameters
`402` Betaling vereist	Niet genoeg credits om deze aanvraag uit te voeren.
`503` Service niet beschikbaar	De upstreamservice is niet beschikbaar of beperkt tijdelijk aanvragen.
`504` Gateway-time-out	De upstream-aanvraag heeft de tijdslimiet overschreden.

Voorbeeldverzoek

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

Voorbeeldantwoord

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

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

Lichaamsparameters

Parameter	Type	vereist
domains	string[]	vereist
verify	boolean	optioneel
include_wildcards	boolean	optioneel
limit	integer	optioneel

Antwoordvelden

Veld	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

Voorbeeldverzoek

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

Voorbeeldantwoord

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