REST API 활용 가이드
가이드 개요
Genian Insights E 3.0 은 타 장비 또는 타 시스템 등과의 연동을 위해 이벤트 정보의 제공, 사용자 정의 IOC 생성/수정/삭제, 설정변경, 수집 정보 조회 등이 가능하도록 REST API를 제공합니다.
본 가이드는 Genian Insights E 3.0 의 REST API를 활용하기 위한 사전 준비사항, 주요 API 등에 대한 안내를 목적으로 합니다.
사전 준비사항
외부 장비에서 Genian Insights E 3.0으로 REST API를 호출하기 위해서 인증이 필요하며, 인증을 위해서는 API KEY 값 생성이 필요합니다.
API KEY
API KEY방식은 연동을 위한 계정의 API KEY를 생성하여 Genian Insights E 3.0 API를 호출할 때마다 API KEY를 첨부하여 활용하는 방식 입니다.
각 관리자 계정 별로 별도로 생성하여 활용이 가능합니다. 호출의 권한은 해당 계정의 권한에 종속됩니다.
API KEY생성 방안은 다음을 참고하시기 바랍니다. API 가이드
주요 API
Genian Insights E 3.0과 연동을 위한 주요 API 항목은 Managements, Endpoint, Indicator, Events, Acquisitions 등이 있고, 각각 상세 내용은 아래와 같습니다.
Managements API
Genian Insights E 3.0 에서는 업무 역할에 따라 권한을 제어하여 사용할 수 있도록 관리역할을 생성할 수 있으며, 생성된 관리역할을 할당하여 관리자 계정을 생성하여 시스템을 관리할 수 있습니다.
Managements API를 활용하시면 관리자 계정, 관리역할에 대한 관리를 수행할 수 있습니다.
관리자 계정 관련한 주요 API는 다음과 같습니다.
Description |
Type |
API Path |
주요 목적 |
|---|---|---|---|
등록된 관리자 계정 검색 |
GET |
/managements/users |
사용자 아이디, 사용자명, 접근허용IP 등 등록되어 있는 모든 관리자 계정 관련 정보를 조회하기 위한 목적으로 사용됩니다. |
특정 관리자 계정 검색 |
GET |
/managements/users/{user_id} |
USER_ID 기준으로 특정 관리자 계정 정보만을 조회하기 위한 목적으로 사용됩니다. |
관리자 계정 생성 |
POST |
/managements/users |
신규로 관리자 계정을 생성하기 위한 목적으로 사용됩니다. |
관리자 계정 수정 |
PUT |
/managements/users/{user_id} |
이미 등록되어 있는 관리자 계정 정보를 수정하기 위한 목적으로 사용됩니다. |
관리자 계정 삭제 |
DELETE |
/managemnets/users/{user_id} |
이미 등록되어 있는 관리자 계정 정보를 삭제하기 위한 목적으로 사용됩니다. |
관리자 API 키 생성 |
POST |
/managements/users/{user_id}/apikey |
특정 관리자 계정의 API KEY를 생성하여 API연동, NAC연동 등을 위한 목적으로 사용됩니다. |
관리자 API 키 삭제 |
DELETE |
/managements/users/{user_id}/apikey |
특정 관리자 계정의 API KEY를 삭제하기 위한 목적으로 사용됩니다. |
관리역할 관련한 주요 API는 다음과 같습니다.
Description |
Type |
API Path |
주요 목적 |
|---|---|---|---|
관리역할 검색 |
GET |
/managements/roles |
현재 등록되어 있는 관리역할을 조회하는 목적으로 사용됩니다. |
관리역할 조회 |
GET |
/managements/roles/{role_id} |
role_id 기준으로 특정 관리역할을 조회하는 목적으로 사용됩니다. |
관리역할 생성 |
POST |
/managements/roles |
기 정의 된 관리역할 외 신규 관리역할을 생성하는 목적으로 사용됩니다. |
관리역할 수정 |
PUT |
/managements/roles/{role_id} |
role_id 기준으로 특정 관리역할의 권한 등을 수정하는 목적으로 사용됩니다. |
Endpoint API
Genian Insights E 3.0에서는 에이전트가 설치 된 단말은 Endpoint로 명칭하고, 개별 Endpoint에 대해 관리자가 명령을 수행 할 수 있습니다.
Endpoints API를 활용하시면 Endpoint에 네트워크 격리, 아티팩트 수집 등 특정 명령을 수행할 수 있습니다.
Endpoint와 관련한 주요 API는 다음과 같습니다.
Description |
Type |
API Path |
주요 목적 |
|---|---|---|---|
네트워크 격리/해제 |
POST |
/endpoints/command |
특정 Endpoint가 감염 된 것으로 추정되어 네트워크 격리가 필요한 경우, 혹은 위협 분석 결과 안전으로 판명될 경우 해제의 목적으로 사용됩니다. command에 isolate_network를 입력하면 됩니다. |
아티팩트 수집 |
POST |
/endpoints/command |
특정 Endpoint에 대한 상세 분석이 필요한 경우 아티팩트 수집의 목적으로 사용됩니다. command에 collect_artifact를 입력하면 됩니다. |
파일 수집 |
POST |
/endpoints/command |
특정 Endpoint에 존재하는 파일 수집의 목적으로 사용됩니다. command에 collect_file를 입력하면 됩니다. |
Indicator API
Genians Insights E 3.0에서는 MalwareHash(악성HASH), SuspiciousIP(악성IP), GoodwareHash(안전HASH), GoodIP(안전IP) 와 같이 분류하여 위협 정보를 관리하고 있습니다.
Indicator API를 활용하시면 사용자정의 IOC를 조회/추가/삭제를 수행할 수 있습니다.
Indicator와 관련한 주요 API는 다음과 같습니다.
Description |
Type |
API Path |
주요 목적 |
|---|---|---|---|
MalwareHash 조회 |
GET |
/indicators/custom/malwarehashes |
등록되어 있는 사용자정의 MalwareHash 정보를 조회하기 위한 목적으로 사용됩니다. |
MalwareHash 생성 |
POST |
/indicators/custom/malwarehashes |
파라미터에 입력된 정보를 기반으로 사용자정의 MalwareHash 정보를 다중 생성할 목적으로 사용됩니다. |
MalwareHash 수정 |
PUT |
/indicators/custom/malwarehashes |
등록되어 있는 사용자의 MalwareHash 정보를 수정하기 위한 목적으로 사용됩니다. |
MalwareHash 삭제 |
DELETE |
/indicators/custom/malwarehashes |
등록되어 있는 사용자의 MalwareHash 정보를 삭제하기 위한 목적으로 사용됩니다. |
GoodWareHash 조회 |
GET |
/indicators/custom/goodwarehashes |
등록되어 있는 사용자의 GoodwareHash 정보를 조회하기 위한 목적으로 사용됩니다. |
GoodWareHash 생성 |
POST |
/indicators/custom/goodwarehashes |
파라미터에 입력된 정보를 기반으로 사용자정의 GoodwareHash 정보를 생성할 목적으로 사용됩니다. |
GoodWareHash 수정 |
PUT |
/indicators/custom/goodwarehashes |
등록되어 있는 사용자의 GoodwareHash 정보를 수정하기 위한 목적으로 사용됩니다. |
GoodWareHash 삭제 |
DELETE |
/indicators/custom/goodwarehashes |
등록되어 있는 사용자의 GoodwareHash 정보를 삭제하기 위한 목적으로 사용됩니다. |
Suspiciousip 조회 |
GET |
/indicators/custom/Suspiciousips |
등록되어 있는 사용자의 Suspiciousip 정보를 조회하기 위한 목적으로 사용됩니다. |
Suspiciousip 생성 |
POST |
/indicators/custom/Suspiciousips |
파라미터에 입력된 정보를 기반으로 사용자정의 Suspiciousip 정보를 생성할 목적으로 사용됩니다. |
Suspiciousip 수정 |
PUT |
/indicators/custom/Suspiciousips |
등록되어 있는 사용자의 Suspiciousip 정보를 수정하기 위한 목적으로 사용됩니다. |
Suspiciousip 삭제 |
DELETE |
/indicators/custom/Suspiciousips |
등록되어 있는 사용자의 Suspiciousip 정보를 삭제하기 위한 목적으로 사용됩니다. |
Goodip 조회 |
GET |
/indicators/custom/goodips |
등록되어 있는 사용자의 goodip 정보를 조회하기 위한 목적으로 사용됩니다. |
Goodip 생성 |
POST |
/indicators/custom/goodips |
파라미터에 입력된 정보를 기반으로 사용자정의 goodip를 생성할 목적으로 사용됩니다. |
Goodip 수정 |
PUT |
/indicators/custom/goodips |
등록되어 있는 사용자의 goodip 정보를 수정하기 위한 목적으로 사용됩니다. |
Goodip 삭제 |
DELETE |
/indicators/custom/goodips |
등록되어 있는 사용자의 goodip 정보를 삭제하기 위한 목적으로 사용됩니다. |
Events API
Genian Insights E 3.0에서는 Endpoint 이벤트 수집, 위협 이벤트 탐지, 소프트웨어 정보 수집, 저장매체 정보 수집 등 다양한 정보를 수집하여 저장하고 있습니다.
Events API를 활용하시면 수집 이벤트, 위협 이벤트, 소프트웨어 정보, 외부매체 정보 등 Insights E에 적재된 이벤트를 조회 할 수 있습니다.
Description |
Type |
API Path |
주요 목적 |
|---|---|---|---|
이벤트 조회 및 집계 |
GET |
/events/endpoints |
수집된 이벤트를 조회 및 집계하는 목적으로 사용됩니다.(단, 검색범위는 24H 초과불가, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
위협 이벤트 조회 및 집계 |
GET |
/events/alerts |
위협 이벤트를 조회 및 집계하는 목적으로 사용됩니다. (단, 검색범위는 일주일 초과불가, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
소프트웨어 정보 조회 및 집계 |
GET |
/events/softwares |
엔드포인트에 설치되어 있는 소프트웨어 정보를 조회하는 목적으로 사용됩니다. (단, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
파일 정보 조회 및 집계 |
GET |
/events/filemasters |
엔드포인트에서 수집한 파일에 대한 해시, 속성, 전자서명 등 정보를 조회하는 목적으로 사용됩니다. (단, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
시스템 정보 조회 및 집계 |
GET |
/events/systems |
엔드포인트 시스템 소프트웨어 정보(cpu,mem,list 등)를 조회하는 목적으로 사용됩니다. (단, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
실행파일 유입경로 정보 조회 및 집계 |
GET |
/events/inflows |
실행파일의 유입 경로에 대한 정보를 조회하는 목적으로 사용됩니다. (단, 검색범위는 일주일 초과불가, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
외부매체 정보 조회 및 집계 |
GET |
/events/volumes |
외부매체(이동식 디스크, 외장 HDD 등) 정보를 조회하는 목적으로 사용됩니다. (단, 검색범위는 일주일 초과불가, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
Acquisitions API
Genian Insights E 3.0에서는 에이전트 로그 수집, Endpoint 파일 수집, 악성 샘플파일 수집 등 다양한 파일을 수집할 수 있습니다.
Acquisitions API를 활용하시면 에이전트 로그 수집, 파일 수집 기능, 아티팩트 수집, 악성 샘플파일 수집 등 다양한 파일을 수집할 수 있습니다.
Description |
Type |
API Path |
주요 목적 |
|---|---|---|---|
수집된 파일 검색 |
GET |
/acquisitions |
수집관리 메뉴 내 수집된 파일을 검색하는 목적으로 사용됩니다. (단, 검색범위는 30일 초과불가, 반환 건수는 최대 1000건, API KEY 별 1초내 연속 요청 제한) |
수집된 파일 다운로드 |
GET |
/acquisitions/download |
수집관리 메뉴 내 수집된 파일을 다운로드 하는 목적으로 사용됩니다. (단, API KEY 별 1초내 연속 요청 제한) |
RESPONSE CODE
아래 표는 REST API에서 사용하는 HTTP Status Codes를 나타냅니다.
Code |
Name |
Detailed Descriptions |
|---|---|---|
200 |
OK |
요청이 성공적으로 되었습니다. |
201 |
Created |
요청이 성공적이었으며 그 결과로 새로운 리소스가 생성되었습니다. |
400 |
Bad Request |
잘못된 구문으로 인해 서버가 요청을 이해할 수 없습니다. |
401 |
Unauthorized |
요청한 응답을 받기 위해서는 사용자 인증이 필요합니다. |
403 |
Forbidden |
콘텐츠에 접근할 권리를 가지고 있지 않습니다. |
404 |
Not Found |
서버는 요청받은 리소스를 찾을 수 없습니다. |
406 |
Not Acceptable |
요청한 페이지가 요청한 콘텐츠 특성으로 응답할 수 없습니다. |
500 |
Internal Server Error |
서버에 예기치 않은 오류가 발생했습니다. |
503 |
Service Unavailable |
서버가 요청을 처리할 준비가 되지 않았습니다. |
참고 - API활용도구 제공:Swagger
Genian Insights E 3.0를 활용하는데 도움을 드리고자, Swagger 페이지를 제공하고 있습니다. Swagger는 웹페이지를 통해서 REST API 정보와 테스트 도구를 제공합니다.
1단계. Swagger 접속
Genian Insights E 3.0 의 관리자 계정으로 WEB 콘솔 1차 접속
로그인이 된 상태에서 주소창에 https://{정책서버IP}:8443/mc/swagger 를 입력하여 2차 접속
Swagger 접속 확인
2단계. Swagger를 이용한 테스트
활용하고자 하는 API를 선택한 후, 해당 API의 우측에 Try It out 버튼 클릭
Parameters 항목에서 Description 값 입력
아래의 Execute 버튼 클릭
Responses 항목에서 curl 및 Request URL 값 확인 (Server response 항목에서 Code값이 200 일 때 정상동작 합니다.)
Note
Content Type은 JSON을 사용하며 'application/json;charset=UTF-8'을 표준으로 합니다. (포맷이 다른 경우, 폰트가 손상되어 보일 수 있습니다.)