Package: bashmator
Bashmator- консольный менеджер скриптов, основанный на формате YAML.Основная задача программы - предоставить простую и универсальную систему для хранения, поиска, запуска и логирования большого количества небольших скриптов и однострочников.Как это работаетКаждый скрипт вносится в YAML файл. В этом файле с помощью ключей задаются аргументы командной строки, параметры подстановки их значений в код скрипта, используемая оболочка, а также информация, по которой этот скрипт можно будет найти.YAML файлы хранятся в папке (библиотеке). Для каждой библиотеки bashmator собирает необходимую информацию о доступных скриптах и поддерживает её актуальность, чтобы обеспечить возможность быстрого поиска.Установкаpip install --upgrade bashmatorВ комадной строке станет доступен под короткими названиямbashmatorиbshm.Далее рекомендуется добавить оболочку и пересканить библиотеку:bashmator shell add /usr/bin/bash
bashmator library scan -fИспользованиеbashmator --helpusage: bashmator [-h] [-v] {use,search,set,shell,library} ...

                                        __     _  
    _           _             _         \ \   | | 
   | |_ ___ ___| |_ _____ ___| |_ ___ ___\ \ / __)
   | . | .'|_ -|   |     | .'|  _| . |  _|> >\__ \
   |___|__,|___|_|_|_|_|_|__,|_| |___|_| / / (   /
    by vinzekatze                       /_/   |_| 
    version 1.0.0
    
.................................................................

used library: default

commands:
  {use,search,set,shell,library}
    use                 use script
    search              search script at library by keywords
    set                 settings
    shell               shells management
    library             libraries management

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exitbashmator use --helpusage: bashmator use [-l] [-o FILE] [-i] [-c] [-h] script ...

Runs a script from the library by it's name.

.................................................................

positional arguments:
  script               script name and it's options

script launch options:
  -l, --log-headers    print log headers when executing script
  -o FILE, --out FILE  log execution process to file (append
                       mod)

code printing options:
  -i, --install        show script's installation information
  -c, --code           print script without execution

other options:
  -h, --help           show this help message and exitbashmator search --helpusage: bashmator search [-i] [-A] [-D] [-S] [-h] [keyword ...]

Search for a script in the used library. By default, the search
is performed by tags and script names.

.................................................................

positional arguments:
  keyword            keywords for search

search options:
  -i, --ignore-case  ignore case distinctions
  -A, --author       add search by author
  -D, --description  add search by script description
  -S, --shell        add search by shell

other options:
  -h, --help         show this help message and exitbashmator set --helpusage: bashmator set [--auto-scan {true,false}]
                     [--color {true,false}] [-h]

Current setings:
  auto-scan True
  color True

.................................................................

settings:
  --auto-scan {true,false}
                        automatically detect changes in the
                        used library
  --color {true,false}  use color on the command line

other options:
  -h, --help            show this help message and exitbashmator shell --helpusage: bashmator shell [-h] {add,delete} ...

commands:
  {add,delete}
    add         add a new shell to the known list
    delete      remove a shell from the known list

options:
  -h, --help    show this help message and exit

.................................................................

known shells:
 name    | path             | popen arguments   | encoding
---------+------------------+-------------------+------------
 bash    | /usr/bin/bash    | ['-c']            | utf-8bashmator shell add --helpusage: bashmator shell add [--name NAME] [--encoding CODE]
                           [--popen-args LIST] [-h]
                           path

Add a new shell to the known list.

.................................................................

positional arguments:
  path               full path to the shell (for example:
                     /usr/bin/bash)

options:
  --name NAME        specify shell name (default: base name)
  --encoding CODE    shell encoding (used when logging;
                     default: 'utf-8')
  --popen-args LIST  shell arguments for the subprocess.Popen
                     function (default: '["-c"]')
  -h, --help         show this help message and exitbashmator shell delete --helpusage: bashmator shell delete [-h] name [name ...]

Remove a shell from the known list. Use 'delete ALL' to clear.

.................................................................

positional arguments:
  name        shell name (can be multiple)

options:
  -h, --help  show this help message and exitbashmator library --helpusage: bashmator library [-h] {add,delete,scan,use} ...

commands:
  {add,delete,scan,use}
    add                 add a new library to the known list
    delete              remove library from the known list
    scan                detect changes in the used library
    use                 select library for use

options:
  -h, --help            show this help message and exit

.................................................................

known libraries:
 name    | status   | path
---------+----------+----------------------------------
 default | IN USE   | /home/vinzekatze/workspace/apps/
         |          | bashmator/librarybashmator library add --helpusage: bashmator library add [--name NAME] [-h] path

Add a new library to the known list.

.................................................................

positional arguments:
  path         path to main library directory

options:
  --name NAME  specify library name (default: folder name)
  -h, --help   show this help message and exitbashmator library delete --helpusage: bashmator library delete [-h] name [name ...]

Remove a library from the known list. Type 'delete ALL' to clear.

.................................................................

positional arguments:
  name        library name (can be multiple)

options:
  -h, --help  show this help message and exitbashmator library scan --helpusage: bashmator library scan [-f] [-h]

Scans the directory of the used library for changes in it's
contents.

.................................................................

options:
  -f, --forced  reset the saved information and rescan the
                library
  -h, --help    show this help message and exitbashmator library use --helpusage: bashmator library use [-h] name

Select the library to use from the known list.

.................................................................

positional arguments:
  name        library name

options:
  -h, --help  show this help message and exitОболочкиНе смотря на название, bashmator способен работать не только с bash. Ниже представлены примеры команд добавления некоторых других оболочек, интерпритаторов и программ:Linuxbashmator shell add /usr/bin/zsh
bashmator shell add /usr/bin/python3
bashmator shell add /usr/bin/node --popen-args '["-e"]'
bashmator shell add /usr/bin/msfconsole --popen-args '["-q", "-x"]'Windows⚠️Для powershell и cmd важно указать кодировку, что бы логирование с помощьюuse -o <file> ...работало корректноbashmator shell add C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe --popen-args "['-Command']" --encoding 'cp866' --name powershell
bashmator shell add C:\Windows\System32\cmd.exe --popen-args "['/C']" --encoding 'cp866' --name cmd
bashmator shell add C:\...path\to\python\...\python.exe --name python3Потенциально bashmator может работать с любыми интерпритаторами, способными принимать последовательность команд из аргументов командной строки. Флаг, отвечающий за прием последовательности команд, должен всегда располагаться в конце списка, передаваемого в аргументе--popen-args.Создание библиотекРекомендуется создавать собственные библиотеки, а не добавлять свои скрипты в библиотеку по умолчанию.Библиотекой будет считаться любой каталог, содержащий следующие подкаталоги:files- каталог для файлов, используемых в скриптами. Полезен для повышения совместимости.modules- каталог для YAML файлов.Данные подкаталоги могут иметь собственные подкаталоги - bashmator будет их учитывать в работе.Добавить библиотеку в bashmator и выбрать её для использования:bashmator library add <path to library>
bashmator library use <library name>Создание YAML модулейМинимальная структура, необходимая для работы:shell:<SHELL NAME>script:|-<YOUR CODE>Общая структураauthor:<NAME>description:<TEXT>tags:-<TAG1>-<TAG2>-...install:<INSTALLATION INFORMATION>arguments:<ARG NAME>:default:<EMPTY, STRING OR LIST>description:<TEXT>metavar:<STRING>multiple:<TRUE | FALSE>replacer:<VALUE REPLACER>regex:<REGEX STRING><OTHER ARG NAME>:......mode:readfile:-<ARG NAME>...replace:<ARG NAME>:<VALUE TO REPLACE>:<REPLACEMENT>loop:<ARG NAME>format:<ARG NAME>:<.format() TEMPLATE><OTHER ARG>:......join:<ARG NAME>:<DELIMITER><OTHER ARG>:......pformat:<ARG NAME>:<.format() TEMPLATE><OTHER ARG>:......shell:<MAIN SHELL SHORT NAME OR PATH>script:|-<YOUR MAIN CODE>file_<NUMBER>:path:<SHORT PATH TO FILE AT LIBRARY/FILES DIRECTORY>replacer:<FULL PATH REPLACER>description:<TEXT>file_<OTHER NUMBER>:......item_<NUMBER>:shell:<OTHER SHELL SHORT NAME OR PATH>description:<TEXT>mode:<SAME STRUCTURE AS AT MAIN>script:|-<YOUR OTHER CODE>item_<OTHER NUMBER>:......Описание ключей:authorСодержит имя автора модуля, используется для поиска и удовлетворения чувства собственной значимости😅. Пример:author:vinzekatzedescriptionСодержит общую информацию о работе скрипта, которая будет выведена при вызове помощиuse <script name> -hилиuse <script name> --help.Для большего удобства рекомендуется использовать|-. Пример:description:|-Набор однострочников для получение базовой DNS информацииtagsСодержит список тегов, по которым можно будет найти скрипт с помощью командыsearch. Пример:tags:-53-dns-reconinstallСодержит информацию о ПО, которое необходимо установить для правильной работы скрипта. Данная информация будет отображена при вызове скрипта с помощью командыuse -i <script name>.Если есть возможность, рекомендуется писать сразу последовательность команд для установки, либо явно указывать, что установка чего-либо не требуется. Пример:install:|-sudo apt update -y && sudo apt install dnsrecon -yargumentsСодержит имена аргументов и их параметры. На основе заданных тут данных bashmator создает CLI для скрипта.Рекомендуется использовать полные названия для позиционных аргументов, и однобуквенные для опций.replacerпо умолчанию:#[ARGUMENT NAME]#Общий вид:arguments:n:default:42metavar:NUMregex:\d+arg:replacer:__B__multiple:truedescription:bla bla blaКлючи аргументов:defaultОпределяет значение аргумента по умолчанию, либо список возможных значений.Еслиdefaultпуст, либо отсутствует, аргумент будет обязательным.Еслиdefaultсодержит строковое или числовое значение, то аргумент будет опцией, которая по умолчанию будет подставлять указанное значение. Пример:a:default:53Еслиdefault- список из одного пустого значения, то аргумент будет опцией с пустым значением по умолчанию. Пример:a:default:-Еслиdefaultсодержит список из двух элементов, то аргумент будет флагом, подставляющим первое значение когда отсутствует в команде, а второе - когда присутствует. Пример:a:default:-https://-http://Еслиdefaultсодержит список из более чем трех элементов, аргумент сможет принимать только значения из списка. Если при этом первый элемент пуст, то аргумент будет обязательным, если же нет - первое значение из списка будет использоваться по умолчанию. Пример:arg:default:--one-twodescriptionСодержит описание назначения аргумента, которое будет выведено при вызове помощиuse <script name> -hилиuse <script name> --help. Пример:arg:description:очень важный аргументmetavarКосметический ключ, позволяющий задать свое метазначение для опций. На позиционные аргументы не влияет.Пример:arg:default:42metavar:MY_METAVARОтображение:usage: test [--arg MY_METAVAR] [-h]

options:
  --arg MY_METAVAR  (default: '42')
  -h, --help        show this help message and exitmultipleОпределяет, может ли аргумент принимать множественные значения, или нет. По умолчаниюfalse. Пример:arg:multiple:truereplacerСодержит строку, котороя будет заменятья в коде скрипта (ключscript) на значение аргумента. Не самое элегантное решение, но позволяет творить интересные трюки в комбинации сmode: format.Реплейсеры в коде скрипта заменяются в том порядке, в каком описаны ключи вarguments. После аргументов в код подставляются значенияfile_[NUMBER], если они есть.Если ключ отсутвует либо пуст, то реплейсер принимает значение#[ARGUMENT NAME]#Пример реплейсеров и скрипта:arguments:arg:replacer:-+PLACEHOLDER+-script:>-cat -+PLACEHOLDER+- | ncat 127.0.0.1 9090regexПозволяет задать регулярное выражение, с помощью которого будут проверяться значения аргумента. Не прошедие проверку значения будут вызывать ошибку и не позволять запустить скрипт. Для проверки используется функцияre.fullmatchПример:arguments:ip:regex:>-((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3,3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])script:'echo#ip#isok'Реакция скрипта на ввод:$ bashmator use ip 77.88.55.60
77.88.55.60 is ok

$ bashmator use ip 77.88.55.601
ip: error: argument 'ip': invalid value '77.88.55.601'modeИспользуется для модификации значений аргументов. Общий вид:mode:readfile:-arg2replace:arg3:v1:value1v2:value2loop:arg1format:arg2:'{0!r}'join:arg2:','arg3:';'pformat:arg2:'[{}]'Ключи mode:readfileСодержит список имен аргументов, которые будут интерпритированы как имена файлов.Данные файлы будут читаться построчно, а считанные строки будут подставляться в скрипт на место реплейсера.Пример:shell:basharguments:arg1:description:testmode:readfile:-arg1script:>-echo #arg1#Содержимое файлаsome_file.txt:one
two
threeЕсли запустить скрипт с аргументом./some_file.txt, то для исполнения будет сформирован следующий код:echoonetwothreereplaceПодзволяет заменять значения аргументов. Содержит в себе имена аргументов в качестве ключей, которые в свою очередь содержат замены в видеключ:значение.Пример:shell:basharguments:arg1:default:-A-B-Cmode:replace:arg1:A:OneB:Twoscript:>-echo #arg1#В данном примере, когда на вход скрпта в аргумент--arg1будет подаваться значениеA, в скрипт будет подставлено значениеOne, а когдаB-Two. ЗначениеCзаменено не будет и попадет в скрипт напрямую.loopЕсли содержит имя множественного аргумента (multiply: true), то скрипт будет запускаться отдельно для каждого его значения. По умолчанию этого не происходит.Пример:shell:basharguments:arg1:multiple:truemode:loop:arg1script:>-echo -n #arg1#; echo ' end'Результат выполнения скрипта c аргументами1 2 3 4 5:1 end
2 end
3 end
4 end
5 endformatСодержит имена аргументов в качестве ключей и шаблоны python функции.format()в качестве значений. Если значение аргумента пусто, то форматирование не происходит и соответсвующий реплейсер удаляется из скрипта.Для множественных аргументов форматирование производится для каждого из значений отдельно. Операцияjoinвсегда происходит после.Обычно этот ключ применяется для правильной подстановки неоднозначных значений с использованием шаблона{0!r}, однако в комбинации с пустыми по умолчанию аргументами может позволить опционально вставлять в скрипт дополнительные куски.Пример:shell:basharguments:arg1:default:-arg2:multiple:truemode:format:arg1:>-| tee {0!r}arg2:>-{0!r}script:>-echo #arg1# #arg2#Если запустить скрипт с аргументамиa d c r t, для исполнения будет сформирован следующий код:echo'a''d''c''r''t'Если с аргументами--arg1 ./file.txt a d c r t:echo'a''d''c''r''t'|tee'./test.txt'joinСодержит имена множественных аргументов (multiply: true) в качестве ключей и строки-разделители для объединения в качестве значений. По умолчанию объединение значений множественных аргументов происходит через пробел.Пример:join:arg1:','В этом случае значения множественного аргументаarg1будут подставлены в скрипт в виде следующей строки:val1,val2,val3,val4pformatТоже что иformat, но отрабатывает после всех других модов. Полезен при обработке множественных аргументов без режимаloop, позволяя дополнительно форматировать собранную с помощьюformatиjoinстроку перед вставкой в код скрипта.shellВ данном ключе указывается короткое имя оболочки, используемой для запуска скрипта, либо путь до неё.В целях улучшения совместимости рекомендуется добавлять оболочки в bashmator с помощьюbashmator shell add, а в ключеshellуказывать их короткие имена.Данный ключ обязателен, если отсутствуют ключиitem_[NUMBER], либо для каждого из них не заданыshellотдельно.Пример:shell:bashЭто тоже сработает, но так делать не рекомендуется:shell:/usr/bin/bashscriptСодержит непосредственно код скрипта, который будет исполняться.Не забудьте вставить реплейсеры аргументов!Чтобы записывать многострочные скрипты используйте|-. Чтобы записать однострочник, но в коде использовать перенос строки, используйте>-Пример 1:script:|-ls -larm -r ./Пример 2:script:>-ls -la;rm -r ./file_[NUMBER]Используется для подстановки полных путей файлов из директорииfilesбиблиотеки.replacerпо умолчанию:#file_[NUMBER]#Общий вид:file_1:description:My Wordlistpath:dicts/my_wordlist.txtfile_2:description:My Big Scriptpath:scripts/big_script.shreplacer:__BIG_SCRIPT__Ключи file_[NUMBER]:path⚠️Обязательный ключСодержит путь до файла в библиотеке относительно директорииfiles. Используйте/для перехода в директорию независимо от системы (windows, linux). Пример:file_1:path:lorem/lorem.txtТак же можно обращаться к файлам по полному пути и использовать возвраты в родительскую директорию, но этого делать не рекомендуется. Скорее всего я закрою эту возможность спустя какое-то время, так как это больше баг, чем фитча 🥲.replacerРаботает аналогично ключуreplacerдляarguments, но не подвергается форматированию.descriptionСодержит краткое описание файла, которое будет выведено при вызове помощиuse <script name> -hилиuse <script name> --help. Пример:item_[NUMBER]Используется для добавления дополнительных скриптов в один модуль. Это удобно, когда разные скрипты принимают на вход одни и те же аргументы и объеденены общим смыслом.Если существуютitem, то в CLI добавляется опция--item, которая позволяет вызывать подскрипты по номеру. Для массового запуска можно использовать последовательности:--item 1,2,4-6.Если вместе сitemсуществует основнойscript, то ему будет присвоен номер0. Запускаться по умолчанию будет только он.Общий вид:item_1:description:script 1shell:python3script:|-print(1+2)item_2:description:script 2mode:loop:arg1script:echo _ARG1_Ключи item_[NUMBER]:shellРаботает аналогично ключуshellв корне. Если ключ отсутствует, item будет использовать значение главногоshell.modeРаботает аналогично ключуmodeв корне. Используется для изменения главных параметров форматирования дляitem.Чтобы отметить действиеloopглавногоmode, оставьте ключ пустым. Например:item_2:script:echo _A_mode:loop:descriptionСодержит краткое описание назначенияitem, которое будет выведено при вызове помощиuse <script name> -hилиuse <script name> --help.script⚠️Обязательный ключРаботает аналогично главномуscript.Примеры YAML модулей представлены вовстроенной библиотеке:$ bashmator search examples
Search results:

 script name                  | status   | tags
------------------------------+----------+-----------------------------
 examples/args/choice         | OK       | help, manual, arguments
 examples/args/choice_default | OK       | help, manual, arguments
 examples/args/default        | OK       | help, manual, arguments
 examples/args/default_empty  | OK       | help, manual, arguments
 examples/args/flag           | OK       | help, manual, arguments
 examples/args/metavar        | OK       | help, manual, arguments
 examples/args/multiple       | OK       | help, manual, arguments
 examples/args/regex          | OK       | help, manual, arguments
 examples/args/replacer       | OK       | help, manual, arguments
 examples/args/simple         | OK       | help, manual, arguments
 examples/files/replacer      | OK       | help, manual, files
 examples/files/simple        | OK       | help, manual, files
 examples/items/default       | OK       | help, manual, items
 examples/items/mode          | OK       | help, manual, items
 examples/items/shell         | OK       | help, manual, items
 examples/items/simple        | OK       | help, manual, items
 examples/minimal             | OK       |
 examples/mode/format         | OK       | help, manual, mode
 examples/mode/format_empty   | OK       | help, manual, mode
 examples/mode/join           | OK       | help, manual, mode
 examples/mode/loop           | OK       | help, manual, mode
 examples/mode/pformat        | OK       | help, manual, mode
 examples/mode/readfile       | OK       | help, manual, mode
 examples/mode/replace        | OK       | help, manual, mode
 examples/simple              | OK       | help, manual, informationalПример работыНиже представлен пример запуска скриптаexamples/args/simple:Аргументы командной строки, сгенерированные из YAML$bashmatoruseexamples/args/simple-husage: examples/args/simple [-h] argExample of a simple required argument.................................................................positional arguments:arg         random stringoptions:-h, --help  show this help message and exitShell:   bashAuthor:  demoTags:    help, manual, argumentsЗапуск скрипта с включенной опцией логирования$bashmatoruse-oexample.logexamples/args/simpleblablablaInput: blablablaСодержимое записанного файлаexample.log$catexample.log+-------------------------------------------------------------------------------+ Generated by bashmator 1.1.1+-------------------------------------------------------------------------------+ Script name:               examples/args/simple (0)+ Start time:                2023-06-29 16:11:25 (UTC)+ Shell:                     /usr/bin/bash -c+-------------------------------------------------------------------------------+ Running code+-------------------------------------------------------------------------------echo 'Input: blablabla'+-------------------------------------------------------------------------------+ Log+-------------------------------------------------------------------------------Input: blablabla+-------------------------------------------------------------------------------+ End time:                  2023-06-29 16:11:25 (UTC)+-------------------------------------------------------------------------------Доступные библиотекиПотихоньку веду коллекцию сомнительных скриптов для Kali-Linuxktz-autokali