macnoise

<div style="text-align: center;">
  <img src="https://assets.kitploit.com/production/public/readmes/12216/015e563e6db740a8025fff16e60052d282eafc29855ed07fd23f58cd1a3fc0e5.png" alt="Description of image" style="max-width: 100%; height: auto; display: block; margin: 0 auto;">
</div>

---

[![CI](https://github.com/0xv1n/macnoise/actions/workflows/ci.yaml/badge.svg)](https://github.com/0xv1n/macnoise/actions/workflows/ci.yaml)
[![Release](https://img.shields.io/github/v/release/0xv1n/macnoise)](https://github.com/0xv1n/macnoise/releases/latest)

# MacNoise

يولّد MacNoise بيانات قياس عن بُعد حقيقية لنظام macOS: اتصالات الشبكة، وكتابات الملفات، وعمليات إنشاء العمليات، وتعديلات plist، وفحوصات TCC، والمزيد. وجّهه نحو جهاز يشغّل حزمة EDR أو SIEM أو جدار الحماية لديك وشاهد ما يُفعَّل فعليًا - وليس ما تدّعي ورقة بيانات المورّد أنه سيُفعَّل.

للحصول على خلفية عن الدافع والتصميم، راجع [منشور المدونة الخاص بالإصدار](https://0xv1n.github.io/posts/macnoise/).

## البدء السريع

```bash
# Build (add build-amd64 / build-arm64 to cross-compile for Darwin, or release for both)
make build

# List available modules
./macnoise list

# Run a single module
./macnoise run net_connect --param target=127.0.0.1 --param port=8080

# Preview without executing
./macnoise run svc_launch_agent --dry-run

# Run all network modules
./macnoise run --category network

# Run a scenario
./macnoise scenario configs/scenarios/edr_validation.yaml

# Emit structured JSONL output
./macnoise scenario configs/scenarios/file_flow.yaml --format jsonl --output /tmp/events.jsonl
```

## فئات القياس عن بُعد

| الفئة | الوصف |
|----------|-------------|
| `network` | اتصالات TCP، وHTTP، والمستمعون، والأصداف العكسية، وDNS، وTLS |
| `process` | التنفيذ الدقيق، وإرسال الإشارات، وحقن dylib، وتجاوز Gatekeeper، وosascript |
| `file` | الاكتشاف المحدود، والقراءات/النسخ الحرفية، والإنشاء، والتعديل، والأرشفة، والإخفاء، وتشفير الطُعم |
| `tcc` | فحوصات أذونات TCC بمتطلبات دقيقة للوصول الكامل إلى القرص، أو جهات الاتصال، أو إمكانية الوصول، أو تسجيل الشاشة |
| `credential` | الوصول الأصلي إلى مخزن بيانات الاعتماد |
| `volume` | إنشاء صور القرص ودورة حياة وحدات التخزين المُثبَّتة |
| `service` | تعداد Launchd، واستمرارية LaunchAgent/Daemon، وcron، وملف تعريف الصدفة، وعناصر تسجيل الدخول |
| `plist` | إنشاء وتعديل Plist |
| `evasion` | مسح السجلات، والتلاعب بالطوابع الزمنية، وإزالة السجل، والتنكّر |

راجع [فهرس الوحدات](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) المُولَّد للاطلاع على كل وحدة، ومعامل، ومخرج، ونوع حدث، وامتياز، وتعيين ATT&CK.

## الأوامر

```
macnoise run <module> [--param key=val ...]   Run a specific module
macnoise run --category <cat>                 Run all modules in a category
macnoise run --all                            Run all modules
macnoise list [--category <cat>]              List modules
macnoise info <module>                        Show module details, params, MITRE
macnoise scenario <file.yaml> [--input key=val] [--report report.json]
                                                Run a YAML scenario
macnoise categories                           List categories with counts
macnoise version                              Print version
```

### الأعلام العامة

| العلم | الافتراضي | الوصف |
|------|---------|-------------|
| `--format` | `human` | تنسيق الإخراج: `human` أو `jsonl` |
| `--output` | (لا شيء) | كتابة الإخراج إلى ملف (بالإضافة إلى stdout) |
| `--verbose` | false | إخراج مطوّل يتضمن أخطاء التنظيف |
| `--dry-run` | false | معاينة الإجراءات دون تنفيذ |
| `--no-cleanup` | false | ترك آثار الوحدة في مكانها (انظر أدناه) |
| `--timeout` | `30` | المهلة الزمنية لكل وحدة بالثواني |
| `--audit-log` | (لا شيء) | كتابة سجلات تدقيق OCSF 1.7.0 إلى ملف JSONL |
| `--config` | (لا شيء) | تحميل الإعدادات الافتراضية من ملف تكوين YAML |
| `--run-id` | مُولَّد | تعيين معرّف الارتباط لهذه التشغيلة |

### تدفق بيانات السيناريو

تستخدم ملفات السيناريو `version: 1`. المدخلات ومخرجات الوحدات مُصنَّفة، وتشير
خطوة لاحقة إليها بتعيينات صريحة بدلًا من الاستيفاء النصي:

```yaml
version: 1
name: Archive one generated artifact
on_error: stop
inputs:
  content:
    type: string
    required: true
steps:
  # Custom modules declare these outputs through OutputSpecs.
  - id: create
    module: custom_create
    params:
      content:
        input: content
  - id: archive
    module: custom_archive
    params:
      source:
        output: create.path
outputs:
  archive:
    output: archive.path
```

يمكن فقط الإشارة إلى المخرجات التي تُصرّح بها الوحدة. يمكن إعادة استخدام
السيناريوهات المحلية عبر خطوة `include`؛ فالإدراجات نسبية، ولا يمكنها تجاوز
دليل السيناريو الجذر، ويتم فحصها بحثًا عن الدورات، وتقتصر على ثمانية مستويات.
يتحقق MacNoise من الرسم البياني الكامل قبل التنفيذ، ويمنح التشغيلة مساحة عمل
خاصة واحدة، وينظّف الوحدات المُستدعاة بترتيب عكسي. استخدم
`--input content=value` لتوفير المدخلات و`--report report.json` للحصول على
تقرير التنفيذ المُصدَّر.

## ترك الآثار في مكانها

بشكل افتراضي، تعكس كل وحدة نفسها عند الانتهاء. هذا عادةً ما تريده، لكنه يعني أن
الاكتشاف لا يرى سوى حدث *التثبيت*. للتحقق من أن حزمتك تكتشف الاستمرارية نفسها -
LaunchAgent موجود في `~/Library/LaunchAgents`، أو إدخال cron، أو ملف تعريف صدفة
معدَّل - يجب أن يكون الأثر لا يزال موجودًا عند تشغيل الفحص:

```bash
./macnoise run svc_launch_agent --no-cleanup
```

كل وحدة تتخطى التنظيف تطبع سطرًا يسمّي نفسها، ويسجّل سجل التدقيق
`cleanup_result: skipped` بدلًا من `ok`، بحيث لا يُخطئ أبدًا في اعتبار تشغيلة
تركت الاستمرارية خلفها كتشغيلة نظّفت. استخدم `macnoise info <module>` لمعرفة ما
تنشئه وحدة معينة.

**أنت مسؤول عن إزالة هذه بنفسك.** إعادة تشغيل الوحدة نفسها دون العلم ستُنظّف فقط
ما أنشأته تلك التشغيلة، وليس ما تركته تشغيلة سابقة بـ `--no-cleanup`.

## تسجيل التدقيق

يكتب MacNoise تدفقين منفصلين. أحداث القياس عن بُعد - ما يراه EDR/SIEM لديك
فعليًا - تذهب إلى stdout أو `--output`. ويسجّل تدفق ثانٍ اختياري ما فعله
MacNoise نفسه: أي الوحدات عملت، ونتائج المتطلبات المسبقة/التنظيف، وتعيينات
MITRE، بصيغة [OCSF 1.7.0](https://schema.ocsf.io/) JSONL.

```bash
./macnoise scenario configs/scenarios/amos_atomic_stealer.yaml --audit-log /tmp/audit.jsonl
```

يحمل كل حدث قياس عن بُعد قيمة `outcome` موثوقة واحدة و`subject` مُصنَّفًا واحدًا
(المخطط 2.0). تحدّد النتيجة ما حدث للإجراء الذي حاول MacNoise تنفيذه، بينما
يحدّد subject الملف أو العملية أو نقطة نهاية الشبكة أو الخدمة أو المورد المعني:

| `outcome` | المعنى | العلامة البشرية |
|---|---|---|
| `executed` | نُفّذ الإجراء وفعل ما تدّعيه الوحدة | `[+]` |
| `denied` | نُفّذ الإجراء ورفضته البيئة | `[-]` |
| `indeterminate` | نُفّذ الإجراء، لكن لا يمكن استنتاج أي شيء | `[?]` |
| `error` | فشل MacNoise نفسه في تنفيذ الإجراء | `[!]` |

فحص TCC مرفوض أو إشارة إلى C2 ميت هو القياس عن بُعد الذي وُجدت هذه الأداة
لتوليده، لذا فهو متميز عن `error`، الذي يعني أن MacNoise نفسه فشل. يسجّل سجل
التدقيق القيمة نفسها عند `unmapped.outcome`. تُستبدل المعاملات المُصرَّح بأنها
حساسة بـ `[REDACTED]` في سجلات التدقيق المُدارة وهوية سطر الأوامر.

يفتح سجل التدقيق في وضع الإلحاق، لذا تتراكم السجلات من تشغيلات متعددة في ملف
واحد للتحليل الدفعي. إذا كنت تضيف وحدة وتريد معرفة كيف يُصنَّف نوع حدث جديد في
OCSF، راجع [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md#primitive-modules).

## مرجع الوحدات

[فهرس الوحدات](https://github.com/0xv1n/macnoise/blob/main/docs/module-catalog.md) المُولَّد هو المرجع الموثوق للأسماء
والمعاملات والمخرجات وأنواع الأحداث والامتيازات وتعيينات ATT&CK. تشرح ملاحظات
الفئات سلوك المنصة والحدود التشغيلية:

| الفئة | README |
|----------|--------|
| `network` | [modules/network/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/network/README.md) |
| `process` | [modules/process/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/process/README.md) |
| `file` | [modules/file/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/file/README.md) |
| `tcc` | [modules/tcc/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/tcc/README.md) |
| `credential` | [modules/credential/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/credential/README.md) |
| `volume` | [modules/volume/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/volume/README.md) |
| `service` | [modules/service/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/service/README.md) |
| `plist` | [modules/plist/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/plist/README.md) |
| `evasion` | [modules/evasion/README.md](https://github.com/0xv1n/macnoise/blob/main/modules/evasion/README.md) |

## السيناريوهات

تُسلسل السيناريوهات الوحدات في تسلسلات مرتّبة - ملف YAML واحد يعيد تشغيل نمط
اختراق متعدد المراحل مقابل أنظمة الكشف لديك.

| الملف | الوصف |
|------|-------------|
| `network_only.yaml` | عمليات TCP وlistener وDNS وHTTP beacon وتسريب HTTP مُركّبة |
| `edr_validation.yaml` | تغطية شاملة لاكتشاف EDR |
| `full_sweep.yaml` | جميع الفئات |
| `lazarus_group.yaml` | Lazarus Group: حقن dylib، واكتشاف الخدمات، والصدفة العكسية، واستمرارية LaunchAgent |
| `amos_atomic_stealer.yaml` | AMOS / Atomic Stealer: برمجية سرقة معلومات MaaS، وتجاوز Gatekeeper، واستخراج keychain، وتسريب ZIP، واستمرارية الباب الخلفي |
| `clickfix.yaml` | ClickFix: سطر أوامر واحد مُموَّه يُلصق في Terminal، وفك ترميز base64، وجلب المرحلة الثانية، واستمرارية LaunchAgent |
| `ransomware.yaml` | تأثير برامج الفدية: تجهيز طُعم نصي، وتشفيره، ثم إسقاط ملاحظة فدية |
| `discovery.yaml` | وصفات مُركّبة لاكتشاف النظام والحسابات والشبكة وبرامج الأمان المبنية على argv |
| `process_chain.yaml` | سلسلة صدفة من ثلاث عمليات مبنية من متجه وسائط صريح |
| `file_flow.yaml` | تدفق متصل للإنشاء والتعديل والاكتشاف المحدود والقراءة والنسخ والأرشفة |
| `mounted_execution.yaml` | إنشاء وتنفيذ حمولة من نقطة تثبيت صورة قرص مرصودة |

يتبع سيناريو APT المذكوران تسلسلات اختراق موثّقة حقيقية، تقنية تلو الأخرى -
كل ملف YAML يستشهد ببيانات استخبارات التهديد الفعلية التي بُني منها ويعلّق على
كل خطوة بتقنية MITRE التي يمارسها، لذا ابدأ من هناك للحصول على التفصيل الكامل
بدلًا من إعادة سرده هنا.

**التشغيل التجريبي أولًا:**
```bash
./macnoise scenario configs/scenarios/<scenario>.yaml --dry-run
```

**المرجع المتقاطع مع SIEM/EDR لديك:** يسمّي تعليق كل خطوة التقنية التي يجب أن
يُفعّلها. عدم وجود تنبيه مطابق بعد تشغيل حقيقي هو ثغرة في تغطيتك.

**كتابة سيناريو خاص بك:**
```yaml
version: 1
name: My Custom Scenario
on_error: stop
steps:
  - module: net_connect
    params:
      target: "192.168.1.1"
      port: 443
  - module: file_create
    params:
      base_dir: "/tmp/test"
```

يتم فحص المعاملات مقابل النوع المُصرَّح به لكل وحدة: string أو integer أو boolean
أو path أو list، قبل المعاينة أو التنفيذ. تُرفض الأسماء غير المعروفة والقيم غير
الصالحة. القيمة الافتراضية لـ `on_error` هي `stop`. اضبطها على `continue` فقط
عندما ينبغي لمسح تغطية أن يحاول استدعاءات وحدات لاحقة بعد فشل.

ابدأ من [قالب السيناريو](https://github.com/0xv1n/macnoise/blob/main/docs/templates/scenario.yaml) للمدخلات والمخرجات
وتدفق البيانات المتصل المُصنَّفة.

## توافق الإصدار 1

يحدّد الإصدار 1.0 أوامر وأعلام CLI المدعومة، وأسماء الوحدات وعقودها، ومخطط
السيناريو 1، ومخطط القياس عن بُعد 2.0، ومخطط تقرير السيناريو 1.0. تتطلب أي
تغييرات مستقبلية غير متوافقة على تلك الواجهات إصدارًا رئيسيًا جديدًا.

ينبغي للمستخدمين الحاليين قراءة [الترحيل من v0.6.0 إلى v1.0.0](https://github.com/0xv1n/macnoise/blob/main/docs/migration-v1.md).
فهو يربط كل وحدة مُزالة ويصف تغييرات السيناريو وJSONL وواجهة Go API.

## المساهمة

راجع [CONTRIBUTING.md](https://github.com/0xv1n/macnoise/blob/main/CONTRIBUTING.md) لمسارات الوحدات الأولية والسيناريوهات
والتغييرات الأساسية.

الإصدارات آلية - [release-please](https://github.com/googleapis/release-please)
يُصدر إصدارًا جديدًا مباشرة من عنوان PR الخاص بك بصيغة
[Conventional Commit](https://www.conventionalcommits.org/)، لذا فإن
`feat: add net_tls module` أو `fix: correct beacon jitter` هو عنوان PR الخاص بك
ومدخل سجل التغييرات في آنٍ واحد.

## إخلاء المسؤولية

MacNoise مخصص لاختبارات الأمان **المصرَّح بها**، والتحقق من EDR، وهندسة الكشف
على الأنظمة التي تملكها أو لديك إذن كتابي صريح باختبارها. لا يتحمل المؤلفون أي
مسؤولية عن سوء الاستخدام.

## سياسة كود الذكاء الاصطناعي

مساهمات كود الذكاء الاصطناعي مقبولة، لكن يرجى الأخذ في الاعتبار أن مراجعة
الكود ستكون حاليًا عملية يقودها البشر، مما يعني أن هناك حدًا لما يمكننا مراجعته
من الكود. يرجى قصر طلبات السحب على إصلاح محدد، أو وحدة قياس عن بُعد جديدة.
طلبات السحب ذات التغييرات الواسعة من المرجح أن تُغلق.