.. _corelight-client:

.. Version number is filled in automatically. .. |version| replace:: 1.5.22

==================================== Corelight Sensor 명령줄 클라이언트

.. contents::

개요

이 도구는 Corelight Sensor <https://www.corelight.com>_ 를 위한 명령줄 클라이언트를 제공합니다. Corelight Sensor는 Bro의 창시자들이 처음부터 네트워크 트래픽을 분석 파이프라인을 위한 고품질 데이터로 변환하도록 설계한 Bro <https://www.bro.org>_ 어플라이언스입니다. 명령줄 클라이언트를 사용하면 포괄적인 RESTful API를 통해 Corelight Sensor를 원격으로 구성하고 제어할 수 있습니다. 이 클라이언트 개요의 확장 버전은 Corelight Sensor 문서를 참조하십시오.

:Version: |version| :Home: http://www.corelight.com :GitHub: https://github.com/corelight/corelight-client :Author: Corelight, Inc. <https://www.corelight.com>_ [email protected]

라이선스

이 클라이언트는 BSD 라이선스에 따른 오픈 소스입니다. 자세한 내용은 COPYING 을 참조하십시오.

설치

명령줄 클라이언트는 Python >= 3.4와 주요 의존성으로 requests 모듈이 설치되어 있어야 합니다.

클라이언트를 설치하는 가장 쉬운 방법은 Python Package Index를 이용하는 것입니다::

# pip3 install corelight-client

또는 GitHub에서 최신 버전을 설치할 수 있습니다::

# git clone https://github.com/corelight/corelight-client
# cd corelight-client
# pip3 install setuptools
# python3 setup.py install

모든 것이 올바르게 설치되었다면 --help 가 사용법 메시지를 표시합니다::

# corelight-client --help
Usage: corelight-client [<global options>] <command> <subcommand> [<options>]
          [--ssl-ca-cert SSL_CA_CERT] [--ssl-no-verify-certificate]
          [--ssl-no-verify-hostname] [--cache CACHE]
[...]

처음에는 --help 가 아직 사용할 수 있는 추가 명령을 표시하지 않습니다. 클라이언트가 장치에 연결할 수 있도록 하려면 다음 섹션으로 진행하십시오.

접근 및 인증

장치의 구성 인터페이스를 통해 Corelight API에 대한 접근을 활성화해야 합니다. 또한 API 사용자인 admin (무제한 접근용)과 monitor (읽기 전용 접근용)의 비밀번호를 설정해야 합니다. 자세한 내용은 Corelight Sensor 문서를 참조하십시오.

다음으로 corelight-client 에 Corelight Sensor의 네트워크 주소를 알려주어야 합니다. 이를 위한 세 가지 방법이 있습니다:

• 명령줄에 -b <address> 를 추가합니다.

• ~/.corelight-client.rc 구성 파일을 생성하고 device=<address> 내용을 작성합니다.

• 환경 변수 CORELIGHT_DEVICE=<address> 를 설정합니다.

모든 설정이 완료되면 corelight-client --help 가 사용자 이름과 비밀번호를 요청하고, 장치 API가 클라이언트에 제공할 수 있는 전체 명령 목록을 표시합니다. 자격 증명 저장을 확인하면 클라이언트는 향후 재사용을 위해 ~/.corelight-client/credentials 에 저장합니다. Configuration File_ 또는 Global Options_ 를 통해 인증 정보를 지정할 수도 있습니다.

사용법

클라이언트는 <command> <subcommand> [options] 형식의 명령 집합을 통해 API의 기능을 제공합니다. 모든 명령에 --help 를 추가하면 해당 명령의 모든 기능과 옵션에 대한 설명을 볼 수 있습니다.

--help 출력에서 명령의 옵션 유형이 file 로 표시되면 클라이언트는 전송할 파일의 경로를 지정하도록 요구합니다. 또한 명령줄에서 직접 값을 제공하는 대신 옵션 값 앞에 file:// 를 붙여 파일에서 내용을 읽을 수 있습니다.

(참고: --help 출력에는 클라이언트가 장치에 연결하고 인증할 수 있는 경우에만 명령 목록이 포함됩니다.)

.. _corelight-client-options:

전역 옵션

corelight-client 는 다음과 같은 전역 명령줄 옵션을 지원합니다. --device 와 --fleet 옵션은 상호 배타적으로 사용해야 합니다. 다른 모든 옵션은 모든 요청에 적용됩니다:

--async 비동기 명령이 완료될 때까지 기다리지 않고 종료합니다.

--device Corelight Sensor 장치의 네트워크 주소를 지정합니다.

--fleet Corelight Fleet Manager의 네트워크 주소를 지정합니다.

--uid 지정된 Corelight Fleet Manager를 통해 관리되는 Corelight Sensor의 UID를 지정합니다.

--cache=<file> Corelight Sensor 메타 데이터를 캐싱할 사용자 지정 파일을 설정합니다.

--debug HTTP 요청과 응답을 보여주는 디버깅 출력을 활성화합니다.

--password 인증을 위한 비밀번호를 지정합니다.

--mfa 지정된 Corelight Fleet Manager로 인증하기 위한 2FA 인증 코드를 지정합니다. '-'를 사용하면 사용자에게 묻습니다.

--ssl-ca-cert 장치의 신뢰성을 검증하기 위한 사용자 지정 SSL CA 인증서가 포함된 파일을 지정합니다.

--ssl-no-verify-certificate 클라이언트가 모든 Corelight Sensor SSL 인증서를 수락하도록 지시합니다.

--ssl-no-verify-hostname Corelight Sensor의 SSL 인증서가 호스트 이름과 일치하지 않더라도 수락하도록 클라이언트에 지시합니다.

--socket 요청 전송에 unix 도메인 소켓을 사용하도록 클라이언트에 지시합니다.

--user 인증을 위한 사용자 이름을 지정합니다.

--version corelight-client 의 버전을 표시하고 종료합니다.

--ignore-meta CLI에서 지정하지 않는 한 센서 API 호출에 메타데이터 정보를 전송하지 않습니다.

--automation 자동화 친화적 동작 묶음을 활성화합니다: 요청 타임아웃, 일시적 실패 재시도, 구조화된 JSON 오류, 선별된 종료 코드 분류, 엄격한 비대화형 확인. 자세한 내용은 아래 Automation_ 을 참조하십시오. 환경 변수 CORELIGHT_AUTOMATION=1 을 설정하여 활성화할 수도 있습니다.

--timeout 요청 타임아웃을 초 단위로 설정합니다. 단일 숫자 N (연결과 읽기 모두에 적용) 또는 connect,read 형식으로 지정할 수 있습니다. --automation 이 활성화된 경우 기본값은 10,3600 입니다.

--retries 일시적 실패(연결 오류 및 멱등 요청에 대한 HTTP 429/502/503/504)에 대해 시도할 재시도 횟수를 설정합니다. --automation 이 활성화된 경우 기본값은 3, 그렇지 않으면 0 입니다.

--retry-max-time 재시도에 소비할 최대 총 시간(초)을 설정합니다. --automation 이 활성화된 경우 기본값은 120 입니다.

--error-format 출력/오류 형식을 text 또는 json 으로 설정합니다. --automation 이 활성화된 경우 기본값은 json, 그렇지 않으면 text 입니다.

--assume-yes 확인이 필요한 작업을 프롬프트 없이 진행합니다(별칭: --confirm). --automation 이 활성화된 상태에서 파괴적 작업을 수행하려면 필요합니다. 그렇지 않으면 해당 작업은 확인 필요 오류와 함께 실패합니다.

자동화

--automation 을 전달하거나 CORELIGHT_AUTOMATION=1 을 설정하면 자동화 친화적 동작 묶음이 활성화되고 아래의 종료 코드 분류가 켜집니다. 이는 --noblock 을 암시하며 기본값으로 10초 연결 / 3600초 읽기 타임아웃, 3회 재시도(총 120초로 제한), 성공과 오류 모두에 대한 JSON 출력을 사용합니다. 각 부분은 자체 플래그로 재정의할 수 있습니다.

--automation 없이는 요청 타임아웃이 전혀 없으므로(클라이언트가 무한정 차단됨), 이를 활성화해도 이전에 존재하던 타임아웃이 단축되지 않습니다. 기본 읽기 타임아웃은 의도적으로 길게 설정되어 있습니다. 이는 정상적인 작업을 제한하기 위한 것이 아니라 멈춘 연결을 제한하기 위한 것입니다. 대용량 업로드와 같은 일부 작업은 합법적으로 수 분이 걸릴 수 있으며, 읽기 타임아웃은 전체 전송이 아닌 네트워크 읽기마다 적용되므로 꾸준한 업로드는 계속 타임아웃을 재설정합니다. 자동화가 더 빨리 포기하도록 하려면 --timeout 을 낮추고, 느린 링크를 통한 비정상적으로 큰 전송의 경우 높이십시오.

재시도는 멱등성을 인식합니다: GET/HEAD/OPTIONS 요청은 연결 실패 및 HTTP 429/502/503/504에서 재시도합니다. 안전하지 않은 메서드(POST/PUT/DELETE)는 연결이 서버에 도달하기 전에 타임아웃된 경우에만 재시도하므로 변경 사항이 두 번 전송되지 않습니다. 안전하지 않은 메서드의 다른 일시적 실패에 대해서는 클라이언트가 재시도하지 않고 일치하는 코드로 종료하며(JSON 오류 봉투에 retriable 을 설정), 이는 해당 작업을 반복해도 안전한지 유일하게 아는 호출자가 결정할 수 있도록 합니다.

--retry-max-time 은 첫 시도부터 측정하여 요청 자체에 소비된 시간을 포함한 재시도 루프의 총 실시간 예산입니다. 각 새 시도 전에 확인됩니다: 경과 시간에 다음 백오프를 더한 값이 이를 초과하면 더 이상 시도가 시작되지 않습니다. 이미 진행 중인 요청을 중단하지는 않습니다. 단일 요청의 지속 시간은 이 값이 아니라 위의 읽기 타임아웃에 의해 제한됩니다.

종료 코드(자동화가 활성화된 경우에만):

===== ==================================================== Code Meaning ===== ==================================================== 0 성공 1 일반 / 예기치 않은 오류 2 사용법 / 잘못된 인수 3 연결 실패 또는 타임아웃(재시도 후) 4 인증 / 권한 부여(401/403) 5 리소스를 찾을 수 없음(404) 6 서버 오류(5xx) 7 확인 필요(거부 또는 차단됨) 8 지원되지 않는 API 버전 ===== ====================================================

.. _corelight-client-config:

구성 파일

corelight-client 는 구성 파일 ~/.corelight-client.rc 를 찾습니다. 파일은 <key>=<value> 형식의 줄로 구성되어야 합니다. # 로 시작하는 주석은 무시됩니다. corelight-client 는 다음 키를 지원합니다:

device Corelight Sensor 장치의 네트워크 주소입니다.

fleet Corelight Fleet Manager의 네트워크 주소입니다.

uid 지정된 Corelight Fleet Manager를 통해 관리되는 Corelight Sensor의 UID입니다.

user 인증을 위한 사용자 이름입니다.

password 인증을 위한 비밀번호입니다.

mfa Corelight Fleet Manager로 인증하기 위한 2FA 인증 코드입니다. '-'를 사용하면 사용자에게 묻습니다.

ssl-ca-cert 장치의 신뢰성을 검증하기 위한 사용자 지정 SSL CA 인증서가 포함된 파일입니다.

ssl-no-verify-certificate false 로 설정하면 클라이언트가 모든 Corelight Sensor의 SSL 인증서를 수락합니다.

ssl-no-verify-hostname false 로 설정하면 Corelight Sensor의 SSL 인증서가 호스트 이름과 일치하지 않더라도 수락합니다.

socket 요청 전송에 사용할 unix 도메인 소켓입니다.

automation true 값으로 설정하면 자동화 친화적 동작을 활성화합니다. Automation_ 을 참조하십시오.

timeout 요청 타임아웃(초)으로, N 또는 connect,read 형식입니다.

retries 일시적 실패에 대해 시도할 재시도 횟수입니다.

retry-max-time 재시도에 소비할 최대 총 시간(초)입니다.

error-format 출력/오류 형식으로, text 또는 json 입니다.