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

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

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

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

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

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

Установка

pip install --upgrade bashmator

В комадной строке станет доступен под короткими названиям 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.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 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__

Ключи 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 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

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
bshm		bshm
static		static
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

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

Установка

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

Оболочки

Создание библиотек

Создание YAML модулей

Описание ключей:

Пример работы

Доступные библиотеки

About

Releases 6

Languages

License

vinzekatze/bashmator

Folders and files

Latest commit

History

Repository files navigation

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

Установка

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

Оболочки

Создание библиотек

Создание YAML модулей

Описание ключей:

Пример работы

Доступные библиотеки

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 6

Languages