0xv1n/macnoiseРасширяемый генератор системной телеметрии MacOS.
<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>
---
[](https://github.com/0xv1n/macnoise/actions/workflows/ci.yaml)
[](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, слушатели, reverse shell, DNS и TLS |
| `process` | Точное выполнение, доставка сигналов, инъекция dylib, обход Gatekeeper и osascript |
| `file` | Ограниченное обнаружение, буквальное чтение/копирование, создание, изменение, архивирование, сокрытие и шифрование приманок |
| `tcc` | Проверки разрешений TCC с точными требованиями Full Disk Access, Contacts, Accessibility или Screen Recording |
| `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). Outcome говорит, что произошло с действием, которое попытался выполнить 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, слушателя, DNS, HTTP-маяка и HTTP-эксфильтрации |
| `edr_validation.yaml` | Комплексное покрытие обнаружения EDR |
| `full_sweep.yaml` | Все категории |
| `lazarus_group.yaml` | Lazarus Group: инъекция dylib, обнаружение служб, reverse shell, персистентность 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-файл цитирует фактическую threat intel, на которой он построен, и аннотирует каждый шаг техникой MITRE, которую он отрабатывает, так что начинайте оттуда для полной разбивки, а не с пересказа здесь.
**Сначала dry-run:**
```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, и запись в changelog.
## Отказ от ответственности
MacNoise предназначен для **авторизованного** тестирования безопасности, валидации EDR и инженерии обнаружения на системах, которыми вы владеете или на которые у вас есть явное письменное разрешение на тестирование. Авторы не несут ответственности за неправомерное использование.
## Политика в отношении ИИ-кода
Вклад в виде ИИ-кода допустим, но имейте в виду, что ревью кода в настоящее время будет процессом, ведомым человеком, а значит, объём кода, который мы можем проверить, ограничен. Пожалуйста, ограничивайте PR конкретным исправлением или новым модулем телеметрии. PR с обширными изменениями, скорее всего, будут закрыты.