कोई नियम भाषा नहीं, कोई ट्यूनिंग रस्म नहीं, कोई ML नहीं। एक **trail** एक डोमेन, URL, IP पता, `IP:port` या User-Agent है जो किसी दुर्भावनापूर्ण चीज़ से संबंधित माना जाता है, और Maltrail आपको बताता है कि उनमें से कोई कब वायर पर दिखाई देता है।

---

## सामग्री

- [Maltrail क्यों?](#why-maltrail)
- [आर्किटेक्चर](#architecture)
- [प्रदर्शन](#performance)
- [त्वरित आरंभ](#quick-start)
  - [सेवा के रूप में](#as-a-service)
  - [Docker](#docker)
- [कॉन्फ़िगरेशन](#configuration)
- [Trails](#trails)
- [ईवेंट](#events)
- [इसे संचालित करना](#operating-it)
  - [ईवेंट धारण](#event-retention)
- [दस्तावेज़ीकरण](#documentation)
- [योगदान](#contributing)
- [लाइसेंस](#licence)
- [प्रायोजक](#sponsors)
- [डेवलपर](#developers)
- [प्रस्तुतियाँ](#presentations)
- [प्रकाशन](#publications)
- [ब्लैकलिस्ट](#blacklist)
- [धन्यवाद](#thank-you)
- [थर्ड-पार्टी एकीकरण](#third-party-integrations)

---

## Maltrail क्यों?

अधिकांश नेटवर्क डिटेक्शन उपकरण आपसे *व्यवहार* का वर्णन करने के लिए कहते हैं। Maltrail एक सरल प्रश्न पूछता है जो
अधिकांश वास्तविक घटनाओं का उत्तर देता है: **क्या यह होस्ट किसी ऐसी चीज़ से बात कर रहा है जिसे हम पहले से बुरा मानते हैं?**

* **1.5 मिलियन से अधिक trails**, 3,000 से अधिक क्यूरेटेड स्टैटिक सूचियों और 46 पब्लिक फीड्स से,
  प्रतिदिन ताज़ा होती हुई और बढ़ती हुई। मुख्य रूप से **मैलवेयर** — C2 डोमेन, ड्रॉपर,
  स्टीलर, APT इंफ्रास्ट्रक्चर — की ओर उन्मुख, क्योंकि वास्तविक सुरक्षा उल्लंघन में यही दिखाई देता है।
* **Trails सादा पाठ हैं।** प्रति पंक्ति एक संकेतक, एक फ़ाइल में जिसे आप पढ़ सकते हैं, 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

**दूसरी तालिका पढ़ें जो यह छापता है, पहली नहीं।** यह दो चीज़ें बताती है, और वे अलग-अलग सवालों के जवाब देती हैं:

* **पूरी प्रक्रिया** — इसमें स्टार्टअप शामिल है, जो छोटे रीप्ले पर *माप* ही है:
  1.5M-पंक्ति वाले ट्रेल सेट को लोड करने में Rust सेंसर को ~1.1-1.5 सेकंड लगते हैं, और 300,000 पैकेट एक सेकंड से कम समय लेते हैं।
  वह अनुपात लगभग **3×** आता है, और यह पैकेट पथ नहीं है।
* **स्थिर अवस्था** — स्टार्टअप को अलग से 1-पैकेट रीप्ले के साथ मापकर घटाया गया। यह
  प्रति-पैकेट लागत है, और यह ऊपर बताया गया **14-37×** है।

ट्रेल लोडिंग एकमात्र जगह है जहाँ पुराना सेंसर अब भी जीतता है: यह पहले से निर्मित `trails.csv.bin`
साइडकार को mmap करता है, इसलिए इसका *वार्म* स्टार्ट CSV से स्टोर बनाने की तुलना में तेज़ है — RPi 5 पर 1.25 सेकंड बनाम 2.24 सेकंड।
वह लागत प्रति प्रक्रिया एक बार चुकाई जाती है; पैकेट पथ 300,000 बार चुकाया जाता है।

दोनों संख्याएँ हार्डवेयर के साथ बदलती हैं, इसलिए अपना खुद का मापें — और ध्यान दें कि हार्नेस इस मिश्रण पर दोनों सेंसर के लिए
`events=0` रिपोर्ट करता है, क्योंकि यह जानबूझकर हानिरहित ट्रैफ़िक है। डिटेक्शन इसके ऊपर इवेंट-लॉगिंग
लागत जोड़ते हैं।

मेमोरी कोर के साथ नहीं बढ़ती: 1.5M-ट्रेल स्टोर **68.5 MB** है, जो हर वर्कर द्वारा अपरिवर्तनीय रूप से साझा किया जाता है।
इसे बनाना ऊपर बताई गई स्टार्टअप लागत है — Ryzen 7 PRO 4750U पर 1.2 सेकंड,
RPi 5 पर 2.2 सेकंड — और यह प्रति प्रक्रिया एक बार चुकाई जाती है, प्रति वर्कर नहीं।

**डिफ़ॉल्ट रूप से एक कैप्चर वर्कर।** इसका पैकेट पथ 2-vCPU VM पर इस मिश्रण का 4.2 Gbit/s,
8.7 Gbit/s RPi 5 पर और 25.5 Gbit/s Ryzen 9 5900X पर संभालता है — हर मामले में होस्ट के
नेटवर्क इंटरफ़ेस की क्षमता से अधिक, यही कारण है कि एक वर्कर डिफ़ॉल्ट है, समझौता नहीं।
अतिरिक्त वर्कर एक स्पष्ट ऑप्ट-इन हैं (`CAPTURE_FANOUT`), क्योंकि कर्नेल कैप्चर को फ्लो-हैश करता है
जबकि स्कैन ह्यूरिस्टिक्स प्रति स्रोत गिनते हैं: एक वर्कर जितने ह्यूरिस्टिक अलर्ट उठाता है, उनमें से 91%
2 सॉकेट पर, 86% 4 पर, 65% 8 पर बचते हैं। हर वर्कर गिनती पर सटीक ट्रेल डिटेक्शन समान होता है।
जब `maltrail_capture_dropped_total` कहे तब स्केल आउट करें, पहले नहीं।

<sub>सभी आंकड़े: ह्यूरिस्टिक्स सक्षम, वास्तविक 1.5M-पंक्ति ट्रेल सेट, एक कैप्चर वर्कर, तीन रनों में
सबसे तेज़। स्थिर-अवस्था अनुपात ऊपर दिए गए प्रोसेसरों में 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` के लिए पूर्व-निर्मित सेंसर बाइनरी हर
[रिलीज़](https://github.com/stamparm/maltrail/releases) के साथ SHA-256 चेकसम सहित संलग्न हैं — उन्हें केवल
रनटाइम पर 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` नहीं। ये यूनिट्स
`/var/log/maltrail` (इवेंट्स) और `/var/lib/maltrail` (ट्रेल सेट) को systemd के
`LogsDirectory=`/`StateDirectory=` के माध्यम से बनाती हैं और स्वामित्व रखती हैं, दोनों प्रोसेस को अन-प्रिविलेज्ड `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 मॉड्यूल है। दोनों
साधारण पुल रिक्वेस्ट हैं, और यही कम बाधा इस सेट को उपयोगी बनाए रखती है।

आपके अपने इंडिकेटर `CUSTOM_TRAILS_DIR` में जाते हैं; जिनके बारे में आप कभी सुनना नहीं चाहते वे
`USER_WHITELIST` में जाते हैं।

---

## घटनाएँ

प्रत्येक डिटेक्शन के लिए एक लाइन, व्हाइटस्पेस से अलग की गई, जहाँ आवश्यक हो CSV-कोटेड:```
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

यह उत्तर देता है कि कोई एक डोमेन, आईपी या URL ट्रेल सेट में है या नहीं, और कौन-सी कुंजी मेल खाई — सूचीबद्ध डोमेन का एक सबडोमेन पैरेंट को रिपोर्ट करता है, और एक URL को `host/path` के रूप में आज़माया जाता है, फिर केवल होस्ट के रूप में। यह मेमोरी-मैप्ड ट्रेल स्टोर के माध्यम से पढ़ता है, इसलिए इससे सर्वर की मेमोरी पर कोई लागत नहीं पड़ती, और बिना रीस्टार्ट के ट्रेल अपडेट उठा लेता है।

यह **सार्वजनिक** ट्रेल सेट के लिए बिना प्रमाणीकरण के है, जैसे इसके बगल में `/trails` है: वह एंडपॉइंट पहले से ही किसी को भी स्टैटिक और फ़ीड ट्रेल्स परोसता है (इसी तरह एक सेंसर `UPDATE_SERVER` से खींचता है), इसलिए उन पर एकल-कुंजी लुकअप उससे सख्ती से कम खोलता है जो उसी पोर्ट पर पहले से उपलब्ध है।

**कस्टम ट्रेल्स को एक सत्र की आवश्यकता होती है।** वे सार्वजनिक डेटा के बजाय आपके अपने संकेतक हैं, और `ENABLE_MASK_CUSTOM` पहले से ही गैर-व्यवस्थापक उपयोगकर्ताओं से उनके नाम छिपाता है — इसलिए `/check` किसी ऐसे व्यक्ति को भी जो इसे देखने की अनुमति नहीं रखता, कस्टम-मात्र मेल को मिस के रूप में रिपोर्ट करता है। घटना डेटा पूरी तरह से सीमित रहता है।

---

## इसे संचालित करना

* **`-T`** एक कॉन्फ़िगरेशन को मान्य करता है और समाप्त हो जाता है। डिप्लॉयमेंट गेट के रूप में उपयोगी; systemd यूनिट इसे `ExecStartPre` के रूप में चलाती है।
* **`STATS_ADDRESS`** Prometheus मेट्रिक्स उजागर करता है। अलर्ट करने लायक चार मेट्रिक्स, जिन सभी का अर्थ है *यह सेंसर वह नहीं पहचान रहा जो आप सोचते हैं*:

  | मेट्रिक | इसका अर्थ |
  | --- | --- |
  | `maltrail_up == 0` | कोई कैप्चर वर्कर जीवित नहीं है — यह होस्ट **निगरानी में नहीं है** |
  | `rate(maltrail_capture_dropped_total)` | रिंग पैकेट गिरा रही है — **छूटी हुई पहचानें** |
  | `rate(maltrail_local_log_errors_total)` | पहचानें उत्पन्न हुईं और फिर **खो गईं** |
  | `maltrail_trail_generation` आगे नहीं बढ़ रहा | ट्रेल्स ने रीफ़्रेश होना बंद कर दिया है |

  इसके अलावा उपयोगी: `maltrail_log_dir_free_bytes` (नीचे देखें) और
  `maltrail_state_saturations_total`, जो गैर-शून्य होता है जब स्टेट-समाप्ति बाढ़ ने
  ह्यूरिस्टिक्स को संकुचित कर दिया हो। सटीक ट्रेल मिलान उससे, डिज़ाइन के अनुसार, अप्रभावित रहता है।
* **`systemctl reload`** (`SIGHUP`) बिना रीस्टार्ट के ट्रेल्स को पुनः लोड करता है। किसी और चीज़ द्वारा रीफ़्रेश किए गए ट्रेल्स एक सेकंड के भीतर उठा लिए जाते हैं, एटॉमिक स्वैप के साथ — न रीस्टार्ट, न गिराए गए पैकेट।
* **संघनित अवलोकन स्टोर** (`USE_CONDENSED_STORAGE`, `meta.sqlite`) जो सर्वर के `/meta` नवीनता और रेट्रो-हंट दृश्यों को फ़ीड करता है, उसी प्रारूप में लिखा जाता है जो पुराना सेंसर उत्पन्न करता है, और दोनों की तुलना पैरिटी हार्नेस द्वारा पंक्ति-दर-पंक्ति की जाती है। सेंसरों के बीच हर जानबूझकर अंतर
  [`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 से नीचे चेतावनी देता है। जब यह शून्य तक पहुँचता है तो सेंसर जोड़ नहीं सकता और पहचानें खो जाती हैं।
* **संग्रहण (आर्काइविंग) आपका निर्णय है।** यदि आपको स्थान चाहिए तो अपने समय-सारणी के अनुसार पुराने दैनिक लॉग को संपीड़ित करें या स्थानांतरित करें। ध्यान दें कि रिपोर्टिंग UI ऐतिहासिक लॉग को सादे, सीक-योग्य फ़ाइलों के रूप में परोसता है, इसलिए उन्हें जगह में संपीड़ित करने से उन दिनों को इंटरफ़ेस से हटा देता है — उन्हें कहीं और संग्रहीत करें।

यदि आपकी नीति *विलोपन की आवश्यकता रखती है* (घटना लॉग में 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