Инструменты

Бинарь объявляет 43 инструмента плюс write_file, run_command, run_script, файловые операции copy_file, move_file, rename_file и create_directory, download_file и upload_file, когда оператор их включит. Инструменты только для чтения не требуют подтверждения. Модифицирующие инструменты требуют явного подтверждения оператора (DR-5).

Сессия

Инструмент	Описание
`connect`	Открыть WinRM-сессию к Windows-хосту и вернуть `session_id` (HTTP 5985 или HTTPS 5986 через `use_ssl`)
`disconnect`	Закрыть активную WinRM-сессию
`list_sessions`	Список активных WinRM-сессий с деталями использования

Инструменты только для чтения

Файловая система

Инструмент	Описание
`list_directory`	Список файлов и каталогов по пути
`find_files`	Рекурсивный поиск файлов по шаблону
`read_file`	Чтение содержимого файла с нумерацией строк. В режиме хвоста можно отбросить строки, которые содержат заданный текст
`search_file_content`	Текстовый поиск в файле или по каталогу, аналог grep. Инструмент может вернуть последние совпадения, посчитать совпадения и отфильтровать строки по отметке времени в начале строки
`file_info`	Метаданные файла или каталога в JSON
`compare_files`	Построчный diff двух файлов

Диагностика системы

Инструмент	Описание
`get_event_log`	Журнал событий Windows: падения, отказы служб, ошибки аутентификации
`list_event_logs`	Каналы журнала событий с числом записей и признаком включения
`get_services`	Сводка служб или полные детали по каждой службе в JSON
`get_service_config`	Одна служба: тип запуска (Automatic, AutomaticDelayed, Manual или Disabled), учётная запись, путь к бинарю и действия восстановления с действием, задержкой и периодом сброса
`list_processes`	Процессы с сортировкой по CPU, памяти или дескрипторам
`get_open_handles`	Процессы, которые держат файл открытым: PID, имя и время запуска. Инструмент использует Restart Manager, поэтому Sysinternals `handle.exe` на хосте не нужен
`get_printers`	Принтеры: имя общего ресурса, драйвер, порт, хост и номер порта, состояние в виде имени PrinterStatus и число заданий
`get_print_jobs`	Задания печати одного принтера. Имя документа и владелец скрыты, пока не задан `include_personal_data`
`get_system_info`	Версия ОС, uptime, RAM, число CPU, домен, часовой пояс
`get_disk_space`	Место на всех фиксированных дисках
`get_perf_snapshot`	Снимок CPU, памяти, дискового I/O и сети, не зависящий от локали
`get_registry`	Чтение ключа или значения реестра и, по запросу, имён дочерних ключей (только чтение)
`get_certificates`	Сертификаты личного хранилища с сортировкой по дням до истечения
`get_network_config`	IP, шлюз и DNS по каждому сетевому адаптеру
`test_network`	ICMP-пинг или проверка TCP-порта с удалённого хоста

Идентичность и конфигурация

Инструмент	Описание
`get_environment_variables`	Переменные окружения по областям
`get_scheduled_tasks`	Запланированные задачи с последним/следующим запуском и результатом
`get_local_users`	Локальные учётные записи со статусом и последним входом
`get_user_groups`	Членство в локальных группах
`get_security_context`	Идентичность текущей сессии, группы, привилегии
`get_permissions`	Записи ACL для файлов и каталогов

Сеть и ПО

Инструмент	Описание
`get_tcp_connections`	Активные TCP-соединения с фильтром по состоянию, порту, PID или имени процесса и необязательной сводкой по группам
`get_dns_cache`	Локальный кэш DNS-клиента
`get_installed_software`	Установленное ПО из 64- и 32-битных ключей удаления
`resolve_dns_name`	Цепочка разрешения DNS с удалённого сервера

Active Directory — решено, но не построено

Ни одного из этих инструментов в бинаре сегодня нет. Раздел фиксирует решение (ADR-0014, срезы W19–W21), а не возможность. Агент видит WinRM и хост в домене и предполагает, что каталог доступен. Но каталог не доступен.

Инструменты только для чтения, опрос через System.DirectoryServices, а не командлетами RSAT:

Инструмент	Описание
`get_ad_object`	Один пользователь, группа или компьютер: состояние учётной записи, сроки пароля, последний вход, DN, OU
`get_ad_membership`	Членство в обе стороны, при необходимости вложенное
`find_ad_objects`	Поиск по имени или `sAMAccountName` с потолком результатов
`get_ad_domain_info`	Домен, лес, уровни функционирования, роли FSMO, контроллеры, доверия, сайты, парольная политика и PSO
`get_ad_health`	Партнёры репликации и отставание, службы NTDS/DNS/ADWS/W32Time, состояние SYSVOL
`get_ad_stale_objects`	Залежавшиеся пользователи и компьютеры по `lastLogonTimestamp` и `pwdLastSet`

Запись в каталог (срезы W20–W21) намеренно оставлена за пределами первой волны. По умолчанию она будет выключена за WINRIG_ALLOW_AD_WRITE. Текущий бинарь эту переменную не читает.

Модифицирующие инструменты

Эти инструменты меняют хост и требуют подтверждения.

Каждое подтверждение называет хост сеанса, пользователя запроса и инструмент. Оно называет цель и операцию с деталями, доступными до вызова, и содержит одну простую строку, которая сообщает эффект и можно ли операцию отменить. Скрытое значение показано только как hidden: старое и новое значения set_registry и содержимое write_file — скрытые значения. Текст команды и текст скрипта показываются целиком, без лимита в 200 символов, потому что оператор подтверждает то, что запустится. kill_process не читает командную строку вовсе. Сервер очищает каждое поле и ограничивает остальные поля 200 символами; обрезанный путь сохраняет хвост, а обрезанное поле несёт маркер ... внутри лимита. Текст английский и не зависит от языка хоста.

Инструмент	Описание
`restart_service` / `stop_service` / `start_service`	Управление службами с состоянием до и после. `stop_service` проверяет останов: ждёт `wait_seconds` (по умолчанию 15), читает состояние и события 7031/7034/7036 журнала System и сообщает ошибкой, если служба снова запустилась. При `disable=true` он задаёт тип запуска Disabled до останова
`set_service_start_type`	Задать тип запуска (Automatic, AutomaticDelayed, Manual или Disabled). Подтверждение показывает текущий и новый тип запуска. Инструмент отвергает службу, критичную для удалённого сеанса
`kill_process`	Принудительное завершение процесса по PID. Подтверждение показывает имя, путь к исполняемому файлу (без аргументов) и время запуска. Командная строка не читается, поэтому секрет в ней не утечёт (DR-4)
`set_registry`	Запись значения реестра. Старое и новое значения показаны только как `hidden`; подтверждение сообщает, есть ли старое значение и какого оно типа
`delete_file` / `delete_directory`	Удаление с запросом подтверждения; инструмент отвергает защищённые пути, в том числе по фактическому расположению системы на хосте. `delete_file` принимает список разрешённых путей `WINRIG_WRITE_ALLOW_PATHS`; рекурсивный `delete_directory` — нет (DR-6)
`flush_dns`	Очистка кэша DNS-клиента
`write_file`	Запись файла с заменой целиком. Выключен по умолчанию: задайте `WINRIG_ALLOW_FILE_WRITE=true`, иначе сервер не объявляет инструмент и вызвать его нельзя
`run_command`	Запуск произвольной команды PowerShell. Выключен по умолчанию: задайте `WINRIG_ALLOW_COMMAND_EXEC=true`, иначе сервер не объявляет инструмент и вызвать его нельзя. Подтверждение показывает полный текст команды. Сервер отвергает команду вне непустого `WINRIG_ALLOWED_COMMANDS` до сетевой активности
`run_script`	Запуск скрипта PowerShell длиннее одной командной строки WinRS. Выключен по умолчанию: задайте `WINRIG_ALLOW_SCRIPT_EXEC=true`, иначе сервер не объявляет инструмент и вызвать его нельзя. Сервер записывает скрипт во временный `.ps1` в каталоге временных файлов сеанса, читает файл и выполняет его текст как блок скрипта, затем пытается удалить файл. У скрипта нет `$PSScriptRoot`, нет `$PSCommandPath` и нет аргументов. Одно подтверждение покрывает всю операцию и показывает весь скрипт и его SHA-256. Список префиксов `WINRIG_ALLOWED_COMMANDS` не фильтрует скрипт
`copy_file` / `move_file` / `rename_file` / `create_directory`	Копирование, перемещение и переименование файла или каталога, а также создание каталога с родителями. Выключены по умолчанию: задайте `WINRIG_ALLOW_FILE_OPS=true`, иначе сервер не объявляет инструменты и вызвать их нельзя. Все четыре запрашивают подтверждение. Копирование каталога показывает счётчики и отвергает исходное дерево с символической ссылкой или junction. Перемещение на одном томе переименовывает; между томами копирует файл и удаляет источник, а перемещение каталога между томами отвергает (DR-6). Переименование принимает одно новое имя. Ни один из четырёх не заменяет существующий каталог, а существующая цель требует `overwrite` (кроме `create_directory`, который её отвергает). Цель подчиняется `WINRIG_WRITE_ALLOW_PATHS`; источник копирования может лежать в системном каталоге, потому что копирование только читает его
`download_file`	Копирование файла с хоста в локальный каталог передачи. Выключен по умолчанию: задайте `WINRIG_ALLOW_FILE_DOWNLOAD=true`, иначе сервер не объявляет инструмент и вызвать его нельзя. Инструмент читает файл на хосте окнами по 16 МиБ и пишет его в `WINRIG_TRANSFER_DIR`, и сверяет SHA-256 обеих сторон. Результат несёт имя, размер и хеш, а не содержимое. Каждое скачивание требует подтверждения (ADR-0017 §21–28)
`upload_file`	Копирование файла из локального каталога передачи на хост. Выключен по умолчанию: задайте `WINRIG_ALLOW_FILE_UPLOAD=true`, иначе сервер не объявляет инструмент и вызвать его нельзя. Инструмент хеширует локальный файл и показывает SHA-256 в подтверждении. Он отправляет байты окнами по 4 МиБ во временный файл. Каждое окно идёт через стандартный ввод команды на хосте. Хост хеширует этот файл до переименования. Цель подчиняется `WINRIG_WRITE_ALLOW_PATHS`, а существующая цель требует `overwrite`. Каждая загрузка требует подтверждения (ADR-0017 §26)

Переключатели, которые включают модифицирующие инструменты

Переключатель	Действие
`WINRIG_ALLOW_FILE_WRITE=true`	Объявляет инструмент `write_file`. Пока значение `false`, сервер удаляет инструмент из роутера
`WINRIG_MAX_WRITE_BYTES`	Наибольшее содержимое, которое принимает `write_file` и загружаемый скрипт `run_script`, в байтах (по умолчанию 64 КиБ)
`WINRIG_WRITE_ALLOW_PATHS`	Список разрешённых оператором путей записи через запятую. Элемент снимает отказ по защищённому пути для `write_file` и `delete_file`. Он также снимает его для цели `copy_file` и `move_file`, для пути и назначения `rename_file` и для `create_directory`. Тогда подтверждение предупреждает о системном каталоге, корне тома или корне ресурса. Компонент 8.3 и символическая ссылка или junction остаются отвергнутыми (ADR-0017 §7–13)
`WINRIG_ALLOW_COMMAND_EXEC=true`	Объявляет инструмент `run_command`. Пока значение `false`, сервер удаляет инструмент из роутера
`WINRIG_ALLOW_SCRIPT_EXEC=true`	Объявляет инструмент `run_script`. Пока значение `false`, сервер удаляет инструмент из роутера
`WINRIG_ALLOW_FILE_OPS=true`	Объявляет инструменты `copy_file`, `move_file`, `rename_file` и `create_directory`. Пока значение `false`, сервер удаляет их из роутера
`WINRIG_ALLOW_FILE_DOWNLOAD=true`	Объявляет инструмент `download_file`. Пока значение `false`, сервер удаляет инструмент из роутера
`WINRIG_ALLOW_FILE_UPLOAD=true`	Объявляет инструмент `upload_file`. Пока значение `false`, сервер удаляет инструмент из роутера
`WINRIG_TRANSFER_DIR`	Локальный каталог передачи (по умолчанию подкаталог `transfer` каталога состояния). Должен быть абсолютным путём. В HTTP-режиме сервер добавляет по одному подкаталогу на пользователя (DR-3)
`WINRIG_MAX_TRANSFER_BYTES`	Наибольший файл, который принимают `download_file` и `upload_file`, в байтах (по умолчанию 256 МиБ)
`WINRIG_ALLOWED_COMMANDS`	Список префиксов команд через запятую. Пустое значение допускает любую команду. Префикс не образует границу (ADR-0013 §18)
`WINRIG_CONFIRM_FALLBACK`	`refuse` (по умолчанию) или `proceed`. При `proceed` клиент без elicitation выполняет модифицирующую операцию, и аудит помечает запуск (TR-SEC-11)
`WINRIG_ALLOW_INSECURE_TLS=true`	Разрешает `verify_cert=false` в `connect`. По умолчанию сервер его отвергает

run_command запускает одну команду PowerShell, которую подтверждает оператор. Сервер кодирует текст команды как base64-строку UTF-16. Затем он декодирует строку в блок скрипта, поэтому текст не может выйти за пределы сгенерированной обёртки. Команда должна влезть в одну командную строку WinRS. Поэтому текст содержит не более 979 символов. WINRIG_ALLOWED_COMMANDS — это список префиксов, сравнение без учёта регистра после обрезки пробелов. Пустой список допускает любую команду. Список не образует границу. Ведущие &, . и powershell -c обходят его. Псевдоним, оператор вызова и закодированная команда делают то же. Любой текст после разрешённого префикса выполняется. Поэтому ;, перевод строки, | и $(...) не возвращают управление списку. Элемент & или . сам по себе допускает всё. Скрипт, записанный через write_file и затем запущенный, тоже обходит его. При включённом run_command и пустом списке защита путей перестаёт быть гарантией продукта (ADR-0013 §18).

run_script запускает скрипт PowerShell длиннее одной командной строки WinRS. Он выключен по умолчанию (WINRIG_ALLOW_SCRIPT_EXEC). Сервер записывает скрипт во временный .ps1 в каталоге временных файлов сеанса кусками, читает файл и выполняет его текст как блок скрипта, затем пытается удалить файл. У скрипта нет $PSScriptRoot, нет $PSCommandPath и нет аргументов. Сервер показывает SHA-256 скрипта в подтверждении и записывает его в аудит, и он сверяет хеш до запуска. Одно подтверждение покрывает всю операцию и показывает весь скрипт построчно, без лимита в 200 символов. WINRIG_ALLOWED_COMMANDS не фильтрует скрипт, потому что сервер не может осмысленно проверить текст скрипта по префиксу; подтверждение это сообщает. Скрипт подчиняется WINRIG_MAX_WRITE_BYTES, а вывод — тем же лимитам, что у run_command. Результат несёт temp_file с исходом очистки и warning, когда временный файл может остаться. Инструмент может отказать, если скрипт не даёт вывода 60 секунд (ADR-0017 §29–34).

copy_file, move_file, rename_file и create_directory выключены по умолчанию (WINRIG_ALLOW_FILE_OPS). copy_file копирует файл или каталог; копирование каталога рекурсивно, и подтверждение показывает счётчики файлов, каталогов и байтов. Копирование обходит исходное дерево один раз и отвергает его, если в нём есть символическая ссылка или junction; команда повторяет проверку во время выполнения. move_file переименовывает объект на одном томе, а между томами копирует файл, сверяет размер и затем удаляет источник. Перемещение каталога между томами отвергается, потому что подразумеваемое рекурсивное удаление попадает под DR-6. rename_file меняет последний компонент в том же каталоге и принимает одно новое имя: разделитель, зарезервированное имя устройства (CON, NUL, COM1, …) и точка или пробел в конце отвергаются. create_directory создаёт конечный каталог и каждого недостающего родителя; подтверждение показывает число созданных уровней и самый верхний создаваемый уровень, который тоже проходит границу записи. Цель каждого инструмента подчиняется списку WINRIG_WRITE_ALLOW_PATHS; источник копирования только читается, поэтому он может лежать в системном каталоге. Ни один из четырёх не заменяет существующий каталог, а существующая цель требует overwrite (кроме create_directory, который её отвергает). Инструменты обращаются к хосту классами [IO.File] и [IO.Directory], поэтому шаблон в пути не раскрывается. Частичное копирование или перемещение — это ошибка, а не успех. Долгое копирование или перемещение может отказать, если не даёт вывода 60 секунд. Цель или источник, доступные только для чтения, дают понятную ошибку: у инструмента нет -Force, и он никогда не снимает атрибут «только чтение». Перезапись сохраняет список управления доступом и атрибуты заменяемого файла. write_file тоже использует разрешённый хостом .NET-путь для своих кусков.

download_file выключен по умолчанию. Задайте WINRIG_ALLOW_FILE_DOWNLOAD=true, чтобы сервер объявил его. Он читает файл на хосте и пишет его в локальный каталог передачи. Сначала инструмент читает размер и время изменения источника. Он отвергает файл выше WINRIG_MAX_TRANSFER_BYTES (по умолчанию 256 МиБ) до чтения. Подтверждение показывает разрешённый удалённый путь, размер, время изменения и локальное назначение. Хеш оно не показывает: до чтения он неизвестен. Затем инструмент читает файл окнами по 16 МиБ через необработанный канал, строками base64 по 1 МиБ. Вывод идёт непрерывно, поэтому большой файл не даёт тайм-аут, а весь файл никогда не грузится в память хоста. Хост читает с разделяемым доступом на чтение и удаление, поэтому файл, открытый другим процессом (живой журнал), всё равно копируется. Инструмент хеширует байты по мере чтения. После последнего окна отдельный проход на хосте хеширует ровно прочитанную длину и сверяет два дайджеста. Расхождение или короткий файл — это отказ с текстом «the source changed during the transfer». Инструмент пишет окна во временный файл рядом с конечным путём. Сбой или отмена удаляют этот файл, поэтому частичный файл не остаётся. Результат несёт имя, размер и хеш, а не содержимое. Локальный каталог — WINRIG_TRANSFER_DIR, по умолчанию подкаталог transfer каталога состояния. В HTTP-режиме сервер изолирует каждого пользователя в подкаталоге его канонической идентичности (DR-3). Каталог и его файлы используют приватные режимы (0700/0600). Инструмент принимает одно простое локальное имя файла. Он отвергает разделитель, компонент .., ведущую точку, зарезервированное имя устройства, символическую ссылку и управляющий или форматный символ. Существующий локальный файл требует overwrite. Источник-каталог, символическая ссылка или junction отвергаются. Источник в системном каталоге допускается, и подтверждение предупреждает об этом. Каждое скачивание требует подтверждения, потому что переносит данные с хоста. Аудит записывает разрешённые пути, размер, оба хеша и состояние подтверждения. Содержимое он не записывает (ADR-0017 §21–28).

upload_file выключен по умолчанию. Задайте WINRIG_ALLOW_FILE_UPLOAD=true, чтобы сервер объявил его. Он копирует файл из локального каталога передачи на хост. Инструмент принимает одно простое локальное имя файла и абсолютный удалённый путь. Он читает только из каталога пользователя запроса (DR-3). Он отвергает символическую ссылку, любой объект кроме обычного файла и файл, доступный другому пользователю на запись. В Unix он также отвергает файл с несколькими жёсткими ссылками. В Windows инструмент не видит жёсткую ссылку, поэтому держите каталог передачи приватным. Он отвергает файл выше WINRIG_MAX_TRANSFER_BYTES (по умолчанию 256 МиБ) до чтения. Инструмент хеширует локальный файл один раз. Подтверждение показывает локальный источник, разрешённый удалённый путь, размер, SHA-256, состояние перезаписи и эффект. Удалённая цель подчиняется границе write_file. Защищённый путь отвергается, если его не покрывает WINRIG_WRITE_ALLOW_PATHS; тогда подтверждение предупреждает. Существующая цель требует overwrite. После подтверждения инструмент отправляет файл окнами по 4 МиБ. Каждое окно — одна команда на хосте, а байты приходят на её стандартный ввод, а не в текст команды. Поэтому предел командной строки WinRS примерно в 8191 символ не ограничивает размер окна. Первое окно создаёт временный файл рядом с конечным путём и отвергает существующий файл. Каждое следующее окно должно найти временный файл ожидаемой длины. Инструмент хеширует байты ещё раз при отправке. Он останавливается, если дайджест отличается от подтверждённого, например когда локальный файл изменился после подтверждения. Последняя команда на хосте хеширует временный файл и сверяет дайджест с подтверждённым. Затем она проверяет цель и каждый родительский каталог на символическую ссылку или junction и ставит файл переименованием (атомарная замена при overwrite). Расхождение или сбой до размещения удаляют временный файл и оставляют цель прежней. Отмена останавливает команду на хосте и удаляет временный файл. Отмена или потерянный ответ во время размещения могут прийти после замены. Тогда цель в неизвестном состоянии, аудит записывает unknown, и оператор должен проверить файл. Если хост недоступен для удаления, ошибка называет временный файл. Результат несёт имя, удалённый путь, размер и хеш. Аудит записывает два пути, размер, оба хеша и состояние подтверждения, но не содержимое (ADR-0017 §26, §38).

delete_file, delete_directory, write_file и файловые операции отвергают защищённые пути и точки повторной обработки. Не вызывайте их для корня тома или системного каталога. Возможна потеря данных. Список WINRIG_WRITE_ALLOW_PATHS снимает отказ для write_file, delete_file и цели файловой операции, когда элемент покрывает её. Копирование только читает источник, поэтому источник в системном каталоге разрешён. Тогда подтверждение предупреждает о системном каталоге, корне тома или корне ресурса. Элемент никогда не снимает отказ по компоненту 8.3 или по символической ссылке или junction. У run_command и run_script защиты путей нет вовсе: одна команда или скрипт может удалить или перезаписать всё, до чего дотянется учётная запись.