Maltrail은 지표 기반 네트워크 모니터링을 위해 설계되었습니다. 휴리스틱 탐지는 트레일 매칭을 보완하지만, 엔드포인트 텔레메트리나 범용 침입 방지 시스템을 대체하지는 않습니다.

## 기능

- 3,000개 이상의 번들 정적 파일, 42개의 공개 피드 통합, 선택적 운영자 제공 트레일을 결합한 전체 트레일 구축.
- libpcap을 사용하는 멀티스레드 Rust 센서로, 선택적 Linux `PACKET_FANOUT` 캡처 워커 지원.
- 보고 인터페이스, 이벤트 수신, HTTP API를 제공하는 Python 서버.
- 검토 및 버전 관리가 가능한 일반 텍스트 사용자 정의 트레일 및 화이트리스트.
- 스캐닝, DNS 고갈, DGA 유사 조회, 의심스러운 다운로드, 프록시 프로브, 의심스러운 User-Agent 값 및 관련 네트워크 활동에 대한 휴리스틱.
- 로컬 이벤트 로깅, 원격 Maltrail 로깅, syslog를 통한 CEF, Logstash JSON 출력.
- `maltrail-sensor -T`를 통한 배포 검증 및 선택적 Prometheus 메트릭.

## 목차

- [아키텍처](#architecture)
- [보고 인터페이스](#reporting-interface)
- [성능](#performance)
- [설치](#installation)
  - [설치 프로그램](#installer)
  - [소스에서 빌드](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [구성](#configuration)
- [트레일](#trails)
- [이벤트 및 API](#events-and-api)
- [운영](#operations)
  - [모니터링](#monitoring)
  - [이벤트 보존](#event-retention)
- [문서](#documentation)
- [기여](#contributing)
- [프로젝트](#project)
  - [라이선스](#license)
  - [유지관리자](#maintainers)
  - [스폰서](#sponsors)
  - [발표 및 간행물](#presentations-and-publications)
  - [파생 블랙리스트](#derived-blacklist)
  - [타사 통합](#third-party-integrations)
  - [감사의 말](#acknowledgements)

## 아키텍처

Maltrail은 동일한 호스트 또는 별도의 호스트에서 실행될 수 있는 두 개의 독립적인 프로세스로 구성됩니다:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

캡처 작업자는 기본적으로 하나가 사용됩니다. 작업자를 추가하면 캡처 용량을 늘릴 수 있지만, Linux
흐름 해싱은 작업자 간에 소스별 상태를 분할하므로 일부 스캔 휴리스틱의 민감도가 낮아집니다.
문서화된 테스트에서 단일 작업자 휴리스틱 경고의 91%가 두 작업자에서 유지되었고, 네 작업자에서는 86%, 여덟 작업자에서는 65%였습니다.
정확한 트레일 매칭은 변경되지 않았습니다. 캡처 드롭 메트릭에서 필요하다고 확인될 때만
`CAPTURE_FANOUT`을 늘리십시오.

벤치마크 방법론, 하드웨어 결과, 프로파일러 출력, 메모리 측정 및 실시간 팬아웃
검사는 [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md)에 문서화되어 있습니다.

## 설치

### 설치 프로그램

설치 프로그램은 Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora 및 openSUSE를 지원합니다:```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Common installer options:```bash
sh install.sh --role sensor      # Install only the sensor
sh install.sh --ref 3.1.2        # Install a release tag instead of master
sh install.sh --no-service       # Install without changing systemd
sh install.sh --dry-run          # Print commands without applying them
sh install.sh --uninstall        # Remove the managed installation; keep logs and state

그런 다음 센서를 빌드하고 검증합니다:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail

cargo build --release --manifest-path sensor/Cargo.toml

sudo setcap cap_net_raw,cap_net_admin=eip \
  sensor/target/release/maltrail-sensor

sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail

sensor/target/release/maltrail-sensor -T
sensor/target/release/maltrail-sensor

Prebuilt `x86_64` 및 `aarch64` 센서 바이너리는 SHA-256 체크섬과 함께 현재 릴리스에 첨부되어 있습니다. 이들은 libpcap을 정적으로 링크하고 glibc 2.28을 대상으로 하므로, RHEL 8+, Debian 10+, Ubuntu 18.04+ 및 Leap 15.x에서 C 라이브러리만 있으면 됩니다 — 설치할 것이 없습니다. Alpine Linux와 같은 musl 기반 시스템에서는 소스에서 빌드하세요.

**3.1.1 및 이전 버전**의 바이너리는 그렇지 않았습니다. 이들은 libpcap을 동적으로 링크했으며, AlmaLinux 빌드 호스트가 사용하는 이름으로 요청했습니다. Debian과 Ubuntu는 동일한 라이브러리를 이전 이름인 `libpcap.so.0.8`로 제공하므로, 해당 바이너리는 시작도 전에 멈춥니다 —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

제공된 `packaging/systemd/` 유닛은 두 프로세스를 권한이 없는 `maltrail` 사용자로 실행합니다. Systemd는 `/var/log/maltrail` 및 `/var/lib/maltrail`을 생성하고, 파일시스템 접근을 제한하며, 센서에 `CAP_NET_RAW` 및 `CAP_NET_ADMIN` 권한을 부여합니다.

설치 프로그램은 이러한 유닛을 자동으로 구성합니다. 기존 소스 설치의 경우, [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md)의 수동 서비스 절차를 따르십시오.

다음 명령으로 서비스 상태와 로그를 확인하십시오:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

컨테이너 구성, 스토리지, 권한, 헬스 체크는
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md)에 문서화되어 있습니다.

## 구성

Maltrail은 별도의 `[Sensor]` 및 `[Server]` 설정을 포함하는 `maltrail.conf`를 읽습니다.
설치 프로그램은 관리되는 구성을 `/etc/maltrail.conf`에 배치합니다.

자주 사용되는 센서 옵션은 다음과 같습니다:

| 옵션 | 용도 |
| --- | --- |
| `MONITOR_INTERFACE` | 캡처 인터페이스 또는 인터페이스들; `any`는 지원되는 모든 인터페이스를 선택합니다 |
| `CAPTURE_FILTER` | BPF 캡처 필터 |
| `CAPTURE_FANOUT` | Linux 캡처 소켓 수; 기본값은 1입니다 |
| `CAPTURE_WORKERS` | 캡처 워커, 각각 하나의 소켓을 사용; 기본값은 `CAPTURE_FANOUT`이므로, 둘 중 하나가 설정되지 않으면 1입니다 |
| `LOG_DIR` | 로컬 이벤트 로그 디렉터리 |
| `TRAILS_FILE` | 생성된 트레일 데이터베이스 |
| `LOG_SERVER` | 원격 Maltrail 이벤트 서버 |
| `SYSLOG_SERVER` | CEF syslog 대상 또는 대상들 |
| `LOGSTASH_SERVER` | Logstash JSON 대상 또는 대상들 |
| `STATS_ADDRESS` | Prometheus 메트릭 리스너; 구성되지 않으면 비활성화됩니다 |
| `UPDATE_PERIOD` | 트레일 새로고침 간격 |
| `STATIC_TRAILS_URL` | 조합된 정적 트레일 세트를 가져오는 위치; 새 콘텐츠가 언제 반영될지 제어하려면 날짜가 지정된 릴리스로 고정하세요 |
| `USER_WHITELIST` | 경고를 발생시키지 않아야 하는 운영자 관리 지표 |
| `CUSTOM_TRAILS_DIR` | 운영자 관리 트레일 디렉터리 |
| `STATIC_TRAILS_DIR` | 트레일 저장소의 선택적 체크아웃; UI에서 트레일의 출처 인용을 표시하는 데만 사용됩니다 |

`PROCESS_COUNT`는 폐기된 Python 센서와 레거시 이벤트 로그 스로틀에 적용되며,
Rust 센서의 워커 수를 설정하지 **않습니다**. 캡처 워커는 `CAPTURE_FANOUT` 또는
`CAPTURE_WORKERS`로 구성하세요.

구성을 변경한 후 배포 검사를 실행하세요:```bash
sensor/target/release/maltrail-sensor -T

`content-YYYYMMDD-HHMM` 릴리스를 지정하면 버전을 고정할 수 있으므로, 잘못된 게시가 즉시 전역에 퍼지지 않습니다. 세트는 `TRAILS_FILE` 옆에 캐시되며, 이 덕분에 오프라인 또는 에어갭 재빌드가 가능합니다. 게시된 `sha256`은 다운로드 전에 확인되므로, 콘텐츠 변경보다 더 자주 업데이트되는 배포는 11MB 대신 65바이트만 전송하며, 다이제스트와 일치하지 않는 페이로드는 캐시를 우선하여 거부됩니다.

`update_trails()`는 빌드가 성공한 후에만 새 `TRAILS_FILE`을 원자적으로 게시합니다. 아무것도 반환하지 않는 피드는 이름으로 보고되므로, 배포가 조용히 은퇴한 소스에 조용히 의존하지 않습니다.

`CUSTOM_TRAILS_DIR` 아래에 자체 지표를 추가하고, 이벤트를 발생시키면 안 되는 항목은 `USER_WHITELIST`에 넣으세요. 둘 다 설치 디렉터리 밖에 두어 업그레이드가 덮어쓰지 못하게 하세요.

정적 트레일 기여는 [stamparm/trails](https://github.com/stamparm/trails)로, 새 피드는 여기로 보내세요. 어느 쪽이든 지표에는 분류와 누군가 확인할 수 있는 출처가 필요합니다 — [Contributing](#contributing)을 참조하세요.

## 이벤트 및 API

Maltrail은 감지마다 공백으로 구분된 이벤트 하나를 기록하며, 값에 공백이 포함된 경우 CSV 따옴표를 사용합니다:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

I’m ready to translate the Kitploit tool content from English to Korean. Please provide chunk 35 of 43.```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}

설계된 악성 트래픽의 pcap(트레일 히트는 DNS 쿼리, IP, `IP:port`, URL 경로 및 `Host` 헤더에 대해 발생하며, SQL 인젝션, 경로 탐색, RCE, XSS, 프록시 프로브, 싱크홀, `Host` 누락 및 포트/웹/감염 스캐닝 휴리스틱도 포함)을 재생하여 설치된 센서를 통해 실행하고, 예상된 모든 탐지가 발생하는지 검증합니다. 루트 권한, 인터페이스 또는 자체 트레일 세트가 필요하지 않습니다. 정상적으로 설치된 경우 `20/20 detection(s) fired`가 출력됩니다.

`STATS_ADDRESS`가 구성된 경우, 최소한 다음 Prometheus 메트릭을 모니터링하세요:

| 메트릭 | 운영상 의미 |
| --- | --- |
| `maltrail_up == 0` | 실행 중인 캡처 워커가 없음 |
| 증가하는 `maltrail_capture_dropped_total` | 캡처 링이 패킷을 드롭하고 있음 |
| 증가하는 `maltrail_local_log_errors_total` | 이벤트가 생성되었지만 로컬에 기록하지 못함 |
| 증가하는 `maltrail_remote_log_errors_total` | 이벤트를 원격 싱크로 전달하지 못함; `DISABLE_LOCAL_LOG_STORAGE`가 설정된 경우 이벤트가 유실됨 |
| 진행되지 않는 `maltrail_trail_generation` | 활성 트레일 세트가 갱신되지 않고 있음 |
| `maltrail_log_dir_free_bytes` | 로컬 이벤트 저장을 위한 남은 용량 |
| 증가하는 `maltrail_state_saturations_total` | 휴리스틱 상태 한도에 도달함 |
| 증가하는 `maltrail_throttle_evictions_total` | 이벤트 스로틀 테이블이 한도에 도달하여 이벤트가 구성된 것보다 일찍 집계됨 |

상태 포화는 해당 휴리스틱에 영향을 미치며, 정확한 트레일 매칭은 계속 활성 상태로 유지됩니다.

트레일 재로드를 요청하려면 `SIGHUP`을 보내거나 `systemctl reload maltrail-sensor`를 사용하세요. 다른 프로세스에 의해 업데이트된 트레일 파일은 자동으로 감지되어 센서를 재시작하지 않고 워커에 게시됩니다.

압축 관측 저장소(`USE_CONDENSED_STORAGE`, `meta.sqlite`)는 서버의 신규성 및 레트로 헌트 뷰를 지원합니다. 일일 이벤트 로그 사이드카 인덱스(`USE_EVENT_INDEX`, `LOG_DIR/index/*.sqlite`, 디스크에서 로그 크기의 약 2배)는 `/counts`를 정확하게 만들고 `/hunt`를 빠르게 만드는 요소입니다. 이 인덱스는 로그 자체에서 증분 방식으로 유지 관리되며 `server.py --rebuild-index`로 재구축할 수 있습니다. 폐기된 센서와의 호환성은 [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md)에 문서화되어 있습니다.

### 이벤트 보존

Maltrail은 이벤트 로그를 순환하거나 삭제하지 않습니다. 운영자는 저장 요구 사항과 조직 정책에 따라 보존, 아카이빙 및 삭제를 정의할 책임이 있습니다.

권장 사항:

- `LOG_SERVER`, `SYSLOG_SERVER` 또는 `LOGSTASH_SERVER`를 사용하여 내구성 있는 이벤트 사본을 원격 Maltrail 서버 또는 SIEM으로 전송하세요.
- 예상 이벤트 속도에 충분한 여유 공간을 두고 `maltrail_log_dir_free_bytes`에 대한 알림을 설정하세요.
- 외부 도구를 사용하여 로컬 일일 로그를 순환, 아카이브 또는 제거하세요.
- 보고 인터페이스에 필요한 파일은 `LOG_DIR`에 압축하지 않은 상태로 유지하고, 압축된 파일은 다른 곳에 아카이브하세요.

로그 파일 시스템이 가득 차면 센서가 이벤트를 추가할 수 없습니다. 이벤트 로그에는 일부 관할권에서 개인 데이터로 규제되는 IP 주소와 도메인이 포함될 수 있습니다. 보존 정책은 적용 가능한 요구 사항을 고려해야 합니다.

## 문서

| 문서 | 내용 |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | 설치, 권한, 구성 및 문제 해결 |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | 센서 내부 구조 및 데이터 흐름 |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | 폐기된 Python 센서와의 의도적 차이점 |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | 측정, 프로필 및 테스트 결과 |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | 공개 센서 작업 |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | 엔지니어링 노트, 벤치마크 및 분석 자료 |

## 기여

트레일 추가, 피드 유지 관리, 버그 보고, 문서 및 센서 개선을 환영합니다. 트레일 제출에는 신뢰할 수 있는 출처가 포함되어야 하며 가장 좁은 적절한 분류를 사용해야 합니다.

코드를 제출하기 전에 관련 검사를 실행하세요. 전체 센서 게이트는 다음과 같습니다:```bash
bash sensor/tools/check.sh

## 프로젝트

### 라이선스

Maltrail은 MIT 라이선스로 배포됩니다. [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE)를 참조하세요.

### 관리자

- Miroslav Stampar ([@stamparm](https://github.com/stamparm))
- Mikhail Kasimov ([@MikhailKasimov](https://github.com/MikhailKasimov))

### 후원자

- [Sansec](https://sansec.io/) (2024–2025)
- [Sansec](https://sansec.io/) (2020–2021)

### 발표 및 간행물

- 47th TF-CSIRT Meeting, Prague, 2016
  ([슬라이드](https://web.archive.org/web/20161109135211/https://www.terena.org/activities/tf-csirt/meeting47/M.Stampar-Maltrail.pdf))
- _Detect attacks on your network with Maltrail_, Linux Magazine, 2022
  ([기사](https://www.linux-magazine.com/Issues/2022/258/Maltrail))
- _Best Cyber Threat Intelligence Feeds_, Silent Push, 2022
  ([리뷰](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds))
- _Research on Network Malicious Traffic Detection System Based on Maltrail_, Nanotechnology
  Perceptions, 2024
  ([논문](https://nano-ntp.com/index.php/nano/article/view/1915/1497))

### 파생 블랙리스트

`malware/` 정적 트레일에서 파생된 도메인 전용 목록은
[`maltrail-malware-domains.txt`](https://raw.githubusercontent.com/stamparm/aux/master/maltrail-malware-domains.txt)에 게시되어 있습니다.
DNS 필터링 시스템의 입력으로 사용할 수 있지만, 운영자는 차단을 활성화하기 전에 이를 검토하고 테스트해야 합니다.
위협 인텔리전스 목록에는 오탐(false positive) 또는 모든 환경에 적합하지 않은 지표가 포함될 수 있습니다.

### 타사 통합

- [FreeBSD Port](https://www.freshports.org/security/maltrail)
- [OPNsense Gateway Plugin](https://github.com/opnsense/plugins/pull/1257)
- [D4 Project](https://www.d4-project.org/2019/09/25/maltrail-integration.html)
- [BlackArch Linux](https://github.com/BlackArch/blackarch/blob/master/packages/maltrail/PKGBUILD)
- [Validin](https://x.com/ValidinLLC/status/1719666086390517762)
- [Maltrail Add-on for Splunk](https://splunkbase.splunk.com/app/7211)
- [Maltrail decoder and rules for Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (트레일 전용)
- [MalwareWorld](https://www.malwareworld.com/) (트레일 전용)
- [oisd domain blocklist](https://oisd.nl/?p=inc) (트레일 전용)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (트레일 전용)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (트레일 전용)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (트레일 전용)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (트레일 전용)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (트레일 전용)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (트레일 전용)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (트레일 커넥터)

### 감사의 말

- Thomas Kristner
- Eduardo Arcusa Les
- James Lay
- Ladislav Baco (@laciKE)
- John Kristoff (@jtkdpu)
- Michael Münz (@mimugmail)
- David Brush
- @Godwottery
- Chris Wild (@briskets)
- Keith Irwin (@ki9us)
- Simon Szustkowski (@simonszu)