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)에 문서화되어 있습니다.

## 설치

### 설치 프로그램

설치 프로그램은 열두 개의 Linux 배포판 — Debian, Ubuntu, Fedora, Rocky, AlmaLinux,
Arch, openSUSE Leap 및 Tumbleweed, 그리고 Alpine — 과 FreeBSD 및 macOS에서 모든 릴리스마다
검증되며, 전체 결과는 [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat)에 기록됩니다. Raspberry Pi OS 및 기타 64비트 ARM 시스템은
`aarch64` 빌드를 사용합니다. 32비트 ARM은 사전 빌드된 센서가 없으며 소스에서 빌드해야 합니다.```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

일반적인 설치 프로그램 옵션:```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

미리 빌드된 센서 바이너리는 SHA-256 체크섬과 함께 최신 릴리스에 첨부되어 있습니다: Linux `x86_64`
및 `aarch64`는 glibc와 musl 모두 대상으로, macOS는 Apple silicon과 Intel, FreeBSD `amd64`, 그리고
Windows `x86_64`입니다.

glibc 빌드는 libpcap을 정적으로 링크하고 glibc 2.28을 대상으로 하므로, C 라이브러리만 있으면 됩니다 — RHEL 8+, Debian 10+, Ubuntu 18.04+ 및 Leap 15.x 모두에서 설치할 것이 없습니다. musl
빌드는 완전히 정적이므로 Alpine은 아무것도 필요로 하지 않습니다. Windows 빌드는 64비트이며 Windows 10 이상과
시작하기 전에 설치된 [Npcap](https://npcap.com)이 필요합니다 — `wpcap.dll`은 로드 시점 의존성이므로,
이것이 없으면 로더가 캡처 시점에 실패하는 대신 실행 파일을 거부합니다. 아카이브에도 그렇게 나와 있습니다.

**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은 `maltrail.conf`를 읽으며, 이 파일에는 별도의 `[Sensor]` 및 `[Server]` 설정이 포함되어 있습니다. 설치 프로그램은 관리되는 구성을 `/etc/maltrail.conf`에 배치합니다.

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

| 옵션 | 용도 |
| --- | --- |
| `MONITOR_INTERFACE` | 캡처 인터페이스 또는 인터페이스들; `any`는 지원되는 모든 인터페이스를 선택합니다 |
| `CAPTURE_FILTER` | BPF 캡처 필터 |
| `CAPTURE_FANOUT` | Linux 캡처 소켓 수; 기본값은 하나입니다 |
| `CAPTURE_WORKERS` | 캡처 워커, 각각 하나의 소켓; 기본값은 `CAPTURE_FANOUT`이므로 둘 중 하나가 설정되지 않는 한 하나입니다 |
| `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` | 선택적 trails 저장소 체크아웃; UI에서 트레일의 출처 인용을 표시하는 데만 사용됩니다 |

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

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

특정 `content-YYYYMMDD-HHMM` 릴리스를 지정하여 버전을 고정하면 잘못된 게시가 즉시 전역으로 퍼지지 않습니다. 이 세트는 `TRAILS_FILE` 옆에 캐시되며, 이것이 오프라인 또는 에어갭 재빌드를 가능하게 합니다. 게시된 `sha256`은 다운로드 전에 확인되므로, 콘텐츠 변경보다 더 자주 업데이트하는 배포는 11 MB가 아닌 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>

## 감사의 말

이 프로젝트에 영감을 주고 기여해 주신 모든 분들께 감사드립니다.```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}

DNS 쿼리, IP, `IP:port`, URL 경로, `Host` 헤더에 대한 트레일 적중과 SQL 인젝션, 트래버설, RCE, XSS, 프록시 프로브, 싱크홀, `Host` 누락, 포트/웹/감염 스캐닝 휴리스틱을 포함한 에뮬레이션된 악성 트래픽의 조작된 pcap을 설치된 센서를 통해 재생하고, 예상되는 모든 탐지가 발동하는지 검증합니다. 루트 권한도, 인터페이스도, 자체 트레일 세트도 필요하지 않습니다. 정상 설치에서는 `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`, 디스크에서 대략 로그 크기의 두 배)는 `/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 주소와 도메인이 포함될 수 있으므로, 보존 정책은 해당 요구 사항을 고려해야 합니다.

### 합성 트래픽

실제 트래픽을 기다리지 않고 탐지와 대시보드가 모두 여전히 작동하는지 확인하려면:```bash
python3 server.py --detect-test                      # assert every detection fires, then exit
python3 server.py --detect-test --keep DIR --serve   # ...and keep the events, serving them on :8338

## 문서

| 문서 | 내용 |
| --- | --- |
| [`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

Linux에서 Windows 빌드를 실행할 수 있으며, 바로 이 과정에서 버그들이 발견되었습니다:```bash
sh sensor/tools/check_windows.sh