bashmator 1.1.9

Console script manager based on YAML format

Bashmator - консольный менеджер скриптов, основанный на формате YAML.

Основная задача программы - предоставить простую и универсальную систему для хранения, поиска, запуска и логирования большого количества небольших скриптов и однострочников.

Как это работает

Каждый скрипт вносится в YAML файл. В этом файле с помощью ключей задаются аргументы командной строки, параметры подстановки их значений в код скрипта, используемая оболочка, а также информация, по которой этот скрипт можно будет найти.

YAML файлы хранятся в папке (библиотеке). Для каждой библиотеки bashmator собирает необходимую информацию о доступных скриптах и поддерживает её актуальность, чтобы обеспечить возможность быстрого поиска.

Установка

Устанавливать bashmator рекомендуется через pipx. Пример:

sudo pipx install bashmator --global

В комадной строке станет доступен под короткими названиям bashmator и bshm.

Далее рекомендуется добавить оболочку и пересканить библиотеку:

bashmator shell add /usr/bin/bash
bashmator library scan -f

Использование

bashmator --help usage: bashmator [-h] [-v] {use,search,set,shell,library} ... __ _ _ _ _ \ \ | | | |_ ___ ___| |_ _____ ___| |_ ___ ___\ \ / __) | . | .'|_ -| | | .'| _| . | _|> >\__ \ |___|__,|___|_|_|_|_|_|__,|_| |___|_| / / ( / by vinzekatze /_/ |_| version 1.1.9 ................................................................. 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 exit bashmator use --help usage: 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 exit bashmator search --help usage: 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 exit bashmator set --help usage: 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 exit bashmator shell --help usage: 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-8 bashmator shell add --help usage: 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 exit bashmator shell delete --help usage: 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 exit bashmator library --help usage: 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/library bashmator library add --help usage: 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 exit bashmator library delete --help usage: 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 exit bashmator library scan --help usage: 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 exit bashmator library use --help usage: 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. Ниже представлены примеры команд добавления некоторых других оболочек, интерпритаторов и программ:

Linux

bashmator 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: vinzekatze

description

Содержит общую информацию о работе скрипта, которая будет выведена при вызове помощи use <script name> -h или use <script name> --help.

Для большего удобства рекомендуется использовать |-. Пример:

description: |-
  Набор однострочников для получение базовой DNS информации

tags

Содержит список тегов, по которым можно будет найти скрипт с помощью команды search. Пример:

tags:
  - 53
  - dns
  - recon

install

Содержит информацию о ПО, которое необходимо установить для правильной работы скрипта. Данная информация будет отображена при вызове скрипта с помощью команды use -i <script name>.

Если есть возможность, рекомендуется писать сразу последовательность команд для установки, либо явно указывать, что установка чего-либо не требуется. Пример:

install: |-
  sudo apt update -y && sudo apt install dnsrecon -y

arguments

Содержит имена аргументов и их параметры. На основе заданных тут данных bashmator создает CLI для скрипта.

Рекомендуется использовать полные названия для позиционных аргументов, и однобуквенные для опций.

replacer по умолчанию: #[ARGUMENT NAME]#

Общий вид:

arguments:
  n:
    default: 42
    metavar: NUM
    regex: \d+
  arg:
    replacer: __B__
    multiple: true
    description: bla bla bla
    

Ключи аргументов:

default Определяет значение аргумента по умолчанию, либо список возможных значений. Если default пуст, либо отсутствует, аргумент будет обязательным. Если default содержит строковое или числовое значение, то аргумент будет опцией, которая по умолчанию будет подставлять указанное значение. Пример: a: default: 53 Если default - список из одного пустого значения, то аргумент будет опцией с пустым значением по умолчанию. Пример: a: default: - Если default содержит список из двух элементов, то аргумент будет флагом, подставляющим первое значение когда отсутствует в команде, а второе - когда присутствует. Пример: a: default: - https:// - http:// Если default содержит список из более чем трех элементов, аргумент сможет принимать только значения из списка. Если при этом первый элемент пуст, то аргумент будет обязательным, если же нет - первое значение из списка будет использоваться по умолчанию. Пример: arg: default: - - one - two description Содержит описание назначения аргумента, которое будет выведено при вызове помощи use <script name> -h или use <script name> --help. Пример: arg: description: очень важный аргумент metavar Косметический ключ, позволяющий задать свое метазначение для опций. На позиционные аргументы не влияет. Пример: arg: default: 42 metavar: MY_METAVAR Отображение: usage: test [--arg MY_METAVAR] [-h] options: --arg MY_METAVAR (default: '42') -h, --help show this help message and exit multiple Определяет, может ли аргумент принимать множественные значения, или нет. По умолчанию false. Пример: arg: multiple: true replacer Содержит строку, котороя будет заменятья в коде скрипта (ключ script) на значение аргумента. Не самое элегантное решение, но позволяет творить интересные трюки в комбинации с mode: format. Реплейсеры в коде скрипта заменяются в том порядке, в каком описаны ключи в arguments. После аргументов в код подставляются значения file_[NUMBER], если они есть. Если ключ отсутвует либо пуст, то реплейсер принимает значение #[ARGUMENT NAME]# Пример реплейсеров и скрипта: arguments: arg: replacer: -+PLACEHOLDER+- script: >- cat -+PLACEHOLDER+- | ncat 127.0.0.1 9090 regex Позволяет задать регулярное выражение, с помощью которого будут проверяться значения аргумента. Не прошедие проверку значения будут вызывать ошибку и не позволять запустить скрипт. Для проверки используется функция 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# is ok' Реакция скрипта на ввод: $ 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:
    - arg2
  replace:
    arg3:
      v1: value1
      v2: value2
  loop: arg1
  format: 
    arg2: '{0!r}'
  join:
    arg2: ','
    arg3: ';'
  pformat:
    arg2: ' [ {} ] '

Ключи mode:

readfile Содержит список имен аргументов, которые будут интерпритированы как имена файлов. Данные файлы будут читаться построчно, а считанные строки будут подставляться в скрипт на место реплейсера. Если файла не существует, то будет подставлено входящиее значение аргумента. Пример: shell: bash arguments: arg1: description: test mode: readfile: - arg1 script: >- echo #arg1# Содержимое файла some_file.txt: one two three Если запустить скрипт с аргументом ./some_file.txt, то для исполнения будет сформирован следующий код: echo one two three replace Подзволяет заменять значения аргументов. Содержит в себе имена аргументов в качестве ключей, которые в свою очередь содержат замены в виде ключ:значение. Пример: shell: bash arguments: arg1: default: - A - B - C mode: replace: arg1: A: One B: Two script: >- echo #arg1# В данном примере, когда на вход скрпта в аргумент --arg1 будет подаваться значение A, в скрипт будет подставлено значение One, а когда B - Two. Значение C заменено не будет и попадет в скрипт напрямую. loop Если содержит имя множественного аргумента (multiply: true), то скрипт будет запускаться отдельно для каждого его значения. По умолчанию этого не происходит. Пример: shell: bash arguments: arg1: multiple: true mode: loop: arg1 script: >- echo -n #arg1#; echo ' end' Результат выполнения скрипта c аргументами 1 2 3 4 5: 1 end 2 end 3 end 4 end 5 end format Содержит имена аргументов в качестве ключей и шаблоны python функции .format() в качестве значений. Если значение аргумента пусто, то форматирование не происходит и соответсвующий реплейсер удаляется из скрипта. Для множественных аргументов форматирование производится для каждого из значений отдельно. Операция join всегда происходит после. Обычно этот ключ применяется для правильной подстановки неоднозначных значений с использованием шаблона {0!r}, однако в комбинации с пустыми по умолчанию аргументами может позволить опционально вставлять в скрипт дополнительные куски. Пример: shell: bash arguments: arg1: default: - arg2: multiple: true mode: 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,val4 pformat Тоже что и format, но отрабатывает после всех других модов. Полезен при обработке множественных аргументов без режима loop, позволяя дополнительно форматировать собранную с помощью format и join строку перед вставкой в код скрипта.

shell

В данном ключе указывается короткое имя оболочки, используемой для запуска скрипта, либо путь до неё.

В целях улучшения совместимости рекомендуется добавлять оболочки в bashmator с помощью bashmator shell add, а в ключе shell указывать их короткие имена.

Данный ключ обязателен, если отсутствуют ключи item_[NUMBER], либо для каждого из них не заданы shell отдельно.

Пример:

shell: bash

Это тоже сработает, но так делать не рекомендуется:

shell: /usr/bin/bash

script

Содержит непосредственно код скрипта, который будет исполняться. Не забудьте вставить реплейсеры аргументов!

Чтобы записывать многострочные скрипты используйте |-. Чтобы записать однострочник, но в коде использовать перенос строки, используйте >-

Пример 1:

script: |-
  ls -la
  rm -r ./

Пример 2:

script: >-
  ls -la;
  rm -r ./

file_[NUMBER]

Используется для подстановки полных путей файлов из директории files библиотеки.

replacer по умолчанию: #file_[NUMBER]#

Общий вид:

file_1:
  description: My Wordlist
  path: dicts/my_wordlist.txt
file_2:
  description: My Big Script
  path: scripts/big_script.sh
  replacer: __BIG_SCRIPT__
  quote:
    - '"'
    - '\'

Ключи file_[NUMBER]:

path ⚠️ Обязательный ключ Содержит путь до файла в библиотеке относительно директории files. Используйте / для перехода в директорию независимо от системы (windows, linux). Пример: file_1: path: lorem/lorem.txt Так же можно обращаться к файлам по полному пути и использовать возвраты в родительскую директорию, но этого делать не рекомендуется. Скорее всего я закрою эту возможность спустя какое-то время, так как это больше баг, чем фитча 🥲. replacer Работает аналогично ключу replacer для arguments, но не подвергается форматированию. description Содержит краткое описание файла, которое будет выведено при вызове помощи use <script name> -h или use <script name> --help. quote При наличии использует первый символ из списка для заковычивания пути, а второй - для экранирования аналогичного символа, если он в изначальном пути содержится. Пример: file_1: path: "lorem folder/lorem'.txt" quote: - "'" - '\' При выполнении подставит следующую строку: '/<library path>/lorem folder/lorem\'.txt'

item_[NUMBER]

Используется для добавления дополнительных скриптов в один модуль. Это удобно, когда разные скрипты принимают на вход одни и те же аргументы и объеденены общим смыслом.

Если существуют item, то в CLI добавляется опция --item, которая позволяет вызывать подскрипты по номеру. Для массового запуска можно использовать последовательности: --item 1,2,4-6.

Если вместе с item существует основной script, то ему будет присвоен номер 0. Запускаться по умолчанию будет только он.

Общий вид:

item_1:
  description: script 1
  shell: python3
  script: |-
    print(1+2)
item_2:
  description: script 2
  mode:
    loop: arg1
  script: 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

$ bashmator use examples/args/simple -h
usage: examples/args/simple [-h] arg

Example of a simple required argument

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

positional arguments:
  arg         random string

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

Shell:   bash 
Author:  demo 
Tags:    help, manual, arguments      

Запуск скрипта с включенной опцией логирования

$ bashmator use -o example.log examples/args/simple blablabla
Input: blablabla

Содержимое записанного файла example.log

$ cat example.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 linux:

• ktz-autokali
• toolscape by Kraus17th

Тестирование WiFi для kali linux на Raspberry Pi 4:

• wless-gun