사용 매뉴얼
개요
대상 사용자: 보안 관제·분석 업무에서 도메인, IP 주소, ASN의 등록 정보를 조회해야 하는 보안 담당자 또는 소나 관리자
- 한국 도메인(.kr, .한국)의 등록인, 관리자, 네임서버 등 등록 정보 조회
- IP 주소의 할당 대역, 기관 정보, 네트워크 담당자 연락처 조회
- ASN의 기관 정보 및 관리자 연락처 조회
기본 개념·용어
| 용어 | 의미 | 관련 리소스 |
|---|---|---|
| 접속 프로파일 | KISA WHOIS API 연결에 필요한 서비스 키를 저장하는 소나 객체 | 설치 매뉴얼 참고 |
kisa-whois-domain | 도메인 이름의 등록정보 및 할당정보를 조회하는 확장 명령어 | 명령어 문서 |
kisa-whois-ip | IP 주소의 등록정보 및 할당정보를 조회하는 확장 명령어 | 명령어 문서 |
kisa-whois-asn | ASN의 등록정보 및 할당정보를 조회하는 확장 명령어 | 명령어 문서 |
| locale | 조회 결과 언어 설정. ko(한국어, 기본값) 또는 en(영문). 예: locale=en | — |
| pretty | 리스트 타입 필드(status, name_servers, name_server_ips)의 값을 줄바꿈된 문자열로 출력. 예: pretty=t | kisa-whois-domain 전용 |
| 배치 명령어 | 다수 건 일괄 조회 시 사용하는 명령어 | — |
주요 화면·메뉴 경로
| 기능 | 경로 |
|---|---|
| 앱 관리 | 앱 |
| 접속 프로파일 등록·관리 | 시스템 > 접속 프로파일 |
| 쿼리 실행 | 분석 > 쿼리 |
작업 시나리오
시나리오 1: 도메인 등록 정보 조회
목적: 특정 도메인의 등록인, 관리자 연락처, 등록일, 만료일, 네임서버 등의 정보를 확인합니다. 피싱 도메인 분석이나 도메인 소유자 확인 시 활용할 수 있습니다.
사전 조건:
- KISA WHOIS 앱이 설치되어 있고 접속 프로파일(식별자 예:
kisa_whois)이 등록되어 있어야 합니다. - 조회 대상은
.kr,.한국도메인만 지원됩니다..com,.net등 해외 TLD는 지원하지 않습니다.
수행 절차:
- 분석 > 쿼리에서 아래 쿼리를 실행합니다.
결과 확인:
- 도메인 등록인, 관리자 이메일, 등록일, 만료일, 등록 대행 기관 등이 조회됩니다.
locale=en옵션을 추가하면 영문 등록 정보를 조회할 수 있습니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
| 결과 0건 또는 에러 코드 100 | 등록되지 않은 도메인 | .kr, .한국 도메인인지 확인 |
| 에러 코드 214501 | 접속 프로파일 미지정 | profile= 옵션에 올바른 식별자 입력 |
| 에러 코드 214504 | 일일 호출 제한 초과 (10,000건/일) | 다음 날 재시도 |
| 에러 코드 214505 | 호출 속도 제한 | 잠시 후 재시도 |
시나리오 2: IP 주소 할당 정보 조회
목적: 특정 IP 주소가 어느 기관에 할당되어 있는지, 네트워크 대역과 담당자 정보를 확인합니다. 보안 이벤트에서 출발지/목적지 IP의 소유자를 식별할 때 활용합니다.
사전 조건:
- KISA WHOIS 앱이 설치되어 있고 접속 프로파일이 등록되어 있어야 합니다.
수행 절차:
- 분석 > 쿼리에서 아래 쿼리를 실행합니다.
결과 확인:
- 국내 IP는 ISP/사용자 블록 정보, 네트워크 담당자 이메일·전화번호까지 조회됩니다.
- 해외 IP는 레지스트리(APNIC, ARIN 등)와 국가 코드만 조회됩니다.
locale=en옵션을 추가하면 영문 등록 정보를 조회할 수 있습니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
| 에러 코드 041 | IPv4 주소 형식 오류 | IP 주소 형식 확인 (예: 192.0.2.1) |
| 에러 코드 200 | IP 주소를 찾을 수 없음 | 유효한 IP 주소인지 확인 |
| 에러 코드 214504 | 일일 호출 제한 초과 | 다음 날 재시도 |
시나리오 3: ASN 등록 정보 조회
목적: 특정 ASN의 기관 정보와 관리자 연락처를 확인합니다. 네트워크 경로 분석이나 특정 AS에서 발생한 트래픽의 소유 기관을 식별할 때 활용합니다.
사전 조건:
- KISA WHOIS 앱이 설치되어 있고 접속 프로파일이 등록되어 있어야 합니다.
수행 절차:
- 분석 > 쿼리에서 아래 쿼리를 실행합니다.
결과 확인:
- 국내 ASN은 기관 정보, 주소, 관리자 연락처까지 조회됩니다.
- 해외 ASN은 레지스트리(ARIN, RIPE 등)와 국가 코드만 반환됩니다.
locale=en옵션을 추가하면 영문 등록 정보를 조회할 수 있습니다.
실패 대응:
| 증상 | 원인 | 해결 |
|---|---|---|
| 에러 코드 061 | ASN 형식 오류 | AS 접두사 포함 확인 (예: AS9700) |
| 에러 코드 400 | ASN를 찾을 수 없음 | 유효한 ASN인지 확인 |
| 에러 코드 214504 | 일일 호출 제한 초과 | 다음 날 재시도 |
주의사항
- 일일 호출 제한: 엔드포인트(domain, ip, asn)당 일일 10,000건으로 제한됩니다. 초과 시 해당 엔드포인트의 호출이 다음 날까지 차단됩니다.
- 호출 속도 제한: 단시간에 과도한 요청을 보내면 일시적으로 HTTP 429 응답이 반환됩니다. 잠시 후 재시도하면 정상 동작합니다.
- 지원 범위: 도메인 조회는
.kr,.한국TLD만 지원합니다..com,.net등 해외 TLD는 조회되지 않습니다. 해외 IP/ASN는 레지스트리·국가 코드만 반환됩니다. - 인증키 유효기간: 공공데이터포털 개발계정 인증키는 발급일로부터 2년간 유효합니다. 만료 전 갱신이 필요합니다.
관련 문서
- 설치 매뉴얼 — 최초 설치 및 접속 프로파일 설정
- kisa-whois-domain — 도메인 등록정보 조회 명령어
- kisa-whois-ip — IP 주소 등록정보 조회 명령어
- kisa-whois-asn — ASN 등록정보 조회 명령어