규칙 언어도, 튜닝 의식도, ML도 없습니다. **트레일**은 악성으로 알려진 도메인, URL, IP 주소, `IP:port` 또는
User-Agent이며, Maltrail은 이 중 하나가 네트워크 트래픽에 나타나면
알려줍니다.

---

## 목차

- [왜 Maltrail인가](#why-maltrail)
- [아키텍처](#architecture)
- [성능](#performance)
- [빠른 시작](#quick-start)
  - [서비스로 실행](#as-a-service)
  - [Docker](#docker)
- [구성](#configuration)
- [트레일](#trails)
- [이벤트](#events)
- [운영](#operating-it)
  - [이벤트 보존](#event-retention)
- [문서](#documentation)
- [기여](#contributing)
- [라이선스](#licence)
- [스폰서](#sponsors)
- [개발자](#developers)
- [프레젠테이션](#presentations)
- [출판물](#publications)
- [블랙리스트](#blacklist)
- [감사의 말](#thank-you)
- [타사 통합](#third-party-integrations)

---

## 왜 Maltrail인가

대부분의 네트워크 탐지 도구는 *행동*을 설명하라고 요구합니다. Maltrail은 대부분의 실제 사고를 해결하는 더 단순한 질문을 던집니다: **이 호스트가 이미 악성으로 알려진 대상과 통신하고 있습니까?**

* **150만 개 이상의 트레일** — 3,000개 이상의 선별된 정적 목록과 46개의 공개 피드에서 얻어지며, 매일 갱신되고 계속 늘어납니다. **악성코드** — C2 도메인, 드로퍼, 스틸러, APT 인프라 — 에 크게 치중되어 있는데, 이는 실제 침해에서 바로 그것들이 나타나기 때문입니다.
* **트레일은 일반 텍스트입니다.** 줄마다 하나의 지표가 들어 있으며, 읽고, grep하고, 풀 리퀘스트를 보낼 수 있는 파일입니다. 그래서 커버리지가 최신으로 유지되며, "왜 이게 탐지됐지?"라는 질문에 항상 답할 수 있습니다.
* **성능에 대해 고민하지 않아도 될 만큼 빠릅니다.** 단일 코어가 현실적인 트래픽 구성에서 10 GbE 링크를 처리합니다. [성능](#performance)을 참조하세요.
* **휴리스틱은 대체가 아니라 그 위에 추가됩니다** — 각각은 이벤트에 이름으로 기록되며, 결코 막연한 점수가 아닙니다: 포트, UDP 및 웹 스캐닝, DNS 소진, DGA 형태의 조회(엔트로피 및 자음 임계값, 과도한 NXDOMAIN), 싱크홀 처리/압수/파킹된 도메인, 긴 도메인, 직접 IP 및 IoT 악성코드 다운로드, 의심스러운 사용자 에이전트 및 프록시 프로브.

---

## 아키텍처

두 개의 독립적인 프로세스로 구성됩니다. 한 대의 서버 또는 여러 대에서 실행할 수 있습니다.```
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching, heuristics

**두 번째로 출력되는 테이블을 읽으세요. 첫 번째가 아닙니다.** 두 가지를 보고하며, 각각 다른 질문에 답합니다.

* **전체 프로세스** — 시작 시간을 포함하며, 짧은 재생에서는 그것이 곧 측정값입니다: 150만 행 트레일 세트를 로드하는 데 Rust 센서는 약 1.1~1.5초가 걸리고, 30만 패킷은 1초 미만이 걸립니다. 그 비율은 약 **3×**가 나오며, 이는 패킷 경로가 아닙니다.
* **정상 상태** — 시작 시간은 1패킷 재생으로 별도 측정하여 차감합니다. 이것이 패킷당 비용이며, 위의 **14~37배**입니다.

트레일 로딩은 이전 센서가 여전히 우위를 점하는 유일한 부분입니다: 미리 빌드된 `trails.csv.bin` 사이드카를 mmap하므로 *웜* 시작이 CSV에서 저장소를 빌드하는 것보다 빠릅니다 — RPi 5에서 1.25초 대 2.24초. 이 비용은 프로세스당 한 번만 지불되며, 패킷 경로는 30만 번 지불됩니다.

두 수치 모두 하드웨어에 따라 달라지므로 직접 측정하세요 — 그리고 이 혼합 트래픽은 의도적으로 무해한 트래픽이므로 하네스가 두 센서 모두에 대해 `events=0`을 보고한다는 점에 유의하세요. 탐지 기능은 그 위에 이벤트 로깅 비용을 추가합니다.

메모리는 코어 수에 따라 늘어나지 않습니다: 150만 트레일 저장소는 **68.5 MB**이며, 모든 워커가 변경 불가능하게 공유합니다. 이를 빌드하는 것은 위의 시작 비용입니다 — Ryzen 7 PRO 4750U에서 1.2초, RPi 5에서 2.2초 — 그리고 프로세스당 한 번만 지불되며 워커당이 아닙니다.

**기본적으로 캡처 워커는 하나입니다.** 해당 패킷 경로는 2-vCPU VM에서 이 혼합 트래픽의 4.2 Gbit/s, RPi 5에서 8.7 Gbit/s, Ryzen 9 5900X에서 25.5 Gbit/s를 처리합니다 — 모든 경우에 호스트의 네트워크 인터페이스가 전달할 수 있는 것보다 많으므로, 기본값이 하나인 것은 절충이 아니라 선택입니다. 추가 워커는 명시적 옵트인(`CAPTURE_FANOUT`)이며, 커널이 캡처를 플로우 해시하는 반면 스캔 휴리스틱은 소스별로 계산하기 때문입니다: 워커 하나가 발생시키는 휴리스틱 알림 중 2소켓에서 91%, 4소켓에서 86%, 8소켓에서 65%가 유지됩니다. 정확한 트레일 탐지는 모든 워커 수에서 동일합니다. `maltrail_capture_dropped_total`이 말할 때 확장하세요, 그 전이 아닙니다.

<sub>모든 수치: 휴리스틱 활성화, 실제 150만 행 트레일 세트, 캡처 워커 하나, 세 번 실행 중 가장 빠른 값. 정상 상태 비율은 위 프로세서들에서 14~37배 범위였습니다. 워커 하나가 흡수할 수 있는 트래픽 양을 결정하는 것은 패킷당 비용입니다. 방법, 프로토콜별 분석, 명령어 수 및 프로파일러 출력은 [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md)에 있습니다.</sub>

---

## 빠른 시작

먼저 사전 요구 사항을 설치하세요 — **전부**, 그렇지 않으면 링크 단계에서 `cannot find -lpcap` 오류와 함께 빌드가 실패합니다:```bash
# Debian / Ubuntu / Raspberry Pi OS
sudo apt-get install cargo libpcap-dev libcap2-bin python3
# RHEL / Fedora
sudo dnf install cargo libpcap-devel libcap python3
# openSUSE / SLES     (do NOT add rustup; the packaged rust 1.74 already qualifies)
sudo zypper install cargo rust libpcap-devel libcap-progs python311

`x86_64` 및 `aarch64`용 사전 빌드된 센서 바이너리는 SHA-256 체크섬과 함께 모든
[릴리스](https://github.com/stamparm/maltrail/releases)에 첨부됩니다 — 런타임에는 libpcap만 필요하며
툴체인이 전혀 필요하지 않습니다. 이 바이너리는 **glibc 2.28**을 대상으로 빌드되었으므로
RHEL 8+, Debian 10+, Ubuntu 18.04+ 및 openSUSE Leap 15.x에서 실행됩니다. 릴리스는
더 새로운 버전이 필요한 바이너리를 게시하지 않습니다. musl(Alpine)에서는 대신 소스에서 빌드하세요. 소스에서 빌드하려면:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail

# 1. build the sensor
cd sensor && cargo build --release && cd ..

# 2. let it capture without running as root
sudo setcap cap_net_raw,cap_net_admin=eip sensor/target/release/maltrail-sensor

# 3. give it somewhere to write events (LOG_DIR, /var/log/maltrail by default)
#    ('id -gn', not "$USER": not every distribution gives each user their own group)
sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail

# 4. check the deployment before trusting it — exits non-zero if anything is wrong
sensor/target/release/maltrail-sensor -T

# 5. run it (first start builds the trail set; takes a minute)
sensor/target/release/maltrail-sensor

그런 다음 <http://127.0.0.1:8338>을(를) 열고 `maltrail.conf`(`USERS`)에 있는 자격 증명으로 로그인하세요.

`-T`는 "이거 작동할까?"의 단축키입니다. 설정, 트레일, 화이트리스트, 로그 디렉터리, 캡처 필터 및 권한을 검증하고 정확히 무엇이 누락되었는지 알려줍니다:```
[o] log directory: '/var/log/maltrail' is writable
[o] log storage: 199.0 GB free on '/var/log/maltrail'
[o] capture filter: udp or icmp or (tcp and (tcp[tcpflags] == tcp-syn or port 80 or port...
[o] capture privileges: CAP_NET_RAW present
[o] interface: any
[o] workers: 1 - undiluted per-source heuristics; raise 'CAPTURE_FANOUT' only if
    'maltrail_capture_dropped_total' climbs
[o] whitelist: 3440 entries, 18 CIDR range(s)
[o] trails: 1505265 loaded (0 malformed row(s)), ipv4=144758 ipv4:port=253517 ipv6=2014 wildcard=29
[o] trail updates: updater present, python3 is Python 3.12.3
[o] heuristics: on (disabled: none)
[o] USE_CONDENSED_STORAGE: on, writing '/var/log/maltrail/meta.sqlite'
[i] configuration test PASSED

이것이 전체 설치입니다 — 생성할 디렉터리도, `setcap`도 필요 없습니다. 유닛들은
systemd의 `LogsDirectory=`/`StateDirectory=`를 통해 `/var/log/maltrail`(이벤트)과 `/var/lib/maltrail`(트레일 집합)을 생성하고 소유하며,
비특권 `maltrail` 사용자로 두 프로세스를 읽기 전용 파일시스템에서 실행하고,
센서에는 정확히 `CAP_NET_RAW`와 `CAP_NET_ADMIN`만 부여합니다 — 그 외에는 아무것도,
어디에도 root는 없습니다. 센서는 `ExecStartPre`로 `-T`를 실행하므로, 잘못된 배포는
`systemctl start` 시점에 실패하며, 무작정 실행되지 않습니다.

확인해 보세요: `systemctl status maltrail-sensor` 및 `journalctl -u maltrail-sensor -f`.

### Docker```bash
docker compose -f docker/docker-compose.yml up -d

인디케이터를 추가한다는 것은 텍스트 파일에 한 줄을 추가하는 것입니다. 피드를 추가하는 것은 작은 Python 모듈입니다. 둘 다
일반적인 pull request이며, 그 마찰이 낮기 때문에 세트가 계속 유용하게 유지됩니다.

자체 인디케이터는 `CUSTOM_TRAILS_DIR`에 넣고, 절대 듣고 싶지 않은 것은
`USER_WHITELIST`에 넣습니다.

---

## 이벤트

탐지 하나당 한 줄이며, 공백으로 구분하고, 필요한 경우 CSV 따옴표로 묶습니다:```
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

하나의 도메인, IP 또는 URL이 트레일 집합에 있는지, 그리고 어떤 키가 일치했는지 답합니다. 나열된 도메인의 서브도메인은 상위 도메인으로 보고되며, URL은 `host/path`로 먼저 시도된 후 호스트 자체로 시도됩니다. 메모리 매핑된 트레일 저장소를 통해 읽으므로 서버 메모리를 소비하지 않으며, 재시작 없이 트레일 업데이트를 반영합니다.

**공개** 트레일 집합에 대해서는 옆에 있는 `/trails`와 마찬가지로 인증이 필요 없습니다. 해당 엔드포인트는 이미 누구에게나 정적 및 피드 트레일을 제공하며(센서가 `UPDATE_SERVER`에서 가져오는 방식입니다), 따라서 이들에 대한 단일 키 조회는 같은 포트에 이미 공개된 정보보다 엄격히 더 적은 정보만 노출합니다.

**사용자 정의 트레일은 세션이 필요합니다.** 이는 공개 데이터가 아니라 사용자 자신의 지표이며, `ENABLE_MASK_CUSTOM`은 이미 비관리자 사용자에게 그 이름을 숨깁니다. 따라서 `/check`는 이를 볼 권한이 없는 사용자에게 사용자 정의 전용 일치를 miss로 보고합니다. 이벤트 데이터는 완전히 게이트된 상태로 유지됩니다.

---

## 운영하기

* **`-T`**는 구성을 검증하고 종료합니다. 배포 게이트로 사용할 수 있으며, systemd 유닛은 이를 `ExecStartPre`로 실행합니다.
* **`STATS_ADDRESS`**는 Prometheus 메트릭을 노출합니다. 알림을 설정할 가치가 있는 네 가지는 모두 *이 센서가 생각하는 대로 탐지하고 있지 않다*는 뜻입니다:

  | metric | 의미 |
  | --- | --- |
  | `maltrail_up == 0` | 실행 중인 캡처 워커가 없음 — 이 호스트는 **모니터링되지 않음** |
  | `rate(maltrail_capture_dropped_total)` | 링이 패킷을 버리고 있음 — **탐지 누락** |
  | `rate(maltrail_local_log_errors_total)` | 탐지가 생성된 후 **유실됨** |
  | `maltrail_trail_generation` not advancing | 트레일이 더 이상 갱신되지 않음 |

  유용한 항목: `maltrail_log_dir_free_bytes`(아래 참조)와 `maltrail_state_saturations_total` — 상태 고갈 플러드가 휴리스틱을 좁혔을 때 0이 아닌 값을 가집니다. 정확한 트레일 매칭은 설계상 이에 영향을 받지 않습니다.
* **`systemctl reload`**(`SIGHUP`)는 재시작 없이 트레일을 다시 로드합니다. 다른 무엇으로 갱신된 트레일은 원자적 교체로 1초 이내에 반영됩니다 — 재시작도, 패킷 손실도 없습니다.
* **축약 관측치 저장소**(`USE_CONDENSED_STORAGE`, `meta.sqlite`)는 서버의 `/meta` novelty 및 retro-hunt 뷰에 데이터를 공급하며, 기존 센서가 생성하는 것과 동일한 형식으로 작성됩니다. 두 센서는 패리티 하니스에서 행 단위로 비교됩니다. 두 센서 간의 모든 의도적 차이는 [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/COMPATIBILITY.md)에 나열되어 있습니다.

### 이벤트 보존

**Maltrail은 이벤트 증거를 절대 삭제하지 않습니다.** 로그를 만료시키는 보존 설정이 없으며, 이는 의도적입니다. 이는 사고 후 돌아가서 확인하는 기록이며, 조용히 폐기하는 도구는 이 기록이 필요한 바로 그 한 주 동안 무용지물보다도 못합니다.

그렇기에 여유 공간은 무시할 것이 아니라 운영해야 할 대상이 됩니다:

* **영구 사본을 박스 외부로 보냅니다.** `LOG_SERVER`(또는 `SYSLOG_SERVER` / `LOGSTASH_SERVER`)는 서버나 SIEM을 기록 시스템으로 만들고, 센서의 로컬 파일은 버퍼가 됩니다. 이것이 보존 전략입니다. 로컬 디스크는 보존 전략이 아닙니다.
* **`maltrail_log_dir_free_bytes`에 실제 여유를 두고 알림을 설정합니다.** `-T`도 이를 보고하며 10 GB 미만이면 경고합니다. 0이 되면 센서는 추가 기록을 할 수 없고 탐지 결과가 유실됩니다.
* **아카이빙은 운영자가 결정합니다.** 공간이 필요하다면 자신의 일정에 따라 오래된 일별 로그를 압축하거나 이동하세요. 보고 UI는 과거 로그를 일반적인 seek 가능 파일로 제공하므로, 제자리에서 압축하면 해당 일자가 인터페이스에서 사라집니다 — 다른 곳에 아카이브하세요.

정책상 삭제가 *필수*라면(이벤트 로그에는 일부 관할권에서 개인 데이터로 간주되는 IP 주소와 도메인이 포함되어 있습니다), 이는 명시적인 운영자 결정입니다. 센서 기본값이 조용히 수행하게 두지 말고, 의도적으로 자체 도구로 처리하세요.

---

## 문서

| | |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md) | 설치, 권한, 구성, 문제 해결 |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/ARCHITECTURE.md) | 센서가 내부적으로 동작하는 방식 |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/COMPATIBILITY.md) | 기존 센서와의 모든 의도적 차이 |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md) | 측정, 프로파일 및 테스트 결과 |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/ROADMAP.md) | 아직 남아 있는 작업 |
| [`old/README.md`](https://github.com/stamparm/maltrail/blob/HEAD/old/README.md) | 참조 및 테스트 오라클로 유지되는 이전 Python 센서 |

---

## 기여하기

트레일이 가장 가치 있는 기여입니다: 출처와 함께 올바른 파일에 한 줄을 추가하는 것입니다. 피드, 버그 리포트, 센서 작업 모두 환영합니다.

센서의 전체 게이트는 단일 명령입니다:```bash
bash sensor/tools/check.sh