# MISP IOC 모으고 STIX 2.1로 내보내기: PyMISP

> 공식 misp-docker 구성으로 MISP를 띄우고 시험용 IOC 8건(example.com 도메인, 문서용 IP, 직접 만든 해시)을 CSV에서 PyMISP로 이벤트 하나에 넣습니다. 이벤트, 속성, 태그가 어떻게 묶이는지 웹 화면으로 보고, REST API로 JSON, CSV, STIX 2.1을 내려받아 indicator 패턴과 observed-data를 읽는 스크립트까지 돌려 봅니다.

- 주소: https://copyandrun.com/blog/misp-docker-ioc-import-export-stix/
- 분야: 위협 인텔리전스
- 발행일: 2026-11-02
- 태그: MISP, IOC, STIX 2.1, PyMISP, 위협 인텔리전스, Docker

MISP는 침해지표(IOC)를 이벤트 단위로 모아 두고 다른 조직이나 도구와 주고받게 해 주는 오픈소스 위협 정보 플랫폼입니다. 이 글은 시험용 IOC 8건을 이벤트 하나에 넣고, 같은 이벤트를 JSON, CSV, STIX 2.1로 내보낸 뒤 STIX 번들에서 무엇이 indicator가 되고 무엇이 빠지는지 읽는 데까지 다룹니다.

Windows Git Bash에서 Docker Desktop으로 실행했습니다. 값은 모두 직접 만든 시험용이며, 도메인은 `example.com`의 하위 이름, IP는 문서용 대역 `192.0.2.0/24`와 `203.0.113.0/24`, 해시는 임의 문자열에서 계산한 값입니다. 서버는 127.0.0.1에만 열고, 아래 비밀번호와 API 키는 이 연습용 서버에서만 쓰는 값이므로 실제 서버에 그대로 쓰지 않습니다.

## 준비물

| 항목 | 확인한 값 |
|---|---|
| Docker / Compose | Docker 29.5.3, Compose 5.1.4 (공식 README는 Docker Engine 25 이상, Compose 2.17 이상을 요구하지만 아래 override 파일의 `!override`는 Compose 2.24.4 이상이 필요) |
| MISP | misp-core v2.5.51 (PHP 8.4.27), misp-modules 3.1.1, misp-stix 2026.10.12 |
| 보조 컨테이너 | MariaDB 10.11.19, Valkey 7.2.15, nginx, SMTP 릴레이 |
| PyMISP | 2.5.34 계열의 네 번째 패치판(호스트의 가상환경, `pip list` 기준) |
| Python | 3.12.10 |
| 내려받은 이미지 | 압축 기준 약 1.3GB, 풀면 misp-core 2.07GB, misp-modules 1.71GB 등 |

작업 폴더는 아래 일곱 파일입니다. 전체 내용은 글 끝의 `## 전체 코드`에 있습니다.

```
setup.sh
docker-compose.override.yml
iocs.csv
import_iocs.py
export_stix.py
read_stix.py
rest_calls.sh
```

## 1. 공식 구성으로 MISP 띄우기

<!-- files: setup.sh, docker-compose.override.yml -->

`setup.sh`는 공식 저장소(`MISP/misp-docker`)의 `docker-compose.yml`과 `template.env`를 내려받아 `.env`의 관리자 이메일, 조직, API 키, 비밀번호, `BASE_URL`을 연습용 값으로 바꿉니다. `docker-compose.override.yml`은 nginx 포트를 `127.0.0.1:18060`에만 열도록 덮어씁니다. 공식 구성의 기본은 모든 인터페이스의 80번이라 그대로 쓰지 않았습니다. `ports` 항목은 기본 병합 규칙으로는 두 파일의 값이 합쳐지므로 `!override` 태그로 통째로 바꿉니다. Docker 공식 문서(`https://docs.docker.com/reference/compose-file/merge/`)가 이 태그에 Compose 2.24.4 이상을 요구한다고 적고 있어, 그보다 낮은 버전이면 먼저 Compose를 올려야 합니다.

```bash
sh setup.sh
docker compose -p cr-c11 up -d
```

첫 실행에는 이미지를 받고 데이터베이스를 만드느라 5분 넘게 걸렸습니다. misp-nginx는 misp-core가 healthy가 될 때까지 `Created` 상태로 기다리므로, 그동안 접속이 안 됩니다. misp-core가 healthy가 되면 같은 명령을 한 번 더 실행해 nginx를 올렸습니다. 상태와 API 응답은 아래 명령으로 확인합니다.

환경 변수를 먼저 지정합니다.

```bash
export MISP_URL=http://127.0.0.1:18060
export MISP_KEY=CrC11LabKeyTestOnly0123456789abcdefghijk
```

그다음 상태와 API 응답을 확인합니다.

```bash
docker compose -p cr-c11 ps --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'
curl -s -H "Authorization: $MISP_KEY" -H "Accept: application/json" $MISP_URL/servers/getVersion | head -3
```

![컨테이너 여섯 개가 healthy이고 nginx가 127.0.0.1:18060에만 연결되며, getVersion 응답에 MISP 2.5.51이 나오는 것을 확인합니다.](https://copyandrun.com/img/misp-docker-ioc-import-export-stix/01-misp-containers-api.png)

가상환경과 PyMISP는 호스트에 설치합니다. Git Bash에서는 활성화 파일이 `Scripts` 폴더에 있습니다. Linux나 macOS에서는 `venv/bin/activate`이며, 이 부분은 실행하지 않았습니다.

```bash
python -m venv venv
source venv/Scripts/activate
pip install pymisp
```

## 2. 이벤트, 속성, 태그 구조

MISP의 단위는 세 겹입니다. 이벤트는 하나의 사건이나 묶음이고 제목, 위협 수준, 분석 상태, 공유 범위(distribution)를 가집니다. 속성(attribute)은 그 안의 IOC 한 건으로 type(`domain`, `ip-dst`, `sha256` 등), category, value와 탐지 대상 여부인 `to_ids`를 가집니다. 태그는 이벤트와 속성 양쪽에 붙으며, `tlp:amber` 같은 taxonomy 태그와 `lab:role="c2"` 같은 직접 만든 machine tag를 쓸 수 있습니다. 공유 범위 값은 MISP 공식 OpenAPI 문서에서 0(이 조직만), 1(이 커뮤니티), 2(연결된 커뮤니티), 3(모든 커뮤니티), 4(공유 그룹), 5(이벤트 따름)로 정의돼 있습니다. 이 글의 이벤트는 0만 씁니다.

## 3. 시험용 IOC를 이벤트로 넣기

<!-- files: iocs.csv, import_iocs.py -->

`iocs.csv`는 8건입니다. 탐지에 쓸 6건은 `to_ids`가 1이고, 정상 파일과 겹칠 수 있는 파일 이름과 메일 제목은 0입니다. 해시는 문자열 `cr-c11 lab sample payload 1`과 `cr-c11 lab dropper 2`에서 계산한 값이라 실제 악성코드와 무관합니다.

`import_iocs.py`는 CSV를 읽어 `MISPEvent` 하나를 만들고, 속성마다 태그를 붙이고, 이벤트에 `tlp:amber`와 `lab:exercise`를 붙여 `add_event`로 보냅니다. 같은 제목의 이벤트가 있으면 새로 만들지 않아서 두 번 실행해도 중복이 생기지 않습니다. 공유 범위는 0으로 두었습니다.

```bash
python import_iocs.py iocs.csv
```

웹 화면(`http://127.0.0.1:18060`, 로그인 ID는 `setup.sh`의 `ADMIN_ID`와 `ADMIN_HOST`를 `@`로 이은 값, 비밀번호는 `ADMIN_PASSWORD`)의 Event Actions에서 이벤트 1을 열면 제목, 위협 수준, 태그가 보입니다.

![이벤트 1의 제목과 Tags 줄에 tlp:amber와 lab:exercise가 붙어 있고, 위협 수준 Low, 분석 Ongoing, 공유 범위 Your organisation only, 속성 8개인 것을 확인합니다.](https://copyandrun.com/img/misp-docker-ioc-import-export-stix/02-event-view-tags.png)

아래쪽 속성 표에서는 category, type, value와 속성별 태그를 한눈에 봅니다.

![속성 8건이 Network activity 4건과 Payload delivery 4건으로 나뉘고 각 행에 lab:role 태그(c2, staging, payload, delivery)가 붙은 것을 확인합니다.](https://copyandrun.com/img/misp-docker-ioc-import-export-stix/03-attributes-table.png)

## 4. REST API로 내보내기

<!-- files: rest_calls.sh -->

같은 데이터를 API로 꺼냅니다. `rest_calls.sh`는 세 번 호출합니다. 속성 검색(`/attributes/restSearch`)에 `to_ids:1`을 주면 탐지 대상 6건만 돌아오고, `returnFormat`을 `csv`로 바꾸면 표 형태가, 이벤트 검색(`/events/restSearch`)에 `stix2`를 주면 STIX 2.1 번들이 옵니다. `returnFormat` 값은 공식 OpenAPI 문서의 목록(json, xml, csv, text, stix, stix2 등)에서 확인했습니다.

```bash
sh rest_calls.sh 1
```

![이벤트 1을 처음 가져올 때는 속성 8개가 만들어지고 다시 실행하면 이미 있다고 나오며, restSearch가 탐지 대상 6건, CSV 헤더, STIX 번들 객체 33개를 돌려주는 것을 확인합니다.](https://copyandrun.com/img/misp-docker-ioc-import-export-stix/04-import-rest-export.png)

## 5. STIX 2.1 내보내기 결과 읽기

<!-- files: export_stix.py, read_stix.py -->

`export_stix.py`는 PyMISP의 `search(return_format="stix2")`로 같은 번들을 파일로 저장하고, `read_stix.py`는 번들을 읽어 세 가지를 보여 줍니다. 객체 종류별 개수, indicator의 STIX 패턴, observed-data가 가리키는 값과 indicator 유무입니다.

```bash
python export_stix.py 1 out.json
python read_stix.py out.json
```

![번들 객체 33개 가운데 indicator 6개, observed-data 8개이고, 파일 이름 report_q4.docm과 메일 제목 Invoice Q4 overdue만 indicator 없음으로 표시되는 것을 확인합니다.](https://copyandrun.com/img/misp-docker-ioc-import-export-stix/05-stix-bundle-read.png)

읽는 방법은 이렇습니다. indicator는 `to_ids`가 1인 6건에만 만들어졌고 `spec_version`은 2.1입니다. 도메인은 `[domain-name:value = ...]`, IP는 `[network-traffic:dst_ref.type = 'ipv4-addr' AND ...]`, 해시는 `[file:hashes.'SHA-256' = ...]` 패턴이며, 속성 태그(`lab:role="c2"`)는 indicator의 `labels`로 따라갑니다. 속성 8건은 모두 observed-data로도 나가고, `to_ids`가 0인 2건은 indicator가 없습니다. 상대 시스템이 indicator만 받아 탐지에 쓴다면 이 2건은 탐지 규칙으로 가지 않는다는 뜻입니다. 이벤트 자체는 grouping 객체(context `suspicious-activity`)로, 조직은 identity로 나갔습니다. 이벤트 태그 `tlp:amber`는 TLP:AMBER marking-definition이 되었고 `lab:exercise`는 grouping의 `labels`에 들어갔습니다. relationship 6개는 `based-on`으로 indicator를 observed-data에 잇습니다.

## 결과 정리

- 이벤트 하나에 속성 8건과 태그를 넣었고, 탐지 대상 여부는 속성의 `to_ids`로 정합니다.
- 같은 이벤트를 `restSearch`의 `returnFormat`만 바꿔 JSON, CSV, STIX 2.1로 받았습니다.
- STIX 번들에서 indicator는 `to_ids`가 1인 속성에서만 만들어지므로, 내보내기 전에 어떤 속성을 탐지에 쓸지 먼저 정해야 합니다.

## 전체 코드

작업 폴더 구조는 아래와 같습니다.

```
setup.sh
docker-compose.override.yml
iocs.csv
import_iocs.py
export_stix.py
read_stix.py
rest_calls.sh
```

### setup.sh

```bash
#!/bin/sh
# 공식 misp-docker 구성을 내려받아 연습용 값으로 .env 를 만듭니다.
# 아래 비밀번호와 API 키는 이 연습용 서버에서만 쓰는 값이며 실제 서버에 쓰지 않습니다.
ADMIN_ID=admin
ADMIN_HOST=example.com
BASE=https://raw.githubusercontent.com/MISP/misp-docker/master
curl -sL $BASE/docker-compose.yml -o docker-compose.yml
curl -sL $BASE/template.env -o .env
sed -i \
  -e "s|^ADMIN_EMAIL=.*|ADMIN_EMAIL=$ADMIN_ID@$ADMIN_HOST|" \
  -e 's|^ADMIN_ORG=.*|ADMIN_ORG=LabOrg|' \
  -e 's|^ADMIN_KEY=.*|ADMIN_KEY=CrC11LabKeyTestOnly0123456789abcdefghijk|' \
  -e 's|^ADMIN_PASSWORD=.*|ADMIN_PASSWORD=Lab-Misp-Pass-2026|' \
  -e 's|^BASE_URL=.*|BASE_URL=http://localhost:18060|' .env
grep -E '^(CORE_TAG|MODULES_TAG|ADMIN_ORG|BASE_URL)=' .env
```

### docker-compose.override.yml

```yaml
services:
  misp-nginx:
    ports: !override
      - "127.0.0.1:18060:8080"
```

### iocs.csv

```
type,value,category,to_ids,comment,tags
domain,c2.lab-ioc.example.com,Network activity,1,시험용 명령 서버 도메인,lab:role="c2"
url,http://c2.lab-ioc.example.com/gate.php,Network activity,1,시험용 접속 주소,lab:role="c2"
ip-dst,192.0.2.45,Network activity,1,문서용 대역의 시험용 IP,lab:role="c2"
ip-dst,203.0.113.77,Network activity,1,문서용 대역의 시험용 IP,lab:role="staging"
sha256,a01c3c2158fc074d263801a3f0e8ae6cd39686887e394cd84f778d3292e43b8f,Payload delivery,1,문자열 cr-c11 lab sample payload 1 의 해시,lab:role="payload"
md5,84cd7f848578a75ff25650f87f1be911,Payload delivery,1,문자열 cr-c11 lab dropper 2 의 해시,lab:role="payload"
filename,report_q4.docm,Payload delivery,0,시험용 첨부 파일 이름(정상 파일과 겹칠 수 있어 탐지에서 제외),lab:role="payload"
email-subject,Invoice Q4 overdue,Payload delivery,0,시험용 메일 제목(탐지에서 제외),lab:role="delivery"
```

### import_iocs.py

```python
"""iocs.csv 를 읽어 MISP 이벤트 하나로 등록합니다. PyMISP 를 씁니다.

사용법: MISP_URL=http://127.0.0.1:18060 MISP_KEY=<API 키> python import_iocs.py iocs.csv
같은 제목의 이벤트가 이미 있으면 새로 만들지 않고 그 이벤트 번호만 출력합니다.
"""
import csv
import os
import sys

from pymisp import MISPEvent, PyMISP

INFO = "시험용 침해지표 묶음 (cr-c11)"
EVENT_TAGS = ["tlp:amber", "lab:exercise"]

misp = PyMISP(os.environ["MISP_URL"], os.environ["MISP_KEY"], ssl=False)

found = misp.search(controller="events", eventinfo=INFO, pythonify=True)
if found:
    print("이미 있음: 이벤트", found[0].id)
    sys.exit(0)

event = MISPEvent()
event.info = INFO
event.distribution = 0        # 0: 이 조직만 볼 수 있음
event.threat_level_id = 3     # 3: 낮음
event.analysis = 1            # 1: 진행 중

with open(sys.argv[1], encoding="utf-8", newline="") as f:
    for row in csv.DictReader(f):
        attr = event.add_attribute(
            row["type"], row["value"],
            category=row["category"],
            to_ids=row["to_ids"] == "1",
            comment=row["comment"],
        )
        attr.add_tag(row["tags"])

for tag in EVENT_TAGS:
    event.add_tag(tag)

created = misp.add_event(event, pythonify=True)
print("만든 이벤트:", created.id, "속성", len(created.attributes), "개")
```

### rest_calls.sh

```bash
#!/bin/sh
# REST API 로 같은 이벤트를 JSON, CSV, STIX 2.1 로 내려받습니다. 사용법: sh rest_calls.sh <이벤트 번호>
URL=http://127.0.0.1:18060
KEY=CrC11LabKeyTestOnly0123456789abcdefghijk
H="-H Authorization:$KEY -H Accept:application/json -H Content-Type:application/json"

echo '--- 속성 검색(JSON), 탐지 대상만'
curl -s $H -X POST $URL/attributes/restSearch \
  -d "{\"returnFormat\":\"json\",\"eventid\":$1,\"to_ids\":1}" \
  | python -c "import sys,json;[print(a['type'],a['value']) for a in json.load(sys.stdin)['response']['Attribute']]"

echo '--- CSV 내보내기 첫 3줄'
curl -s $H -X POST $URL/attributes/restSearch -d "{\"returnFormat\":\"csv\",\"eventid\":$1}" | head -3 | cut -d, -f3-5

echo '--- STIX 2.1 내보내기 요약'
curl -s $H -X POST $URL/events/restSearch -d "{\"returnFormat\":\"stix2\",\"eventid\":$1}" \
  | python -c "import sys,json;b=json.load(sys.stdin);print(b['type'],len(b['objects']),'개 객체')"
```

### export_stix.py

```python
"""이벤트를 STIX 2.1 로 내보내 파일로 저장합니다. PyMISP 를 씁니다.

사용법: MISP_URL=... MISP_KEY=... python export_stix.py <이벤트 번호> out.json
"""
import json
import os
import sys

from pymisp import PyMISP

misp = PyMISP(os.environ["MISP_URL"], os.environ["MISP_KEY"], ssl=False)
bundle = misp.search(controller="events", eventid=sys.argv[1], return_format="stix2")
with open(sys.argv[2], "w", encoding="utf-8") as f:
    json.dump(bundle, f, ensure_ascii=False, indent=2)
print("저장:", sys.argv[2], "객체", len(bundle.get("objects", [])), "개")
```

### read_stix.py

```python
"""STIX 2.1 번들을 읽어 객체 종류별 개수와 indicator 의 패턴을 보여 줍니다. 표준 라이브러리만 씁니다.

사용법: python read_stix.py out.json
"""
import json
import sys
from collections import Counter

bundle = json.load(open(sys.argv[1], encoding="utf-8"))
objs = bundle["objects"]
print("번들", bundle["id"], "| 형식", bundle["type"], "| 객체", len(objs), "개")

print("\n[1] 객체 종류별 개수")
for kind, n in sorted(Counter(o["type"] for o in objs).items()):
    print(f"  {kind:<20}{n}")

print("\n[2] indicator 패턴")
for o in objs:
    if o["type"] == "indicator":
        print(f"  {o['pattern']}")
        print(f"      spec {o['spec_version']} | 유효 시작 {o['valid_from'][:19]} | 레이블 {[l for l in o.get('labels', []) if l.startswith('lab:')]}")

print("\n[3] observed-data 가 가리키는 값과 indicator 유무")
by_id = {o["id"]: o for o in objs}
patterns = " ".join(o["pattern"] for o in objs if o["type"] == "indicator")
for o in objs:
    if o["type"] != "observed-data":
        continue
    for ref in o.get("object_refs", []):
        t = by_id.get(ref, {})
        if t.get("type") in ("domain-name", "url", "ipv4-addr", "file", "email-message"):
            value = t.get("value") or t.get("name") or t.get("subject")
            if not value and t.get("hashes"):
                value = next(iter(t["hashes"].values()))
            mark = "indicator 있음" if value in patterns else "indicator 없음"
            print(f"  {t['type']:<14}{str(value)[:44]:<46}{mark}")
```

## 자주 막히는 곳

- **접속이 안 되고 misp-nginx가 `Created`에서 멈춥니다.** misp-core가 healthy가 될 때까지 nginx가 시작되지 않습니다. 이번에는 첫 기동에 5분 남짓 걸렸습니다. `docker compose -p cr-c11 ps`에서 core가 healthy가 된 뒤 `up -d`를 한 번 더 실행합니다.
- **이벤트 화면에 분홍색 Distribution 경고가 뜹니다.** 처음에 `tlp:green`을 붙이고 공유 범위를 0으로 두었더니 "tlp:green은 커뮤니티 전체 공유를 가정하는데 공유 범위가 맞지 않는다"는 경고가 나왔습니다. 조직 안에서만 보는 이벤트라 `tlp:amber`로 바꾸었고 경고가 사라졌습니다.
- **스크립트를 다시 실행하면 이벤트가 또 생길까 걱정됩니다.** `import_iocs.py`는 같은 제목을 먼저 검색해서 있으면 만들지 않습니다. 이벤트를 지우고 다시 만들면 이벤트 번호가 1이 아닌 2로 이어지므로, 이후 명령의 번호를 바꿔야 합니다. 이 글은 새로 올린 서버에서 1번으로 만든 결과입니다.
- **`.env`가 비어 있으면 로그인 정보를 알 수 없습니다.** 공식 README는 기본 계정으로 도메인이 `admin.test`인 `admin` 사용자와 비밀번호 `admin`을 안내합니다. 이 글은 `setup.sh`로 값을 지정했고, 기본 계정은 시험하지 않았습니다.

## 확인 범위

- **확인한 것:** 위의 모든 명령과 출력은 Docker Desktop의 Windows 호스트에서 실제로 실행한 결과입니다. 공식 구성은 `https://github.com/MISP/misp-docker`(README, `docker-compose.yml`, `template.env`)에서, API 값은 `https://github.com/MISP/MISP/blob/develop/app/webroot/doc/openapi.yaml`에서 확인했습니다(`returnFormat`의 stix2, 공유 범위 0에서 5의 의미). 5가 속성에만 쓰는 값인지는 이 문서의 설명(`Inherit Event`)만으로는 확인하지 못했습니다. Compose의 `!override` 최소 버전은 `https://docs.docker.com/reference/compose-file/merge/`의 Requires 항목(2.24.4 이상)에서 확인했고, 실제 사용한 Compose는 5.1.4입니다. 시각은 컨테이너의 UTC 기준입니다.
- **하지 못한 것:** 이벤트 게시(publish)와 다른 MISP 서버와의 동기화, 피드, 보강 모듈(misp-modules) 사용은 실행하지 않았습니다. STIX 번들을 TAXII 서버로 보내거나 다른 TIP에 읽어 들이는 부분, Linux와 macOS 명령은 실행하지 않았습니다. `docker-compose.yml`은 저장소의 최신판을 받으므로 내용이 달라질 수 있고, 이 글은 2026년 11월에 받은 판(CORE_TAG v2.5.51)을 썼습니다.
- **범위의 한계:** STIX 변환 결과는 misp-stix 2026.10.12와 MISP 2.5.51 조합에서 나온 것이며 버전이 바뀌면 객체 구성이 달라질 수 있습니다. 시험용 값은 실제 위협 정보가 아니므로 탐지 규칙에 쓰지 않습니다.
