Tsukuyomi

Лунный Чтец

Фреймворк командного управления, созданный на Rust

Linux x86_64 и Windows x86_64, одиночный оператор, поэтапная доставка в памяти.

Обзор

Tsukuyomi — это фреймворк C2, основанный на Rust и названный в честь ками Луны — братского божества Аматэрасу (солнце) и Сусаноо (шторм). Мотив «наблюдателя за луной» соответствует роли: тихий, постоянный, наблюдающий издалека, координирующий сверху. Сервер размещает маяки; операторы управляют взаимодействием из консоли; шаговик связывается с базой, заменяет себя имплантом в памяти, а имплант берет на себя функцию проверки связи. Названия компонентов следуют фазам луны — шаговик — Микадзуки (полумесяц), имплант — Мангэцу (полнолуние).

v0.2 добавляет реальное выполнение задач в shell к минимальному рабочему каркасу v0.1: оператор ставит shell-команду в очередь из консоли, имплант выполняет её с тайм-аутом и ограниченными буферами вывода, структурированный результат (код выхода, stdout, stderr) передаётся обратно. v0.3 расширяет имплант до Windows: Мангэцу и Микадзуки компилируются как для x86_64-unknown-linux-gnu, так и для x86_64-pc-windows-gnu, сервер кэширует артефакты для каждой платформы и выбирает на основе типизированного поля Platform в HostInfo при проверке связи шаговика, а консоль отображает платформу рядом с именем хоста/пользователем. v0.3.1 предоставляет однофайловый лаунчер, который координирует сервер и консоль без видимой для оператора конфигурации — ./tsukuyomi погружает оператора в рабочую консоль, где токен передаётся между процессами молча. v0.3.2 переносит сборку шаговика и импланта в консоль: build stager, build implant и build all вызывают cargo с нужным TSUKUYOMI_SERVER_URL, запрашивают URL C2 один раз за сессию и автоматически устанавливают имплант в каталог данных сервера. v0.4.0 вводит фиксацию TLS-сертификата: сервер предоставляет SHA-256 своего самоподписанного сертификата на защищённом токеном операторском эндпоинте /cert/pin, команды build в консоли автоматически загружают пин и встраивают его в артефакты шаговика и импланта через TSUKUYOMI_CERT_PIN_SHA256, а кастомный ServerCertVerifier из rustls проверяет пин при каждом соединении — артефакты, собранные без пина, возвращаются к предыдущему поведению с пропуском проверки и предупреждением в stderr, поэтому ручная сборка через cargo build продолжает работать для отладки и проверки. Большинство операционных функций за исключением выполнения shell-команд, кроссплатформенной поддержки, встроенной сборки и фиксации сертификата всё ещё отложены; см. ROADMAP.md.

Архитектура

                          +---------------------+

                          |  tsukuyomi-console  |
                          |   (operator REPL)   |
                          +----------+----------+

                                     | HTTP+JSON
                                     | 127.0.0.1:9443
                                     v
+----------------------+  HTTPS  +---------------------+  HTTPS  +----------------------+

|  tsukuyomi-mikazuki  | <-----> |   tsukuyomi-server  | <-----> |  tsukuyomi-mangetsu  |
|       (stager)       |  8443   |  axum, sqlite, tls  |  8443   |   (implant cdylib)   |
+----------------------+         +---------------------+         +----------------------+

        |                                                                   ^
        | 1. StagerCheckin (HostInfo.platform = Linux | Windows)            |
        | 2. Stage2Payload (mangetsu cdylib bytes + beacon_id)              |
        |    or Stage2Unavailable if no artifact for this platform          |
        | 3. stage payload (Linux: memfd_create; Windows: %TEMP%\dll)       |
        | 4. load via libloading; call mangetsu_main ------------------------+
                                            (Mikazuki's process is now Mangetsu)

                                                                            |
                                                                            v
                                                            BeaconCheckin -> TaskList
                                                            TaskResult <- runs delivered tasks

Транспорт импланта (/c2) — HTTPS + postcard. Postcard — бинарный формат, с ручным управлением версиями через Message::V1(MessageV1), поэтому протокол v0.2 может добавить MessageV2, не ломая V1-импланты. Транспорт оператора (/beacons, /beacons/{id}/tasks) — HTTP + JSON, намеренно другой: удобство инструментов важнее компактности потока.

Компоненты

• tsukuyomi-api — общие типы протокола. Конверт Message::V1(MessageV1), кодированный в postcard, с ручным управлением версиями для совместимости.
• tsukuyomi-server — постоянный сервер. HTTPS-слушатель имплантов на 0.0.0.0:8443, HTTP API оператора на 127.0.0.1:9443, состояние в SQLite на /tmp/tsukuyomi.db, самоподписанный сертификат генерируется при запуске. Кэширует артефакты Мангэцу для каждой платформы при запуске и раздаёт их по HostInfo.platform.
• tsukuyomi-console — REPL оператора на основе rustyline. Команды: beacons, use, back, task noop, tasks, help, exit.
• tsukuyomi-mikazuki — «полумесяц». Шаговик. Linux: memfd_create + dlopen для /proc/self/fd/<n>. Windows: запись в %TEMP%\mangetsu.dll + LoadLibraryW. Оба пути проходят через libloading и общую абстракцию src/platform/.
• tsukuyomi-mangetsu — «полнолуние». Имплант-cdylib. Экспортирует mangetsu_main, запускает цикл проверки связи каждые 30 секунд. Та же структура src/platform/, что и у Микадзуки — запуск и завершение shell-задач различаются для разных ОС, остальное — платформонезависимое.
• tsukuyomi-launcher — однофайловый лаунчер (tsukuyomi). Запускает сервер и консоль как дочерние процессы, передаёт токен оператора между ними молча через наследуемый pipe в дочернем процессе сервера (файловый дескриптор 3), перенаправляет логи сервера в /tmp/tsukuyomi-server.log и завершает всё по сигналу. Только для Linux; автономные бинарные файлы выше продолжают работать без изменений для тестов, отладки и развёртывания на нескольких хостах.

Примечание о размере бинарных файлов

Tsukuyomi приоритизирует архитектурную корректность над оптимизацией размера до версии v0.5. Релизные артефакты включают полные стеки HTTPS на reqwest + rustls, что делает их значительно больше стандартных шаговиков:

• Linux: Микадзуки ~6.2 МБ, Мангэцу ~6.1 МБ
• Windows: Микадзуки ~10.7 МБ, Мангэцу ~9.4 МБ (импорты системных DLL schannel)

Типичные шаговики C2 этой категории варьируются от нескольких сотен байт (только DNS) до нескольких сотен КБ (минимальный HTTPS). Веха v0.6 (см. ROADMAP.md) заменяет HTTP-клиент шаговика на самодельную минимальную реализацию и исследует сборки no_std. Текущие размеры приемлемы для демо-версии, но не выдержат обнаружения в реальном взаимодействии.

Быстрый старт

Требования: Rust 1.80+, Linux x86_64.

git clone https://codeberg.org/lorsupra/Tsukuyomi.git
cd Tsukuyomi
cargo build --release

Рекомендуемый вариант: лаунчер

./target/release/tsukuyomi

Погружает оператора в рабочую консоль с уже запущенным и аутентифицированным сервером. Токен генерируется сервером и передаётся консоли молча через наследуемый pipe, никогда не появляясь на экране. Логи сервера идут в /tmp/tsukuyomi-server.log, а не перемешиваются с приглашением REPL; лаунчер в баннере указывает путь. Ctrl+C завершает всё.

Шаговик (микадзуки) запускается отдельно на целевом хосте; лаунчер только координирует серверную и консольную часть на стороне оператора.

Вручную: сервер, консоль, шаговик по отдельности

Для тестов, отладки, развёртывания на нескольких хостах или в любых случаях, когда вы хотите запустить три процесса в разных терминалах или на разных хостах:

./target/release/tsukuyomi-server               # listeners on 8443 (TLS) and 9443 (operator)
./target/release/tsukuyomi-console              # REPL (set TSUKUYOMI_OPERATOR_TOKEN from the server's stderr banner)
./target/release/tsukuyomi-mikazuki             # one-shot stager run

Сервер выводит токен оператора в stderr при запуске; скопируйте его в окружение консоли как TSUKUYOMI_OPERATOR_TOKEN. Файлы состояния находятся в /tmp/tsukuyomi.db, /tmp/tsukuyomi-server.crt, /tmp/tsukuyomi-server.key. Передайте --data-dir <путь>, чтобы переместить их.

Тесты работоспособности

./smoke-test.sh                  # server + stager + implant end-to-end (Linux)
./smoke-test-launcher.sh         # launcher lifecycle (spawn, signal, teardown)
./smoke-test-pinning.sh          # cert pin enforcement (matching pin connects, mismatched rejected)
./smoke-test-windows.sh          # Windows stager + implant under Wine

Автономный тест (smoke-test.sh) собирает рабочее пространство, запускает сервер, запускает Микадзуки, ждёт полного цикла проверки связи Мангэцу и проверяет, что временная метка last_seen маяка обновляется, а структурированные результаты трёх shell-задач возвращаются. Код выхода 0 при [smoke] PASS.

Кроссплатформенная сборка

Микадзуки и Мангэцу могут быть кросс-компилированы с Linux-хоста на x86_64-pc-windows-gnu.

Одноразовая настройка инструментария:

rustup target add x86_64-pc-windows-gnu

# Debian / Ubuntu:
sudo apt install gcc-mingw-w64-x86-64

# Arch:
sudo pacman -S mingw-w64-gcc

Команда сборки:

cargo build --release --target x86_64-pc-windows-gnu \
  -p tsukuyomi-mikazuki -p tsukuyomi-mangetsu

Сервер и консоль собираются только для платформы хоста.

Развёртывание

Фреймворк собирается под каждую целевую платформу. Сервер считывает сетевую конфигурацию из CLI; шаговик и имплант встраивают свою при сборке через переменные окружения, поскольку они не переносят argv на целевой хост.

# Server and console build normally.
cargo build --release -p tsukuyomi-server
cargo build --release -p tsukuyomi-console

# Stager pointed at a non-localhost coordinator.
TSUKUYOMI_SERVER_URL=https://your-host.example.com:8443 \
  cargo build --release -p tsukuyomi-mikazuki

# Implant with dev-noise stderr suppressed (any non-empty value enables).
TSUKUYOMI_SERVER_URL=https://your-host.example.com:8443 \
  TSUKUYOMI_QUIET=1 \
  cargo build --release -p tsukuyomi-mangetsu

# Server with a custom implant listener port.
./target/release/tsukuyomi-server --agent-port 8443 --data-dir /tmp

По умолчанию: сервер слушает на 0.0.0.0:<agent_port> (по умолчанию 8443) для имплантов и на 127.0.0.1:9443 для API оператора. API оператора намеренно доступен только с localhost — доступ требует shell на хосте сервера. Шаговик/имплант по умолчанию используют https://127.0.0.1:8443, если TSUKUYOMI_SERVER_URL не задан при сборке.

Артефакты Мангэцу

Linux-маяки требуют <data_dir>/mangetsu.so; Windows-маяки требуют <data_dir>/mangetsu.dll. Любой или оба могут отсутствовать при запуске сервера — сервер всё равно запускается и отклоняет маяки для отсутствующих платформ с понятной ошибкой Stage2Unavailable. Для удобства разработки сервер также ищет артефакты рабочего пространства target/release/libtsukuyomi_mangetsu.so (и target/x86_64-pc-windows-gnu/release/tsukuyomi_mangetsu.dll для Windows) относительно рабочего каталога, что и используется в тесте работоспособности.

Статус v0.4

Реализовано от конца до конца:

• Рабочее пространство с шестью крейтами (api, server, console, mikazuki, mangetsu, launcher)
• Версионированный протокол поверх postcard (Message::V1(MessageV1)); вариант Stage2Unavailable отклоняет проверки связи от платформ без загруженного артефакта
• Сервер с самоподписанным TLS, состояние маяков и задач в SQLite, bearer-аутентификация для API оператора (токен выводится один раз при запуске)
• Кэш артефактов Мангэцу для каждой платформы загружается энергично при запуске сервера; проверка связи шаговика считывает HostInfo.platform и отдаёт соответствующий артефакт
• Настраиваемый порт слушателя агента; сборка шаговика и импланта под каждую цель через TSUKUYOMI_SERVER_URL
• API оператора: список маяков (с полем платформы), постановка задач noop / shell, список задач со структурированными результатами
• Консольная REPL с диспетчеризацией команд, цветным выводом списка маяков, включающим столбец ПЛАТФОРМА (синий для Linux, пурпурный для Windows), и командой shell [--timeout N] <cmd>
• Кроссплатформенный имплант: Linux x86_64 (memfd_create + dlopen через /proc/self/fd/<n>, эскалация SIGTERM/SIGKILL при таймауте shell) и Windows x86_64 (запись %TEMP%\mangetsu.dll + LoadLibraryW, одностадийный TerminateProcess при таймауте shell). Платформо-специфичный код находится в src/platform/ как в Mikazuki, так и в Mangetsu.
• Типизированный перечисление Platform, передаваемый от регистрации стейджера через базу данных (столбец platform в таблице beacons) до отрисовки в консоли
• Сквозные проверки дыма для обеих платформ: smoke-test.sh (нативный Linux) и smoke-test-windows.sh (кросс-компилированный стейджер + имплант под Wine), каждая покрывает штатный сценарий shell, ненулевой код выхода и таймаут
• v0.3.1 одно-бинарный лаунчер (tsukuyomi): управляет сервером и консолью без видимой для оператора конфигурации, передаёт токен через унаследованный pipe fd-3, маршрутизирует логи сервера в файл, SIGTERM/SIGKILL с завершением, устойчивым к ESRCH. Жизненный цикл покрыт smoke-test-launcher.sh. Только Linux в v0.3.1; автономные бинарники продолжают работать без изменений для случаев, когда лаунчер не подходит по форме
• v0.4.0 команды сборки в консоли (build stager, build implant, build all): запуск cargo build --release --target ... -p ... с встроенным TSUKUYOMI_SERVER_URL, потоковый вывод, автоматическая установка артефакта импланта в директорию данных сервера. URL C2 запрашивается один раз за сессию и кэшируются. Поддерживаются флаги --target linux|windows, --url, --no-install и --out. Полный рабочий процесс развертывания описан в DEPLOYMENT.md.
• v0.4.1 закрепление сертификатов: сервер предоставляет SHA-256 по GET /cert/pin, кастомный проверяющий rustls в стейджере и импланте обеспечивает встроенную привязку через TSUKUYOMI_CERT_PIN_SHA256 (компиляционный option_env!), команды build консоли получают и вставляют привязку автоматически, откат на невалидный TLS при отсутствии привязки для совместимости с cargo build, флаги --pin и --no-pin для команд сборки, сквозная проверка дыма (smoke-test-pinning.sh) проверяет как штатный сценарий, так и отклонение при несовпадении.
• v0.4.2 исправление инвалидации кэша сборки: build.rs для каждого крейта импланта генерирует cargo:rerun-if-env-changed для каждого источника option_env!, чтобы cargo инвалидировал устаревшие артефакты при изменении переменных окружения времени сборки.
• v0.4.2 джиттерированный повтор: Mikazuki оборачивает запрос/ответ /c2 вграниченный джиттерированный экспоненциальный повтор (до 5 попыток, откат 1с/2с/4с/8с с потолком 30с, равный джиттер); ошибки транспорта и HTTP 5xx являются временными, HTTP 4xx и Stage2Unavailable — фатальны. Зависимости от ПСЧ нет, изменений в сетевом протоколе или консоли нет.

Явно отложено (см. ROADMAP.md):

• Ключи для каждого маяка, маски сна, крейтбилдер — v0.4 (изначально укрепление v0.3; пересмотрено, когда v0.3 стала кроссплатформенной)
• Файловые операции (загрузка / выгрузка, по частям) — v0.4
• Сохранность после перезагрузки, джиттерированный повтор при временных сбоях — v0.4
• Поддержка нескольких операторов и фоновое обновление консоли — всё ещё в рамках v0.2.x
• Загрузка в память Windows, косвенные системные вызовы, патчинг ETW, обход AMSI — v0.5
• Оптимизация размера бинарника (no_std стейджер, ручной минимальный HTTPS) — v0.6
• Пивотинг / боковое перемещение, веб-интерфейс, отчетность — v0.7+
• Импланты для macOS — не на дорожной карте

Портфолио

Tsukuyomi — один из трех инструментов безопасности на Rust наряду с Susanoo (веб-фаззер / разведка) и Amatsumara (фреймворк пентеста / эксплуатация). Вместе они покрывают разведку, эксплуатацию и пост-эксплуатацию.

Лицензия

BSD-3-Clause