> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Splunk

> CaseBender와 Splunk(Enterprise Security) 간의 양방향 통합. notable/알림 수집, HEC 감사 전달, notable 종료 동기화를 지원합니다.

## 개요

Splunk 통합(**INT-001**)은 **Splunk Enterprise Security(ES)** notable 이벤트를 포함하여
CaseBender와 Splunk 간의 **양방향** 동기화를 제공합니다.

<CardGroup cols={2}>
  <Card title="인바운드 수집" icon="arrow-right-to-bracket">
    Splunk의 notable과 알림은 CaseBender로 수집됩니다. ES REST 검색 API를 통해 예약된
    일정으로 \*\*자동으로 풀(pull)\*\*되거나 Splunk 알림 액션/웹훅에서 \*\*푸시(push)\*\*된 후,
    정규화되고 관찰 가능 항목으로 보강되어 알림(또는 케이스)으로 변환됩니다.
  </Card>

  <Card title="아웃바운드 동기화" icon="arrow-right-from-bracket">
    케이스 수명 주기 이벤트는 **HEC**를 통해 Splunk 인덱스로 전달되며, 연결된 케이스가
    종료되면 CaseBender는 REST API를 통해 감사 코멘트와 함께 **원본 ES notable을 종료**할 수
    있습니다.
  </Card>
</CardGroup>

<Tip>
  **두 가지 인바운드 경로.** 이미 Splunk에서 알림을 생성한다면 \*\*알림 액션/웹훅(푸시)\*\*을,
  CaseBender가 예약된 일정으로 저장된 검색을 실행하도록 하려면 \*\*자동 폴링(풀)\*\*을 사용하세요.
  폴링에는 Enterprise Security REST 연결이 필요하지만, 웹훅 경로에는 필요하지 않습니다.
</Tip>

<Note>
  아웃바운드 HEC는 **HTTP Event Collector**(기본값 `/services/collector/event`, 일반적으로 포트
  `8088`)를 사용합니다. notable 풀 및 종료는 **관리 REST API**(일반적으로 포트 `8089`)를
  사용합니다. 온프레미스 Splunk는 두 경우 모두 **자체 서명 인증서**를 사용하는 경우가 많으므로
  필요하면 **Verify SSL**을 끄세요(아래 참조).
</Note>

## 기능

| 기능                     | 방향    | 설명                                                                      |
| ---------------------- | ----- | ----------------------------------------------------------------------- |
| **notable 폴링(풀)**      | 인바운드  | CaseBender가 ES REST 검색 API를 통해 SPL을 예약 실행하고 결과를 자동 수집 — Splunk 측 설정 불필요 |
| 알림 수집(푸시)              | 인바운드  | Splunk 알림 액션/웹훅이 페이로드를 전송하며 CaseBender 알림으로 정규화됨                        |
| 관찰 가능 항목 추출            | 인바운드  | `src`/`dest`/`user`(및 `*_ip`) 필드가 IP/호스트명/사용자 관찰 항목이 됨                  |
| 자산 추출                  | 인바운드  | `host`(및 IP가 아닌 `dest`)가 호스트 자산이 됨                                      |
| 케이스 자동 생성              | 인바운드  | 수집된 레코드를 자동으로 케이스로 승격 가능(notable ID로 중복 제거)                             |
| HEC 감사 전달              | 아웃바운드 | 케이스 생성/업데이트/종료 및 알림 승격을 Splunk 인덱스에 기록                                  |
| notable 종료(write-back) | 아웃바운드 | 케이스 종료 시 원본 ES notable을 `notable_update`로 코멘트와 함께 Closed로 설정            |
| 연결 테스트                 | 아웃바운드 | HEC 엔드포인트로 테스트 이벤트 전송                                                   |

## 사전 요구 사항

<Steps>
  <Step title="Splunk 액세스">
    Splunk 배포 환경. notable 풀/종료에는 **Splunk Enterprise Security**와
    `edit_notable_events` 권한을 가진 역할이 필요합니다. HEC 전달에는 **HTTP Event Collector**
    토큰이 필요합니다.
  </Step>

  <Step title="네트워크 아웃바운드">
    CaseBender 배포 환경(및 폴링용 백그라운드 폴러 서비스)은 Splunk **HEC** 엔드포인트(예
    `:8088`)에 도달할 수 있어야 하며, REST 기능의 경우 **관리** 엔드포인트(예 `:8089`)에도
    도달할 수 있어야 합니다.
  </Step>

  <Step title="CaseBender 관리자 역할">
    **설정 → 통합**에서 통합을 생성하고 관리할 수 있어야 합니다.
  </Step>
</Steps>

## 파트 A — Splunk 준비

<Steps>
  <Step title="HEC 토큰 생성(아웃바운드 전달용)">
    Splunk에서 **Settings → Data inputs → HTTP Event Collector → New Token**으로 이동합니다.
    HEC가 아직 활성화되지 않았다면 전역으로 활성화하고, 대상 인덱스를 선택(또는 생성)한 후 토큰
    값을 복사합니다.
  </Step>

  <Step title="인증 토큰 생성(REST 기능용)">
    notable **폴링** 및 **종료**를 위해 **Settings → Tokens**에서 Splunk **인증 토큰**을
    생성합니다(또는 Basic 인증용 서비스 계정 사용). 연결된 역할에는 notable을 종료하기 위한
    `edit_notable_events`와 notable 인덱스에 대한 검색 액세스가 필요합니다.
  </Step>
</Steps>

## 파트 B — CaseBender에서 통합 구성

<Steps>
  <Step title="통합 카탈로그 열기">
    **설정 → 통합 → 생성**으로 이동한 다음 **SIEM** 카테고리에서 **Splunk**를 선택합니다.
  </Step>

  <Step title="목적 선택">
    `purpose`를 **Inbound**, **Outbound** 또는 **Bidirectional**로 설정하면 관련 구성 카드가
    표시됩니다.
  </Step>

  <Step title="인바운드 웹훅(푸시) 구성">
    **Webhook URL**을 복사하고 **API 키**(접두사 `sk_splunk_`)를 생성합니다. Splunk에서 헤더
    `Authorization: Bearer <API_KEY>`를 사용해 해당 URL로 POST하는 **Webhook** 알림 액션을
    추가합니다.
  </Step>

  <Step title="Enterprise Security REST 연결 구성(선택 사항)">
    **Enterprise Security REST API** 카드에 관리 URL(예 `https://splunk:8089`)과 자격 증명을
    입력합니다.

    | 필드                              | 설명                                      |
    | ------------------------------- | --------------------------------------- |
    | `restUrl`                       | Splunk 관리 URI(일반적으로 포트 8089)            |
    | `restAuthType`                  | `token`(bearer) 또는 `basic`(사용자 이름/비밀번호) |
    | `restToken`                     | Splunk 인증 토큰(bearer)                    |
    | `restUsername` / `restPassword` | Basic 인증 자격 증명                          |

    이 연결은 notable **폴링**과 **종료**를 모두 지원합니다.
  </Step>

  <Step title="자동 폴링 활성화(선택 사항)">
    **Automatic polling** 카드에서 **Enable automatic polling**을 켜고 다음을 설정합니다.

    | 옵션                            | 효과                                                                  |
    | ----------------------------- | ------------------------------------------------------------------- |
    | `pollingEnabled`              | Splunk 결과의 예약 풀 활성화                                                 |
    | `searchQuery`                 | 각 간격마다 실행되는 SPL(예 `` search `notable` ``, `search` 또는 `\|`로 시작해야 함) |
    | `pollingIntervalMinutes`      | 폴링 주기(기본값 `5`, 범위 1–1440)                                           |
    | `pollingInitialLookbackHours` | 첫 실행 시 이 기간 내 결과를 가져옴(기본값 `24`, 범위 1–168)                           |

    작동 방식은 [자동 폴링](#인바운드-자동-폴링)을 참조하세요.
  </Step>

  <Step title="아웃바운드 구성(HEC + notable 종료)">
    **Outbound** 카드에 HEC URL, 토큰, 인덱스를 입력한 후 다음을 활성화합니다.

    | 옵션                        | 효과                                                                 |
    | ------------------------- | ------------------------------------------------------------------ |
    | `syncCaseUpdates`         | `case_created` / `case_updated` / `alert_promoted` 감사 이벤트를 HEC로 전달 |
    | `syncCaseClose`           | `case_closed` 감사 이벤트를 HEC로 전달                                      |
    | `closeNotableOnCaseClose` | 연결된 케이스 종료 시 원본 ES **notable**을 REST로 종료                           |
    | `autoCreateCases`         | 수집된 각 Splunk 레코드를 자동으로 **케이스**로 승격                                 |
  </Step>

  <Step title="연결 테스트">
    **Test Connection**을 사용해 HEC 엔드포인트로 테스트 이벤트를 전송합니다. Splunk가 자체 서명
    인증서를 사용하는 경우 **Verify SSL**을 끄세요.
  </Step>
</Steps>

## 인바운드(자동 폴링)

**자동 폴링**을 활성화하면 CaseBender는 Enterprise Security REST 검색 API를 통해 주기적으로
SPL을 실행하고 결과를 스스로 수집합니다. **Splunk 측 알림 액션이나 웹훅이 전혀 필요하지
않습니다.**

### 작동 방식

<Steps>
  <Step title="예약 검색">
    각 간격(`pollingIntervalMinutes`)마다 CaseBender는 스트리밍 내보내기 엔드포인트를 통해 마지막
    커서 이후 기간에 대해 `searchQuery`를 실행합니다.

    ```
    POST https://<splunk>:8089/services/search/jobs/export
        search=<사용자 SPL>&earliest_time=<커서>&latest_time=now&output_mode=json
    ```

    최초 실행 시에는 커서가 없으므로 `pollingInitialLookbackHours` 내의 결과를 가져옵니다.
  </Step>

  <Step title="커서 + 중복 제거">
    CaseBender는 통합별 커서를 확인한 가장 최근 결과 `_time`까지 전진시키므로 각 실행은 새 활동만
    가져옵니다. 결과는 notable의 **`event_id`**(대체로 검색 `sid`)로도 **중복 제거**되므로, 폴링
    기간이 겹치더라도 notable이 두 번 수집되지 않습니다.
  </Step>

  <Step title="정규화">
    각 결과 행은 CaseBender 알림으로 정규화됩니다. `urgency`에서 심각도를 매핑하고, 제목/설명을
    구성하며, 관찰 가능 항목과 호스트 자산을 추출합니다. 나중에 아웃바운드 종료 동기화가 찾을 수
    있도록 notable의 `event_id`가 알림에 각인됩니다.
  </Step>
</Steps>

<Note>
  **`autoCreateCases`가 활성화**되면 폴링된 각 notable은 자동으로 **케이스**가 됩니다(notable
  ID로 중복 제거). 이는 "notable 풀 → 케이스로 처리" 흐름과 일치합니다. 비활성화된 경우 결과는
  수동 승격을 위해 **알림** 받은 편지함에 도착합니다. 어느 경우든 Splunk 링크가 보존되므로
  케이스를 종료하면 notable을 종료할 수 있습니다.
</Note>

<Info>
  폴링은 CaseBender의 백그라운드 폴러 서비스에서 실행됩니다. 해당 서비스가 Splunk 관리
  엔드포인트에(직접 또는 구성된 프록시를 통해) 도달할 수 있는지 확인하세요. 프록시 전용
  네트워크에서는 내부 Splunk 호스트를 `NO_PROXY`에 나열해야 합니다.
</Info>

## 인바운드(웹훅 / 푸시)

폴링의 대안(또는 병행)으로, Splunk **알림 액션**(또는 모든 웹훅 발신자)이 검색 결과를 CaseBender
수집 엔드포인트로 푸시할 수 있습니다.

### 엔드포인트

```
POST https://<사용자-casebender-도메인>/api/v1/ingest/splunk
```

요청은 `Authorization: Bearer <key>`로 전달되는 통합 **API 키**로 인증됩니다(`x-api-key`
헤더도 허용됨). Splunk 웹훅 API 키는 접두사 `sk_splunk_`를 가집니다.

### 페이로드 예시

Splunk의 웹훅 알림 액션은 `result` 객체와 검색 메타데이터를 전송합니다.

```bash theme={null}
curl -X POST "https://<사용자-casebender-도메인>/api/v1/ingest/splunk" \
  -H "Authorization: Bearer sk_splunk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": "scheduler__admin__search__RMD5...",
    "search_name": "Threat - Brute Force Access - Rule",
    "results_link": "https://splunk.example.com/app/search/...",
    "app": "SplunkEnterpriseSecuritySuite",
    "result": {
      "event_id": "A1B2C3D4-...",
      "rule_title": "Brute Force Access Behavior Detected",
      "urgency": "high",
      "security_domain": "access",
      "src": "10.0.0.5",
      "dest": "10.0.0.20",
      "user": "jdoe"
    }
  }'
```

성공한 요청은 HTTP `202 Accepted`를 반환합니다.

```json theme={null}
{ "success": true, "messageId": "..." }
```

### 처리 파이프라인

<Steps>
  <Step title="수집 프록시">
    `/api/v1/ingest/splunk`가 소스를 검증하고 요청을 수집 서비스(`POST /v1/sources/splunk`)로
    전달합니다.
  </Step>

  <Step title="큐 게시">
    수집 서비스가 API 키를 인증하고 페이로드를 검증한 후 레코드를 처리 큐에 게시합니다.
  </Step>

  <Step title="정규화">
    Splunk 프로세서가 레코드를 CaseBender 알림으로 정규화합니다. 심각도를 매핑하고 제목/설명을
    구성하며 관찰 가능 항목과 호스트 자산을 추출합니다.
  </Step>
</Steps>

### 데이터 매핑 참조

**심각도 매핑**(Splunk `urgency` → CaseBender 1–4):

| Splunk urgency          | CaseBender 심각도 |
| ----------------------- | -------------- |
| `critical`              | 4              |
| `high`                  | 3              |
| `medium`                | 2              |
| `low` / `informational` | 1              |

**관찰 가능 항목 / 자산 추출:**

| Splunk 필드          | 관찰 가능 항목 / 자산                 |
| ------------------ | ----------------------------- |
| `src` / `src_ip`   | `ip` 또는 `hostname` 관찰 항목(IOC) |
| `dest` / `dest_ip` | `ip` 또는 `hostname` 관찰 항목      |
| `user`             | `user` 관찰 항목                  |
| `host`             | 호스트 자산                        |

**제목**은 `rule_title` → `search_name` → `alert_name` → `signature` → `message` 순으로
구성됩니다. 수집 시 적용되는 **태그**에는 `splunk`, `siem`, `notable`(ES notable의 경우),
`domain:<security_domain>`, `app:<app>`이 포함됩니다. 수집된 레코드는 기본적으로 **TLP:2** 및
**PAP:2**입니다.

## 아웃바운드: HEC 감사 전달

`syncCaseUpdates` / `syncCaseClose`로 활성화하면 CaseBender는 JSON 감사 이벤트를 HEC
엔드포인트에 게시하여 케이스 활동을 Splunk에서 검색할 수 있게 합니다.

| 이벤트      | HEC `action`             | 조건                |
| -------- | ------------------------ | ----------------- |
| 케이스 생성   | `case_created`           | `syncCaseUpdates` |
| 케이스 업데이트 | `case_updated`           | `syncCaseUpdates` |
| 알림 승격    | `alert_promoted_to_case` | `syncCaseUpdates` |
| 케이스 종료   | `case_closed`            | `syncCaseClose`   |

이벤트는 `source: casebender:case`(또는 `casebender:alert`) 및 `sourcetype: _json`으로 구성된
인덱스에 전송됩니다.

## 아웃바운드: Splunk notable 종료(write-back)

CaseBender에서 케이스가 종료되면 `case_closed` 이벤트가 Splunk 핸들러로 디스패치됩니다. 케이스가
Splunk notable에 연결되어 있고 **또한** `closeNotableOnCaseClose`가 켜져 있으면 CaseBender는 ES
REST API를 통해 notable을 종료합니다.

### 연결된 notable 확인 방법

수집 파이프라인은 각 Splunk 알림의 `customFields`에 `splunkEventId`(notable의 `event_id`)와
수집한 통합 ID를 각인합니다. 케이스 종료 시 핸들러는 케이스에 연결된 알림에서 해당 이벤트 ID를
수집하므로, 폴링 또는 웹훅 notable에서 승격된 케이스는 생성 방식과 관계없이 자동으로 확인됩니다.

### 전송되는 내용

CaseBender는 ES `notable_update` 엔드포인트를 호출합니다.

```
POST https://<splunk>:8089/services/notable_update
    ruleUIDs=["<event_id>", ...]&status=<code>&comment=<comment>&output_mode=json
```

* `status`의 기본값은 \*\*5(Closed)\*\*이며 `notableStatusOnClose`로 구성할 수 있습니다.
* `comment`는 `Case <id> closed in CaseBender with resolution: <resolution>`입니다.

결과(종료된 notable 또는 오류)는 케이스 타임라인에 기록되어 분석가가 동기화를 확인할 수
있습니다.

<Note>
  `syncCaseClose`(HEC 감사 이벤트)와 `closeNotableOnCaseClose`(REST notable write-back)는 통합별
  독립 토글입니다. notable write-back에는 Enterprise Security REST 연결과 `edit_notable_events`
  권한을 가진 역할이 필요합니다.
</Note>

## 보안 고려 사항

* **토큰 처리** — HEC 토큰과 REST 토큰/비밀번호는 통합 설정에 저장됩니다. 조직 일정에 따라
  교체하고, 교체 시 통합을 업데이트하세요.
* **최소 권한** — REST 역할에는 notable 인덱스에 대한 검색 액세스와 `edit_notable_events`만
  필요합니다. HEC 토큰은 전용 인덱스를 대상으로 해야 합니다.
* **웹훅 키** — `sk_splunk_` API 키를 비밀로 취급하세요. 노출되면 교체하고 Splunk 알림 액션을
  업데이트합니다.
* **TLS** — 신뢰할 수 있는 인증서를 선호하세요. 자체 서명 인증서를 사용해야 하는 경우(온프레미스
  에서 일반적) **Verify SSL**을 끌 수 있습니다. 연결은 여전히 암호화되지만 인증서는 검증되지
  않습니다. 아웃바운드를 Splunk HEC 및 관리 엔드포인트로 제한하세요.

## 문제 해결

<AccordionGroup>
  <Accordion title="연결 테스트가 실패하거나 시간 초과됨">
    HEC URL과 토큰, HEC가 활성화되어 있는지, CaseBender가 HEC 포트(일반적으로 `8088`)에 도달할 수
    있는지 확인하세요. Splunk가 자체 서명 인증서를 사용하는 경우 **Verify SSL**을 끄세요. 그렇지
    않으면 인증서 오류로 요청이 실패합니다.
  </Accordion>

  <Accordion title="수집이 401 Unauthorized를 반환함">
    `Authorization: Bearer`(또는 `x-api-key`) 헤더가 누락되었거나 유효하지 않습니다. 통합에 구성된
    웹훅 API 키와 일치하는 `sk_splunk_` 키를 전송하고 있는지 확인하세요.
  </Accordion>

  <Accordion title="폴링이 활성화되었지만 notable이 나타나지 않음">
    **Enable automatic polling**이 켜져 있고 **ES REST** 연결이 입력되어 있으며 **검색 쿼리**가
    설정되어 있는지 확인하세요. 역할이 검색을 실행하고 관리 포트(일반적으로 `8089`)에 도달할 수
    있는지, 커서보다 최신인 결과가 있는지 확인합니다. 첫 실행에서는 `pollingInitialLookbackHours`
    내의 결과만 가져옵니다. 구체적인 오류는 통합의 마지막 동기화 상태에서 확인하세요.
  </Accordion>

  <Accordion title="케이스를 종료해도 Splunk notable이 종료되지 않음">
    `closeNotableOnCaseClose`가 켜져 있고 **ES REST** 연결이 `edit_notable_events` 권한을 가진
    역할로 구성되어 있는지 확인하세요. 케이스는 Splunk notable에 연결되어 있어야 합니다 — 폴링/웹훅
    notable에서 승격된 케이스를 종료하면 링크가 자동으로 확인됩니다. 동기화 결과는 케이스
    타임라인에서 확인하세요.
  </Accordion>

  <Accordion title="notable_update가 403 또는 404를 반환함">
    `403`은 REST 역할에 `edit_notable_events` 권한이 없음을 의미합니다. `404`는 일반적으로 URL이
    Enterprise Security 관리 엔드포인트가 아님을 의미합니다. `restUrl`이 ES가 설치된 Splunk 관리
    포트를 가리키는지 확인하세요.
  </Accordion>

  <Accordion title="프록시 뒤에서 자체 서명 인증서 오류">
    프록시 전용 네트워크에서는 연결이 직접 이루어지도록 내부 Splunk 호스트를 `NO_PROXY`에 추가하고,
    인증서가 자체 서명인 경우 **Verify SSL**을 끄세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [통합 개요](./introduction.mdx)
* [Splunk HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector)
* [Splunk ES notable 이벤트 액션](https://docs.splunk.com/Documentation/ES/latest/User/Triagenotableevents)