Natch_v.3.2
Copyright (c) 2020-2024 ISP RAS
based on QEMU emulator v.7.2.0
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers
Available builds: x86_64, aarch64
optional arguments:
-h, --help show this help message and exit
-v, --version Natch version
main commands:
{create,cr,record,replay,kvm,tuning,info,delete,edit,set,modules,settings}
use <cmd_name> -h/--help for additional information
create (cr) create project
record record scenario (only for project)
replay replay scenario (only for project)
kvm launch QEMU kvm without Natch (only for x86_64)
tuning launch tuning (only for project)
info info about project (only for project)
delete delete scenario (only for project)
edit edit Natch config files (only for project)
coverage get coverage for code (only for project)
set change some project settings (only for project)
modules add/update/copy modules in the project (requires sudo)
settings Natch shell settings
Для работы с инструментом Natch предусмотрен пул команд, объединенных под названием natch.
Главная команда natch имеет следующие субкоманды:
createrecordreplaykvmtuninginfodeleteeditcoveragesetmodulessettings
Представленные команды могут иметь параметры или субкоманды, поэтому для получения информации
следует использовать параметр -h/--help, например:
user@user: natch edit -h
usage: natch edit [-h] {main,taint} ...
optional arguments:
-h, --help show this help message and exit
Natch configs editing:
{main,taint,debug} use <cmd_name> -h/--help for additional information
main edit main config natch.cfg
taint edit scenario config taint.cfg
debug edit config debug_info.cfg
С версии 3.2 инструмент поставляется с поддержкой двух архитектур: x86_64 и aarch64.
При первом запуске Natch будет предложено выбрать архитектуру по умолчанию. Далее, если вы собираетесь работать только с одной архитектурой, ничего предпринимать не нужно.
Если необходимо использовать другую архитектуру, некоторые команды Natch получили параметр -a/--arch,
позволяющий выбрать нужную архитектуру, независимо от определенной архитектуры по умолчанию.
Архитектуру по умолчанию можно изменить в любой момент с помощью команды natch settings arch,
описанной ниже.
Команда create применятся для создания Natch-проекта.
Параметры (обязательные выделены жирным шрифтом):
workdir-- название проекта (либо название директории, которая будет создана в текущем расположении, либо полный путь до будущего проекта)image-- путь к образу исследуемой системы-a/--arch-- выбор архитектуры (x86_64, aarch64)-k/--kernel-- путь до ядра-o/--os_name-- выбор гостевой ОС (Linux, FreeBSD, Win7, Win8, Win8.1, Win10)-c/--config-- путь до файла конфигурации для автоматического создания проекта-h/--help-- справка по команде
Пример:
natch create test_sample Natch_testing_materials/test_image_debian.qcow2
Подробнее о создании проекта можно узнать в разделе Создание проекта.
Команда record служит для записи сценария.
Запускаться должна из директории с проектом.
Параметры (обязательные выделены жирным шрифтом):
-s/--scenario-- имя сценария-d/--debug-- отладочный вывод командной строки на экран и в файлdebug_qemu_cmdline.ini-h/--help-- справка по команде
Пример:
natch record -s sample
Подробнее о записи сценария в разделе Запись сценария.
Команда replay служит для воспроизведения ранее записанных сценариев.
Запускаться должна из директории с проектом.
Параметры:
-s/--scenario-- название сценария-S/--start-- icount или название снапшота, на котором следует начать сбор данных-E/--end-- icount или название снапшота, на котором следует закончить сбор данных--no-check-- отключение проверки изменения конфигурационного файлаtaint.cfg-d/--debug-- отладочный вывод командной строки на экран и в файлdebug_qemu_cmdline.ini-h/--help-- справка по команде
При использовании параметров --start/--end следует придерживаться следующих правил:
- параметры
--startи--endмогут быть использованы как вместе, так и по отдельности - если заданы оба, значение параметра
--endне может быть меньше чем--start(при использовании названий снапшотов они приводятся к числовому эквиваленту)
Если значение параметра --start не совпадает со значением icount ни одного из существующих снапшотов --
стартовый снапшот будет определен автоматически (ближаший слева).
Узнать текущий icount во время работы эмулятора можно с помощью команды монитора info replay.
Узнать диапазон icount-ов в сценарии можно с помощью команды natch info -s <name>.
Примеры:
natch replay
natch replay -s sample
natch replay --start login --end get_info
Подробнее о воспроизведении сценария в разделе Воспроизведение сценария.
Команда kvm предназначена для запуска эмулятора в режиме аппаратной виртуализации.
При использовании архитектуры aarch64 выполнение этой команды приведет к запуску эмулятора QEMU
только без расширений Natch.
Может запускаться как из директории с проектом, так и вне ее.
Параметры:
-i/--image-- путь к образу исследуемой системы (обязательно при запуске вне проекта)-s/--snapshot-- добавление опцииsnapshotдля сохранности образа-a/--arch-- выбор архитектуры (x86_64, aarch64)-d/--debug-- отладочный вывод командной строки на экран и в файлdebug_qemu_cmdline.ini-h/--help-- справка по команде
Примеры:
natch kvm -i Natch_testing_materials/test_image_debian.qcow2
natch kvm -s
Обычно используется для подготовки объекта оценки (подробнее в разделе Настройка окружения для работы с Natch) или для быстрого доступа к исследуемой системе.
Команда tuning служит для извлечения смещений структур ядра исследуемой системы и создания или перезаписи
конфигурационного файла task.cfg.
Запускаться должна из директории с проектом.
Параметры:
-a/--arch-- выбор архитектуры (x86_64, aarch64)-d/--debug-- отладочный вывод командной строки на экран и в файлdebug_qemu_cmdline.ini-h/--help-- справка по команде
Если в вашем проекте уже имеется файл task.cfg, вы увидите следующий диалог:
You already have task.cfg
Do you want to do tuning again? [Y/n]
При отказе выполнение команды завершится, в случае согласия будет запущен эмулятор и следует дождаться завершения его работы.
Команда может быть полезна, если вы используете проект, созданный на более старой версии Natch, и существующий конфигурационный файл не соответствует текущей версии инструмента.
Команда info предоставляет информацию о существующих в проекте сценариях и сохраненных снапшотах для каждого из них.
Запускаться должна из рабочей директории проекта.
Параметры:
-s/--scenario-- название сценария-h/--help-- справка по команде
Пример:
natch info
Existing scenarios:
----- sample ------------------------------------------------------------
Snapshot list:
NAME ICOUNT DATE
init 0 2024-06-03 15:57:57
load 13563000904 2024-06-03 15:59:14
The last icount for this scenario: 13888364825
----- hello -------------------------------------------------------------
Snapshot list:
NAME ICOUNT DATE
init 0 2024-06-04 18:00:46
temp_snap 8251101826 2024-06-04 18:01:23
very_very_long_name 11708689459 2024-06-04 18:01:37
The last icount for this scenario: 11818629758
Пример:
natch info -s sample
----- sample ------------------------------------------------------------
Snapshot list:
NAME ICOUNT DATE
init 0 2024-06-03 15:57:57
load 13563000904 2024-06-03 15:59:14
The last icount for this scenario: 13888364825
Команда delete удаляет сценарии и связанные с ними файлы из рабочей директории.
Запускаться должна из рабочей директории проекта.
Параметры:
-s/--scenario-- название сценария-a/--all-- удалить все сценарии-h/--help-- справка по команде
Пример:
natch delete -s test
Are you sure? [y/N] y
Scenario 'test' has been deleted
Do you want to remove output directory? [y/N] y
Output directory 'output_test' has been deleted
При наличии директории с выходными файлами для SNatch (если выполнялось воспроизведение сценария), также будет предложено удалить и ее.
Команда edit предназначена для более удобного редактирования конфигурационных файлов проекта.
Имеет следующие субкоманды:
maintaintdebug
Запускаться эти команды должны из директории с проектом.
Все команды этой группы открывают на редактирование один из файлой конфигурации проекта или сценария.
Команда main предназначения для редактирования главного конфигурационного файла -- natch.cfg.
Команда taint предназначения для редактирования конфигурационных файлов сценариев taint.cfg.
Если сценариев в проекте несколько -- будет отображено меню для выбора нужного сценария.
Команда debug предназначения для редактирования конфигурационного файла с параметрами
получения отладочной информации debug_info.cfg.
Параметры:
-h/--help-- справка по команде
Пример:
natch edit main
При первом запуске Natch (начиная с версии 3.1) перед редактированием файлов будет предложено выбрать
текстовый редактор по умолчанию. Изменить эту настройку можно с помощью команды natch settings editor,
которая описана ниже.
Команда coverage на данный момент является экспериментальной. Предназначена для
работы с исходными кодами исследуемого ПО и получения покрытия кода.
Имеет субкоманды:
extract
Команда extract извлекает из образа системы исходные коды исследуемого ПО, а также
строит отображение покрытия в html на основе этих кодов и покрытия кода, собранного ранее.
Параметры:
-s/--scenario-- название сценария-h/--help-- справка по команде
Как упоминалось ранее, функциональность экспериментальная и сырая, поэтому алгоритм работы с ней на данный момент не совсем удобный. Необходимые шаги:
- Записать сценарий
- Удостовериться, что в основном конфигурационном файле активна секция
Coverageи указан файл (с версии 3.2 это так по умолчанию) - Выполнить воспроизведение сценария
- Выполнить команду
natch coverage extract
Воспроизведение сценария перед выполнением команды необходимо, чтобы получить файл с покрытием.
В директории с выходными файлами появятся папка с исходными кодами и папка coverage с html-страницами
с покрытием. Для самостоятельного просмотра следует открыть в браузере index.html. В дальнейшем
эта функциональность будет реализована в SNatch (исходные коды можно смотреть там уже сейчас).
Архив обновится автоматически.
Пример:
natch coverage extract -s sample
По умолчанию покрытие собирается для всех пользовательских модулей, при желании можно включать эту
опцию для любого модуля из конфигурационного файла модулей module.cfg или выключить ее.
Для этого в module.cfg предусмотрено поле coverage, значение которого следует установить в True или False соответственно.
Подробнее в приложении Формат списка исполняемых модулей.
Команда set служит для внесения изменений в настройки проекта. Имеет субкоманды:
memoryportmode
Запускаться эти команды должны из директории с проектом.
Команда memory предназначена для изменения выделяемой виртуальной машине оперативной памяти.
Параметры:
value-- новый объем оперативной памяти-h/--help-- справка по команде
Указывать объем памяти следует с постфиксом G или M без пробела.
Пример:
natch set memory 8G
Команда port служит для изменения отслеживаемых портов, проброса портов в виртуальную машину или
отмены проброса.
Параметры:
value-- список портов для проброса или 0 для сброса-h/--help-- справка по команде
Параметр value может иметь вид списка портов для проброса, перечисленных через запятую без пробелов,
либо 0 для отмены проброса. Если в настройках проекта уже были проброшенные порты, они будут заменены
новым списком.
Примеры:
natch set port 8888,5555 # пробросятся порты 8888 и 5555
natch set port 0 # проброшенные порты будут сброшены, установятся порты по умолчанию: 80 и 22
Так как настройки портов влияют не только на командную строку запуска эмулятора, но и на конфигурационные файла сценариев, то будет предложено внести изменения и в них (нужные сценарии надо будет отменить галочкой).
Команда mode служит для перевода эмулятора между режимами: графическим, текстовым или vnc.
Параметры:
{graphic, text, vnc}-- режим работы эмулятора-p/--port-- порт (только для vnc)-h/--help-- справка по команде
Параметр -p/--port для vnc необязательный, по умолчанию порт 0.
Примеры:
natch set mode graphic
natch set mode vnc -p 5910
Выполнение вышеописанных команд приведет к изменению параметров запуска эмулятора (qemu_opts.ini).
Команда modules отвечает за работу с модулями в проекте и образе. Имеет субкоманды:
addupdateextractcopy
Команды add и update можно запускать только из рабочей директории проекта.
Для работы команд natch modules потребуется пароль администратора для монтирования образа.
Команда add служит для дополнения проекта новыми модулями.
В процессе работы команды будет проанализирован каталог с новыми модулями, исследованы зависимости и скачана информация о библиотечных модулях (если есть), а так же перестроена символьная информация.
На выходе получим новый module.cfg и обновленные каталоги с информацией о модулях.
Параметры:
--host-dir | --guest-dir-- взаимоисключающие параметры для указания пути к директории с модулями в хостовой системе (host-dir) или в гостевой (guest)-h/--help-- справка по команде
Пример:
natch modules add --guest-dir /home/user/Sample1
Команда update служит для обновления текущих модулей в проекте.
Команда делает все то же самое что add, но не с новыми модулями,
а уже существующими, на случай если в образе что-то изменилось, например, добавилось локальное хранилище
отладочной информации.
На выходе получим новый module.cfg и обновленные каталоги с информацией о модулях.
Параметры:
-h/--help-- справка по команде
Пример:
natch modules update
Команда extract служит для извлечения файлов из образа в хостовую систему.
Такая необходимость может возникать при подготовке объекта оценки к анализу.
Параметры (обязательные выделены жирным шрифтом):
-i/--image-- путь к образу гостевой операционной системы (обязательный вне проекта)-D/--dest-- путь к директории, в которую будут сохранены копируемые файлы-p/--paths-- список, содержащий пути до файлов/директорий в гостевой системе-e/--exec-- флаг, указывающий скачивать только бинарные файлы-l/--log-- путь к файлу, в который будет записан журнал работы-d, --debug-- флаг включения диагностических сообщений-h/--help-- справка по команде
Если команда запускается из рабочей директории проекта, указывать параметр -i/--image не требуется.
Директория для сохранения файлов из образа будет создана автоматически.
Пример:
natch modules extract -i Natch_testing_materials/test_image_debian.qcow2 -p /home/user/Sample1 -D bins -e
Команда copy служит для загрузки в образ файлов из хостовой системы.
Является обратной команде extract.
Параметры (обязательные выделены жирным шрифтом):
-i/--image-- путь к образу гостевой операционной системы (обязательный вне проекта)-D/--dest-- путь к директории, в которую будут сохранены копируемые файлы-p/--paths-- список, содержащий пути до файлов/директорий в хостовой системе-e/--exec-- флаг, указывающий загружать только бинарные файлы-l/--log-- путь к файлу, в который будет записан журнал работы-d, --debug-- флаг включения диагностических сообщений-h/--help-- справка по команде
Пример:
natch modules copy -i Natch_testing_materials/test_image_debian.qcow2 -p Natch_testing_materials/Sample2_bins -D /home/user/Sample2 -e
Команда settings предназначена для изменения общих настроек инструмента.
Имеет субкоманды:
editorarch
Команда editor позволяет выбрать текстовый редактор по умолчанию, с помощью которого будут открываться на
редактирование конфигурационные файлы проекта. Отображается список установленных на машине редакторов из
предопределенного списка (vim, vi, gedit, nano, subl).
Команда arch позволяет определить архитектуру, используемую по умолчанию. Предлагается выбор из двух доступных
архитектур -- x86_64 и aarch64.