개발자 참고자료

하위 도메인 파인더 API 문서

하위 도메인 파인더 API 문서: Certificate Transparency (CT) 로그를 사용해 하위 도메인을 찾습니다. prefer_cache=1로 캐시 결과를 폴링하면, 콜드 미스는 HTTP 202를 반환하고 백그라운드 새로고침을 큐에 넣으며 크레딧을 소비하지 않습니다.

하위 도메인 파인더

Certificate Transparency (CT) 로그를 사용해 하위 도메인을 찾습니다. prefer_cache=1로 캐시 결과를 폴링하면, 콜드 미스는 HTTP 202를 반환하고 백그라운드 새로고침을 큐에 넣으며 크레딧을 소비하지 않습니다.

GET /v1/subdomains

쿼리 매개변수

매개변수	유형	설명
domain 필수	string	하위 도메인을 찾을 루트 도메인 (예: "github.com")
prefer_cache 선택 사항	boolean	캐시된 결과만 제공합니다. 신선한 캐시나 오래된 캐시가 없으면 API는 202를 반환하고 백그라운드 새로고침을 큐에 넣으며 0 크레딧을 청구합니다.
sources 선택 사항	string	쉼표로 구분한 데이터 소스입니다. 현재는 `ct` (Certificate Transparency)만 허용됩니다.
verify 선택 사항	boolean	각 하위 도메인이 DNS를 통해 해결되는지 확인 (느림이지만 더 정확함). 기본값: `false`
limit 선택 사항	number	반환할 최대 하위 도메인 수. 기본값: 500, 최대: 2000

사용 사례

공격 표면 매핑 및 보안 감시
잊혀진 또는 섀도우 IT 하위 도메인 발견
인수 전 기술 실사
인프라의 경쟁 분석
버그 바운티 정찰

응답 필드

필드	설명
`subdomains[].name`	발견된 하위 도메인 호스트명
`subdomains[].source`	데이터 소스 (예: "ct")
`subdomains[].first_seen`	이 하위 도메인이 처음 관찰된 시간
`subdomains[].verified`	DNS 해석이 확인되었는지 여부 (verify=true인 경우)
`subdomains[].dns_records`	발견된 DNS 레코드 (verify=true인 경우)
`summary.total_found`	제한 전 발견된 총 하위 도메인 수
`summary.verified_count`	확인된 (활성) 하위 도메인 수

HTTP 상태 코드

HTTP 상태 코드	설명
`200` 성공	요청 성공
`202` 수락됨	캐시 전용 하위 도메인 요청에서 캐시가 없어 백그라운드 새로고침으로 수락되었습니다. 크레딧은 차감되지 않으며 Retry-After 지연 후 다시 시도하세요.
`400` 잘못된 요청	잘못된 매개변수
`402` 결제 필요	이 요청을 실행할 크레딧이 부족합니다.
`503` 서비스 이용 불가	업스트림 서비스를 사용할 수 없거나 일시적으로 속도 제한 중입니다.
`504` 게이트웨이 시간 초과	업스트림 조회가 시간 초과되었습니다.

예제 요청

# Find subdomains (fast, from CT logs)
curl "https://domscan.net/v1/subdomains?domain=github.com&limit=100"

# Find and verify subdomains (slower, confirms DNS resolution)
curl "https://domscan.net/v1/subdomains?domain=github.com&verify=true&limit=50"

curl "https://domscan.net/v1/subdomains?domain=github.com&prefer_cache=1"

import requests

# Enumerate subdomains with verification
response = requests.get(
    "https://domscan.net/v1/subdomains",
    params={
        "domain": "github.com",
        "verify": "true",
        "limit": 100
    }
)
data = response.json()

print(f"Found {data['summary']['total_found']} subdomains")
print(f"Verified: {data['summary']['verified_count']}")

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

const response = await fetch(
  'https://domscan.net/v1/subdomains?' + new URLSearchParams({
    domain: 'github.com',
    verify: 'true',
    limit: '100'
  })
);
const data = await response.json();

console.log(`Found ${data.summary.total_found} subdomains`);
console.log(`Verified: ${data.summary.verified_count}`);

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

예제 응답

{
  "domain": "github.com",
  "subdomains": [
    {
      "name": "api.github.com",
      "source": "ct",
      "first_seen": "2024-01-15T00:00:00Z",
      "verified": true,
      "dns_records": ["A 140.82.112.5"]
    },
    {
      "name": "gist.github.com",
      "source": "ct",
      "first_seen": "2024-02-01T00:00:00Z",
      "verified": true,
      "dns_records": ["CNAME github.github.io"]
    },
    {
      "name": "education.github.com",
      "source": "ct",
      "first_seen": "2023-06-10T00:00:00Z",
      "verified": true,
      "dns_records": ["A 185.199.108.153"]
    }
  ],
  "summary": {
    "total_found": 847,
    "returned": 3,
    "verified_count": 3,
    "unverified_count": 0,
    "sources_used": ["ct"]
  },
  "meta": {
    "query_time_ms": 1250,
    "cached": false
  }
}

202 수락됨

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