커스텀 커넥터 만들기
이 문서를 사용하여 콘텐츠 허브에서 제공되지 않을 수 있는 서드 파티 도구를 위한 맞춤 통합을 SOAR SDK가 빌드하는 방법을 알아보세요. 커넥터는 일반적으로(항상 그런 것은 아님) 일종의 알림 대기열이 있는 데이터 소스에서 데이터를 수집하는 데 사용됩니다. 케이스, 알림, 이벤트는 Google SecOps 애플리케이션과의 커넥터 상호작용을 사용하여 플랫폼에서 생성됩니다. 커넥터는 기본 이벤트 데이터를 수집하고, 이 데이터를 알림에 할당한 다음, Google SecOps 애플리케이션 및 해당 데이터 처리 파이프라인에 알림을 전송합니다.
커스텀 커넥터를 만들려면 다음 대략적인 단계를 따르세요.
- 서드 파티 도구의 API 로직이 포함된 Manager 클래스를 만듭니다.
- IDE를 사용하여 커넥터를 빌드합니다.
관리자 만들기
커넥터를 만드는 첫 번째 단계는 통합하려는 기술에 필요한 모든 API 로직이 포함된 관리자 클래스를 빌드하는 것입니다. 예를 들어 Google SecOps의 Netskope 통합에는 사전 빌드된 관리자가 포함되어 있습니다. 이 관리자에는 Netskope API와 상호작용하는 데 필요한 모든 로직이 포함되어 있으며 자체 구현의 모델로 사용할 수 있습니다.
커넥터 만들기
IDE에서 맞춤 통합 빌드의 안내에 따라 새 커넥터를 만듭니다. IDE는 커넥터 스크립트의 기본 구조와 요구사항을 설명하는 코드 주석이 포함된 일반 템플릿을 생성합니다.
커넥터 로직은 다양할 수 있지만 일반적으로 프로세스에는 다음과 같은 핵심 단계가 포함됩니다.
- 서드 파티 도구의 API를 사용하여 알림, 감지 또는 이벤트를 가져옵니다. Netskope의 경우
get_alerts()메서드로 처리됩니다. 알림이 중복되지 않도록 하려면 타임스탬프별로 쿼리를 보내고 각 실행 후 업데이트하세요. AlertInfo(이전CaseInfo) 클래스를 사용하여 알림을 빌드하고 필요한 모든 필드를 할당합니다.- 중첩된 목록 및 사전 관련 문제를 방지하기 위해 연결된 이벤트 데이터를 가져와 평면화한 다음 평면화된 이벤트를 알림에 추가합니다.
- 시간별로 알림을 정렬하고 다음 쿼리에서 사용할 최신 타임스탬프를 저장합니다.
가져오기 및 SDK
모든 커넥터는 다음을 실행해야 합니다.
SiemplifyConnectors에서SiemplifyConnectorExecution클래스를 가져옵니다. 이 클래스는 일반적으로 커넥터의main()함수에서 인스턴스화됩니다. 이 객체가return_package()메서드를 사용하여 Google SecOps 애플리케이션에 알림 목록을 전달하면 스크립트가 종료됩니다.SiemplifyConnectorsDataModel에서AlertInfo클래스를 가져옵니다. 이 클래스를 인스턴스화하면 알림 객체가 생성됩니다. 이 예에서는 소스 시스템의 기본 제공 알림 객체 (Netskope)와의 혼동을 방지하기 위해SiemplifyAlertInfo로 이름이 변경됩니다. 이름 변경은 선택사항입니다.
SiemplifyUtils 모듈은 로깅, 데이터 형식 처리, 시간 변환 등에 일반적으로 사용되는 메서드를 제공합니다. 시간 처리를 비롯한 핵심 기능에 필수적이므로 output_handler, dict_to_flat, unix_now를 가져오는 것이 좋습니다.
대부분의 커넥터는 통합의 관리자 클래스도 가져옵니다. 일부 통합에는 관리자가 두 명 이상 포함됩니다. 사용 사례에 따라 추가 표준 Python 라이브러리를 가져올 수도 있습니다.
상수 변수
나중에 사용할 몇 가지 상수 변수를 선언하는 것이 좋습니다.
Google SecOps 알림을 만드는 스크립트의 예
경고는 앞에서 설명한 대로 AlertInfo 클래스의 객체를 인스턴스화하여 생성됩니다. 이 예에서는 소스 시스템과의 혼동을 방지하기 위해 SiemplifyAlertInfo()로 이름이 변경됩니다. alert_info 객체에는 애플리케이션이 알림을 올바르게 처리하기 위해 정의해야 하는 필수 속성이 여러 개 포함되어 있습니다.
build_alert_info 함수는 Netskope 알림(API에서 수신한 원시 JSON 형식)과 Siemplify 객체를 입력으로 수신합니다. 그런 다음 Netskope 알림을 파싱하고 관련 값을 `alert_info` 필드에 할당합니다.
이 함수는 이전에 정의된 상수도 사용합니다. alert_info 객체에 설정된 모든 속성은 Google SecOps 애플리케이션 내에서 알림 객체의 일부가 됩니다.
35번째 줄 (그림 2)에서는 이 프로세스의 중요한 부분을 강조합니다. 즉, 알림이 dict_to_flat 메서드를 사용하여 평면화된 후 events 속성에 추가됩니다.
하나의 알림에 여러 이벤트가 포함될 수 있습니다. 이 경우 각 이벤트를 적절하게 처리하는 로직을 포함해야 합니다. 이 예에서는 각 알림에 이벤트가 하나만 포함되므로 기본 구현으로 충분합니다.
dict_to_flat 메서드는 원시 JSON 구조를 평면화하는 데 사용됩니다. 이렇게 하면 중첩된 목록 및 딕셔너리 관련 문제를 방지할 수 있습니다. 플랫 키-값 쌍은 원본의 약간 수정된 버전입니다.
그림 2에서 다음 논리를 검토하세요.
display_id에는uuid라이브러리를 사용하여 무작위로 생성된 값이 할당됩니다. Netskope 알림은 UUID 필드를 제공하지 않지만, UUID 필드가 제공된다면 대신 사용할 수 있습니다.ticket_id이display_id과 일치하도록 설정됩니다. 두 필드는 시스템의 알림별로 고유해야 합니다. 이 고유성은 임의의 UUID를 생성하여 보장됩니다.name은 알림 이름이며 GUI에 표시됩니다.rule_generator은 소스 시스템에서 알림을 생성한 규칙을 나타냅니다. 이 필드는 원시 데이터에 항상 표시되지 않을 수 있습니다. 누락된 경우 문자열 값을 할당할 수 있지만 비워 두면 안 됩니다.start_time및end_time은 알림의 타임스탬프를 나타냅니다. 이 예에서 Netskope 알림은 Unix epoch 타임스탬프를 제공하며, 이를 밀리초로 변환하려면 1000을 곱해야 합니다. Google SecOps의 예상 형식입니다. 소스가 다른 형식을 사용하는 경우 변환해야 합니다. 유용한 시간 변환 메서드는SiemplifyUtils.py모듈을 참고하세요.priority: Google SecOps 애플리케이션은 알림의 우선순위에 따라 각 케이스에 우선순위를 할당합니다. Google SecOps API는 다음 스키마를 사용하여 숫자 값을 시각적 라벨에 매핑합니다. 여기서 정수 값은 커넥터에 전달됩니다.{"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100}여기서 정수 값은 커넥터에 전달되는 값입니다. 예를 들어 `100` 을 전달하면 GUI에서 알림이 심각으로 표시됩니다. 이 커넥터에서 추가 도우미 함수는 `SEVERITY_MAP` 상수를 사용하여 Netskope의 심각도 값을 이 우선순위 스케일에 매핑합니다. 하지만 Netskope의 심각도 필드가 일관되지 않으므로 여러 필드를 평가하기 위해 매핑에 추가 로직이 필요합니다.device_vendor및device_product에는 스크립트에서 이전에 정의된 상수 값이 할당됩니다.environment는 Google SecOps에서 여러 환경을 사용할 때 중요합니다. 이 경우siemplify객체에서 가져오며 플랫폼에서 커넥터에 대해 선택한 환경과 일치합니다.- 37번째 줄 (그림 3)에서 커넥터는 값이 `"Netskope"`인 새 키
product_name를 추가하여 기본 이벤트 딕셔너리를 수정합니다. 이는 원시 데이터에 플랫폼의 온톨로지에서 매핑 및 모델링에 사용할 수 있는 일관된 제품 필드가 포함되어 있지 않기 때문에 필요합니다.
그림 3: 기본 이벤트 수정
커넥터를 실행하는 스크립트의 예
main 함수에는 커넥터의 핵심 실행 로직이 포함되어 있습니다.
output_handler데코레이터는 디버깅 목적으로 사용되며 이 문서에서는 다루지 않습니다.main함수에는 기본값이False인 선택적 매개변수is_test_run이 포함됩니다. 이름에서 알 수 있듯이 이 매개변수는 커넥터가 프로덕션에서 알림을 수집해야 하는지 아니면 애플리케이션의 커넥터 테스트 탭에서 테스트 모드로 실행해야 하는지 결정합니다.
스크립트 줄별 핵심 실행 논리의 분석을 검토합니다.
- 56번과 57번 줄에서는 실행 중에 사용되는 두 개의 빈 목록을 초기화합니다.
- 58번째 줄에서
SiemplifyConnectorExecution클래스는siemplify객체를 인스턴스화합니다. 이 객체는 커넥터의 런타임 동작을 대부분 관리합니다. - 61번째 줄에서 커넥터 허용 목록의 인스턴스가 생성됩니다. 이 커넥터에서는 사용되지 않지만 다른 커넥터에서는 일반적으로 사용되며 이 가이드에서는 설명하지 않습니다.
- 67~69행에서는 인증 사용자 인증 정보나 구성 설정과 같은 커넥터 매개변수의 변수가 정의됩니다.
- 71번째 줄에서는
NetskopeManager객체를 인스턴스화하고 관련 매개변수를 전달하여 인증이 성공적으로 이루어지도록 합니다. 인증을 처리하는 내부 관리자 로직은 이 예에 표시되지 않습니다. - 73번째 줄에서는 이전 커넥터 실행 중에 생성된 로컬 파일에서 타임스탬프를 가져옵니다. 이 타임스탬프는 동일한 알림이 다시 처리되지 않도록 하는 데 사용됩니다.
- 74번과 75번 줄에서는 커넥터가 처음 실행되고 타임스탬프가 아직 설정되지 않은 경우 (예: 기본값이 `0`인 경우)를 처리합니다. Netskope는 Unix 에포크 시간이 필요하며 `0` 을 유효한 시작 시간으로 허용하지 않으므로 `unix_now` 함수를 사용하여 현재 시간을 밀리초 단위로 가져옵니다. 이 값은 `1,000` 으로 나누어 유닉스 시간(초)으로 변환됩니다. 결과 시작 시간과 종료 시간은 관리자의 `get_alerts` 메서드에 전달됩니다. 많은 API에서 시작 시간만 허용하지만 Netskope API에서는 시간 기반 알림 쿼리에 시작 시간과 종료 시간이 모두 필요합니다.
- 77번째 줄에서는 Netskope에서 알림 목록을 가져옵니다. 커넥터가 테스트 모드로 실행 중인 경우 목록의 마지막 알림만 선택됩니다 (79~80행).
오버플로 로직
그런 다음 커넥터는 가져온 알림을 반복하고 이전에 정의된 build_alert_info 함수를 사용하여 각 알림에서 알림을 빌드합니다. 이전 단계에서 초기화된 all_alerts 목록에 각 알림을 추가합니다. 커넥터 로직의 다음 부분에서는 오버플로를 처리합니다.
오버플로는 특히 알림이 동일한 환경, 제품, 규칙 생성기를 공유하는 경우 짧은 기간 내에 너무 많은 알림이 수집되지 않도록 하는 임곗값 메커니즘입니다. 필수는 아니지만 성능 저하를 방지하기 위해 오버플로 로직을 구현하는 것이 좋습니다.
그림 4에서 스크립트 줄별 오버플로 로직 분석을 검토하세요.
- 104~105행에서
alert가 오버플로로 분류되지 않으면 수집할 알림 목록에 추가됩니다.
커넥터 실행 종료
커넥터가 테스트 모드로 실행되지 않는 경우 타임스탬프는 마지막으로 가져온 알림을 반영하도록 업데이트해야 합니다. 이렇게 하면 다음 실행 주기 동안 동일한 알림이 다시 수집되지 않습니다. all_alerts 목록은 타임스탬프를 기준으로 정렬되므로 오버플로된 알림도 최신 타임스탬프를 결정하는 데 기여합니다.
그림 5에서 스크립트 줄별 커넥터 실행 논리 분석을 검토합니다.
- 126번째 줄에서 오버플로되지 않은 알림 목록이 애플리케이션에 제출되고, 여기에서 알림이 생성되어 GUI에 표시됩니다.
- 128~131행에서는 커넥터가 테스트 모드로 실행 중인지 확인합니다. 테스트 탭에서 커넥터 한 번 실행을 클릭하는 경우와 같이 애플리케이션에서 전달된 시스템 인수가 이 결정을 내리는 데 사용됩니다.
그림 5: 커넥터 실행 종료
도움이 더 필요하신가요? 커뮤니티 회원 및 Google SecOps 전문가에게 문의하여 답변을 받으세요.