kisa-whois-domain-batch
입력 레코드의 domain 컬럼 값으로 .kr·.한국 도메인 등록 정보를 일괄 조회합니다.
문법
옵션
- profile=STRING
- 필수 옵션. KISA WHOIS 접속 프로파일 식별자. 단일 프로파일만 허용하며, 쉼표로 여러 개를 지정할 수 없습니다. 예:
kisa_whois - locale=STRING
- 선택 옵션. 출력 언어.
ko또는en만 허용합니다. (기본값:ko) - pretty=BOOL
- 선택 옵션. 리스트 필드(
status,name_servers,name_server_ips)를 줄바꿈으로 구분된 텍스트로 출력합니다. (기본값:f)
입력 필드
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| domain | 문자열 | Y | 조회할 .kr·.한국 도메인. 예: example.kr |
출력 필드
입력 레코드의 기존 컬럼은 그대로 유지되며, 아래 필드가 병합됩니다.
| 필드 | 타입 | 이름 | 설명 |
|---|---|---|---|
| domain | 문자열 | 도메인 | 조회된 도메인 이름. 예: example.kr |
| registrant_name | 문자열 | 등록인 | 도메인 등록 기관 또는 개인명 |
| registrant_address | 문자열 | 등록인 주소 | 등록인 주소 |
| registrant_postal_code | 문자열 | 등록인 우편번호 | 등록인 우편번호 |
| admin_name | 문자열 | 관리자 | 도메인 관리자 이름 |
| admin_email | 문자열 | 관리자 이메일 | 도메인 관리자 이메일. 예: user@example.com |
| admin_phone | 문자열 | 관리자 전화번호 | 도메인 관리자 전화번호 |
| created | 날짜 | 등록일 | 도메인 최초 등록일 |
| updated | 날짜 | 최근 변경일 | 도메인 정보 최근 변경일 |
| expires | 날짜 | 만료일 | 도메인 만료일 (9999-12-31 은 만료일 미설정) |
| is_disclosed | 불리언 | 정보 공개 여부 | 등록인 정보 공개 여부 (true=공개) |
| registrar | 문자열 | 등록 대행기관 | 도메인 등록 대행 기관명 |
| registrar_url | 문자열 | 등록 대행기관 URL | 도메인 등록 대행 기관 URL |
| dnssec | 문자열 | DNSSEC | DNSSEC 적용 상태 |
| status | 문자열 목록 | 도메인 상태 | 도메인 상태 코드 목록 |
| name_servers | 문자열 목록 | 네임서버 | 권한 있는 네임서버 목록 |
| name_server_ips | 문자열 목록 | 네임서버 IP | 네임서버 IP 주소 목록 (누락 항목은 - 로 표기) |
| _error | 문자열 | 에러 | 유효하지 않은 입력 또는 API 호출 실패 메시지 |
오류 코드
파싱 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| KISA WHOIS 프로파일 이름을 입력하세요. | profile 옵션 누락 | profile= 에 단일 프로파일 지정 |
| 여러 프로파일은 허용되지 않습니다. 단일 KISA WHOIS 프로파일을 입력하세요. | profile 에 쉼표로 여러 개 지정 | 단일 프로파일만 지정 |
| 유효하지 않은 locale 입니다. 'ko' 또는 'en'을 사용하세요. | locale 값이 ko/en 이 아님 | locale=ko 또는 locale=en |
런타임 오류
일괄 처리 명령어는 행별 오류로 쿼리를 중단하지 않고, 해당 행의 _error 필드에 메시지를 기록한 뒤 다음 행으로 진행합니다.
_error 값 | 원인 | 해결 |
|---|---|---|
| domain field is null or empty | 입력 행에 domain 컬럼 누락/빈 값 | domain 컬럼을 채워 입력 |
| invalid domain (only .kr or .한국 supported): <값> | .kr·.한국 외 도메인 | 입력 데이터 정제 |
| no available KISA WHOIS profile | 프로파일 사용 불가 | 프로파일 등록 상태 점검 |
| KISA WHOIS API daily quota exceeded - 일일 호출 제한을 초과하였습니다. | 일일 호출 한도 초과 | 다음 날까지 대기하거나 한도 상향 |
| KISA WHOIS API rate limit exceeded - 호출 속도 제한을 초과하였습니다. ... | 호출 속도 제한 | 잠시 후 재시도 |
설명
이 명령어는 파이프로 들어온 각 입력 레코드의 domain 컬럼 값을 KISA WHOIS OpenAPI(/B551505/whois/domain_name)로 조회하여, 조회 결과 필드를 해당 레코드에 병합한 뒤 다음 단계로 전달합니다. 단일 프로파일에 대해 동작하므로 profile 옵션은 필수이며 쉼표로 여러 프로파일을 지정할 수 없습니다.
행별 입력 검증(.kr·.한국 여부)·API 호출 실패는 쿼리 전체를 중단시키지 않고 해당 행의 _error 필드에 사유를 기록합니다. 따라서 처리 후 _error 가 비어 있는 행만 정상 조회된 결과입니다. 다만 공공데이터포털 인증키 단위로 일일 호출 한도와 호출 속도 제한이 적용되므로, 대량 입력 시 한도 초과로 다수 행이 _error 처리될 수 있습니다.
단건 조회는 kisa-whois-domain 명령어를 사용하세요.
사용 예
예시: 접속 로그에 등장한 도메인 일괄 등록정보 보강
상황: 프록시 접속 로그에서 추출한 .kr 도메인 목록의 등록인·등록일 정보를 한 번에 보강해 위협 분석 자료로 활용합니다.
table xxx
| stats count by domain
| limit 10
| kisa-whois-domain-batch profile=kisa_whois
| fields domain, count, registrant_name, created, _error
예상 결과:
| domain | count | registrant_name | created | _error |
|---|---|---|---|---|
| example.kr | 1024 | 테스트기관 | 2003-01-15 | |
| test.kr | 37 | 테스트회사 | 2015-08-20 | |
| bad.com | 5 | invalid domain (only .kr or .한국 supported): bad.com |
결과 해석: _error 가 비어 있는 행은 정상 조회된 결과입니다. .com 등 미지원 도메인은 _error 에 사유가 남으므로, search _error == "" 로 정상 결과만 후속 분석에 사용할 수 있습니다.