kisa-whois-ip-batch
입력 레코드의 ip 컬럼 값으로 KRNIC 관리 IP 주소의 등록·할당 정보를 일괄 조회합니다.
문법
옵션
- profile=STRING
- 필수 옵션. KISA WHOIS 접속 프로파일 식별자. 단일 프로파일만 허용하며, 쉼표로 여러 개를 지정할 수 없습니다. 예:
kisa_whois - locale=STRING
- 선택 옵션. 출력 언어.
ko또는en만 허용합니다. 해외 IP는 레지스트리·국가 코드만 반환됩니다. (기본값:ko)
입력 필드
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| ip | 문자열 | Y | 조회할 IP 주소 (IPv4 또는 IPv6). 예: 192.0.2.1 |
출력 필드
입력 레코드의 기존 컬럼은 그대로 유지되며, 아래 필드가 병합됩니다.
| 필드 | 타입 | 이름 | 설명 |
|---|---|---|---|
| ip_type | 문자열 | 조회 유형 | 조회된 자원 유형 (IPv4/IPv6) |
| registry | 문자열 | 관리 기관 | 자원을 관리하는 레지스트리. 예: KISA |
| country | 문자열 | 국가 코드 | ISO 2 국가 코드. 예: KR |
| ip_range | 문자열 | IP 범위 | 사용자(최종 할당)에 할당된 IP 범위 |
| cidr | 문자열 | CIDR | 사용자 CIDR 프리픽스 길이 |
| network_type | 문자열 | 네트워크 유형 | 사용자 네트워크 유형 |
| org_name | 문자열 | 할당기관 | 사용자(최종 할당) 기관명 |
| org_id | 문자열 | 할당기관 ID | 할당기관 식별자 |
| org_address | 문자열 | 할당기관 주소 | 할당기관 주소 |
| org_postal_code | 문자열 | 할당기관 우편번호 | 할당기관 우편번호 |
| created | 날짜 | 등록일 | 사용자 할당 등록일 |
| tech_name | 문자열 | 담당자 | 기술 담당자 이름 |
| tech_phone | 문자열 | 담당자 전화번호 | 기술 담당자 전화번호 |
| tech_email | 문자열 | 담당자 이메일 | 기술 담당자 이메일. 예: user@example.com |
| provider_type | 문자열 | 상위 할당 유형 | 상위 할당 유형: PI(독립사용자, Provider-Independent) 또는 ISP |
| provider_ip_range | 문자열 | 상위 IP 범위 | 상위 할당 IP 범위 |
| provider_cidr | 문자열 | 상위 CIDR | 상위 CIDR 프리픽스 길이 |
| provider_service_name | 문자열 | 상위 서비스명 | 상위 네트워크 서비스명 |
| provider_org_name | 문자열 | 상위 할당기관 | 상위 할당 기관명 (독립사용자 또는 ISP) |
| provider_org_id | 문자열 | 상위 할당기관 ID | 상위 할당 기관 식별자 |
| provider_org_address | 문자열 | 상위 할당기관 주소 | 상위 할당 기관 주소 |
| provider_org_postal_code | 문자열 | 상위 할당기관 우편번호 | 상위 할당 기관 우편번호 |
| provider_created | 날짜 | 상위 등록일 | 상위 할당 등록일 |
| provider_tech_name | 문자열 | 상위 담당자 | 상위 기술 담당자 이름 |
| provider_tech_phone | 문자열 | 상위 담당자 전화번호 | 상위 기술 담당자 전화번호 |
| provider_tech_email | 문자열 | 상위 담당자 이메일 | 상위 기술 담당자 이메일 |
| _error | 문자열 | 에러 | 유효하지 않은 입력 또는 API 호출 실패 메시지 |
오류 코드
파싱 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| KISA WHOIS 프로파일 이름을 입력하세요. | profile 옵션 누락 | profile= 에 단일 프로파일 지정 |
| 여러 프로파일은 허용되지 않습니다. 단일 KISA WHOIS 프로파일을 입력하세요. | profile 에 쉼표로 여러 개 지정 | 단일 프로파일만 지정 |
| 유효하지 않은 locale 입니다. 'ko' 또는 'en'을 사용하세요. | locale 값이 ko/en 이 아님 | locale=ko 또는 locale=en |
런타임 오류
일괄 처리 명령어는 행별 오류로 쿼리를 중단하지 않고, 해당 행의 _error 필드에 메시지를 기록한 뒤 다음 행으로 진행합니다.
_error 값 | 원인 | 해결 |
|---|---|---|
| ip field is null or empty | 입력 행에 ip 컬럼 누락/빈 값 | ip 컬럼을 채워 입력 |
| invalid ip: <값> | IPv4·IPv6 형식이 아닌 값 | 입력 데이터 정제 |
| no available KISA WHOIS profile | 프로파일 사용 불가 | 프로파일 등록 상태 점검 |
| KISA WHOIS API daily quota exceeded - 일일 호출 제한을 초과하였습니다. | 일일 호출 한도 초과 | 다음 날까지 대기하거나 한도 상향 |
| KISA WHOIS API rate limit exceeded - 호출 속도 제한을 초과하였습니다. ... | 호출 속도 제한 | 잠시 후 재시도 |
설명
이 명령어는 파이프로 들어온 각 입력 레코드의 ip 컬럼 값을 KISA WHOIS OpenAPI(/B551505/whois/ip_address)로 조회하여, 조회 결과 필드를 해당 레코드에 병합한 뒤 다음 단계로 전달합니다. 단일 프로파일에 대해 동작하므로 profile 옵션은 필수이며 쉼표로 여러 프로파일을 지정할 수 없습니다.
응답은 사용자(최종 할당) 정보(org_*·tech_*)와 상위 할당 정보(provider_*)로 구분되며, 상위 할당 유형은 provider_type(PI 또는 ISP)으로 표시됩니다. KRNIC 관리 대상이 아닌 해외 IP는 registry·country 만 채워집니다.
행별 입력 검증(IP 형식)·API 호출 실패는 쿼리 전체를 중단시키지 않고 해당 행의 _error 필드에 사유를 기록합니다. 따라서 처리 후 _error 가 비어 있는 행만 정상 조회된 결과입니다. 공공데이터포털 인증키 단위로 일일 호출 한도·속도 제한이 적용되므로, 대량 입력 시 한도 초과로 다수 행이 _error 처리될 수 있습니다.
단건 조회는 kisa-whois-ip 명령어를 사용하세요.
사용 예
예시: 방화벽 차단 IP 목록의 할당 기관 일괄 식별
상황: 방화벽에서 차단된 출발지 IP 목록의 국내 할당 기관·ISP를 한 번에 식별해 오탐 여부와 대응 우선순위를 판단합니다.
table firewall_block
| stats count by src_ip
| limit 10
| rename src_ip as ip
| kisa-whois-ip-batch profile=kisa_whois
| fields ip, count, country, org_name, provider_org_name, _error
예상 결과:
| ip | count | country | org_name | provider_org_name | _error |
|---|---|---|---|---|---|
| 192.0.2.1 | 540 | KR | 테스트기관 | 테스트회사 | |
| 192.0.2.2 | 88 | KR | 테스트회사 | 테스트회사 | |
| 203.0.113.7 | 12 | US |
결과 해석: country=KR 인 행은 할당 기관·상위 ISP가 채워집니다. 203.0.113.7 처럼 해외 IP는 country 만 채워지고 상세 정보는 비어 있습니다. _error 가 있는 행은 입력 형식 오류나 API 실패이므로 별도 확인이 필요합니다.