0xb00b5/0xb00b5-packmate
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Sergey
2023-04-14 00:58:44 +00:00
parent 8d48dec701
commit 872e27b926
20 changed files with 463 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

89
docs/SETUP.md Normal file
View File

@@ -0,0 +1,89 @@
## Настройка
Packmate использует настройки из файла `.env` (в той же папке, что и `docker-compose.yml`)
### Основные настройки
```dotenv
# Локальный IP сервера, на который приходит игровой трафик
PACKMATE_LOCAL_IP=10.20.1.1
# Имя пользователя для web-авторизации
PACKMATE_WEB_LOGIN=SomeUser
# Пароль для web-авторизации
PACKMATE_WEB_PASSWORD=SomeSecurePassword
```
### Режим работы
Packmate поддерживает три основных режима работы: `LIVE`, `FILE` и `VIEW`.
1. `LIVE` - это основной режим работы во время CTF. Packmate обрабатывает живой трафик и сразу выводит результаты.
2. `FILE` - обрабатывает трафик из pcap файлов. Полезен для анализа трафика с прошедших CTF, где не был запущен Packmate, или тех, где невозможно запустить его на вулнбоксе.
3. `VIEW` - Packmate не обрабатывает трафик, а только показывает уже обработанные стримы. Полезен для разборов после завершения CTF.
<details>
<summary>Настройка LIVE</summary>
Необходимо указать интерфейс, через который проходит игровой трафик.
На этом же интерфейсе должен располагаться ip, указанный в параметре `PACKMATE_LOCAL_IP`
```dotenv
# Режим работы - перехват
PACKMATE_MODE=LIVE
# Интерфейс, на котором производится перехват трафика
PACKMATE_INTERFACE=game
```
</details>
<details>
<summary>Настройка FILE</summary>
Необходимо указать название pcap файла, лежащего в папке pcaps.
После запуска в веб-интерфейсе появится кнопка, активирующая чтение файла.
Важно, чтобы к этому моменту уже были созданы сервисы и паттерны (см. раздел Использование).
```dotenv
# Режим работы - анализ файла
PACKMATE_MODE=FILE
# Название файла в папке pcaps
PACKMATE_PCAP_FILE=dump.pcap
```
</details>
<details>
<summary>Настройка VIEW</summary>
В этом режиме Packmate просто показывает уже имеющиеся данные.
```dotenv
# Режим работы - просмотр
PACKMATE_MODE=VIEW
```
</details>
### Очистка БД
На крупных CTF через какое-то время накапливается большое количество трафика. Это замедляет работу Packmate и занимает много места на диске.
Для оптимизации работы, рекомендуется включить регулярную очистку БД от старых стримов. Это будет работать только в режиме `LIVE`.
```dotenv
PACKMATE_OLD_STREAMS_CLEANUP_ENABLED=true
# Интервал удаления старых стримов (в минутах).
# Лучше ставить маленькое число, чтобы стримы удалялись маленькими кусками, и это не нагружало систему
PACKMATE_OLD_STREAMS_CLEANUP_INTERVAL=1
# Насколько старым стрим должен быть для удаления (в минутах от текущего времени)
PACKMATE_OLD_STREAMS_CLEANUP_THRESHOLD=240
```
### Дополнительные настройки
```dotenv
# Пароль от БД. Из-за того, что БД принимает подключения только с localhost, менять его необязательно, но можно, для дополнительной безопасности.
PACKMATE_DB_PASSWORD=K604YnL3G1hp2RDkCZNjGpxbyNpNHTRb
# Версия Packmate. Можно изменить, если нужно использовать другой образ из docker registry.
BUILD_TAG=latest
```
Чтобы использовать расшифровку TLS (с RSA), нужно положить соответствующий приватный ключ, который
использовался для генерации сертификата, в папку `rsa_keys`.
Файлы БД сохраняются в ./data, поэтому для обнуления базы нужно удалить эту папку.

88
docs/SETUP_EN.md Normal file
View File

@@ -0,0 +1,88 @@
## Setup
Packmate uses properties from the `.env` file (in the same directory as `docker-compose.yml`)
### Primary settings
```dotenv
# Local IP of a server on which the traffic in directed. Used to tell incoming packets from outgoing.
PACKMATE_LOCAL_IP=10.20.1.1
# Username for the web interface
PACKMATE_WEB_LOGIN=SomeUser
# Password for the web interface
PACKMATE_WEB_PASSWORD=SomeSecurePassword
```
### Modes of operation
Packmate supports 3 modes of operation: `LIVE`, `FILE` и `VIEW`.
1. `LIVE` - the usual mode during a CTF. Packmate processes live traffic and instantly displays the results.
2. `FILE` - processes traffic from pcap files. Useful to analyze traffic from past CTFs where Packmate wasn't launched, or CTFs where it's impossible to use it on the vulnbox.
3. `VIEW` - Packmate does not process any traffic, but simply shows already processed streams. Useful for post-game analyses.
<details>
<summary>LIVE setup</summary>
Set the interface through which the game traffic passes.
IP address from `PACKMATE_LOCAL_IP` should be bound to the same interface.
```dotenv
# Mode: capturing
PACKMATE_MODE=LIVE
# Interface to capture on
PACKMATE_INTERFACE=game
```
</details>
<details>
<summary>FILE setup</summary>
Set the name of the pcap file in the `pcaps` directory.
After the startup, in the web interface, you will see the button that activates the file processing.
It's important that by this moment all services and patterns are already created (see Usage).
```dotenv
# Mode: pcap file anysis
PACKMATE_MODE=FILE
# Path to pcap file in the pcaps directory
PACKMATE_PCAP_FILE=dump.pcap
```
</details>
<details>
<summary>VIEW setup</summary>
In that mode, Packmate simply shows already existing data.
```dotenv
# Mode: viewing the data
PACKMATE_MODE=VIEW
```
</details>
### Database cleanup
On large CTFsб after some time a lot of traffic will pile up. This can slow Packmate down and take a lot of drive space.
To optimize the workflow, it is recommended to enable periodical database cleanup of old streams. It will only work in the `LIVE` mode.
```dotenv
PACKMATE_OLD_STREAMS_CLEANUP_ENABLED=true
# Old streams removal interval (in minutes).
# It's better to use small numbers so the streams are removed in small chunks and don't overload the server.
PACKMATE_OLD_STREAMS_CLEANUP_INTERVAL=1
# How old the stream must be to be removed (in minutes before current time)
PACKMATE_OLD_STREAMS_CLEANUP_THRESHOLD=240
```
### Additional settings
```dotenv
# Database password. Considering it only listens on localhost, it's not mandatory to change it, but you can do it for additional security.
PACKMATE_DB_PASSWORD=K604YnL3G1hp2RDkCZNjGpxbyNpNHTRb
# Packmate version. Change it if you want to use a different version from the docker registry.
BUILD_TAG=latest
```
To use the TLS decryption, you have to put the matching private key in the `rsa_keys` directory.
Database files are being saved in `./data`, so to reset the database, you need to delete this directory.

117
docs/USAGE.md Normal file
View File

@@ -0,0 +1,117 @@
## Использование
### Настройки
При попытке зайти в web-интерфейс впервые, браузер спросит логин и пароль,
который указывался в env-файле.
При необходимости можно настроить дополнительные параметры по кнопке с шестеренками в верхнем
правом углу экрана.
<img alt="Скриншот настроек" width="400" src="../screenshots/Screenshot_Settings.png"/>
### Создание сервисов
Сначала нужно создать сервисы, находящиеся в игре. Если не сделать этого, то никакие стримы не будут сохраняться!
Для этого вызывается диалоговое окно по нажатию кнопки `+` в навбаре,
где можно указать название и порт сервиса, а также дополнительные опции.
<img alt="Скриншот окна создания сервиса" src="../screenshots/Screenshot_Service.png" width="600"/>
#### Параметры сервиса:
1. Имя
2. Порт (если сервис использует несколько портов, нужно создать по сервису на каждый порт)
3. Chunked transfer encoding: автоматически раскодировать [подобные](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#chunked_encoding) http пакеты
4. Urldecode: автоматически проводить urldecode пакетов. Стоит включать по умолчанию в http сервисах.
5. Merge adjacent packets: автоматически склеивать соседние пакеты в одном направлении. Стоит включать по умолчанию в небинарных сервисах.
6. Inflate WebSockets: автоматически разархивировать [сжатые](https://www.rfc-editor.org/rfc/rfc7692) websocket-пакеты.
7. Decrypt TLS: автоматически расшифровывать TLS-трафик (HTTPS).
Работает только с типами шифрования TLS_RSA_WITH_AES_*, и при наличии приватного ключа, который использовался в сертификате сервера (как Wireshark).
### Создание паттернов
Для удобного отлова эксплоитов в приложении существует система паттернов.
Чтобы создать паттерн, нужно открыть выпадающее меню `Patterns` и нажать кнопку `+`,
затем указать параметры паттерна и сохранить.
Важно: паттерн начнет действовать только на стримы, захваченные после его создания. Но можно использовать Lookback, чтобы проанализировать и стримы в прошлом.
<img alt="Скриншот окна создания паттерна" src="../screenshots/Screenshot_Pattern.png" width="400"/>
#### Параметры паттерна:
1. Имя: оно отображается в списке на стримах, которые содержат этот паттерн.
2. Паттерн: само содержимое паттерна. Может быть строкой, регулярным выражением или hex-строкой в зависимости от типа паттерна.
3. Действие паттерна
1. Highlight подсветит найденный паттерн. Пример: поиск флагов.
2. Ignore удалит стрим, содержащий этот паттерн.
Пример: вы запатчили сервис от определенной уязвимости и больше не хотите видеть определенный эксплоит в трафике. Можно добавить этот эксплоит как паттерн с типом IGNORE, и он больше не будет сохраняться.
4. Цвет: этим цветом будут подсвечиваться паттерны с типом Highlight
5. Метод поиска: подстрока, регулярное выражение, бинарная подстрока
6. Направление поиска: везде, только в запросах, только в ответах
7. Сервис: искать в трафике всех сервисов или в каком-то конкретном
### Начало игры
В режиме LIVE система начнет автоматически захватывать стримы и отображать их в сайдбаре.
В режиме FILE для начала обработки файла нужно нажать соответствующую кнопку в сайдбаре.
При нажатии на стрим в главном окне выводится список пакетов;
между бинарным и текстовым представлением можно переключиться по кнопке в сайдбаре.
### Обзор навбара
![Скриншот навбара](../screenshots/Screenshot_Navbar.png)
1. Заголовок
2. Счетчик SPM - Streams Per Minute, стримов в минуту
3. Счетчик PPS - Packets Per Stream, среднее количество пакетов в стриме
4. Кнопка открытия списка паттернов
5. Список сервисов. В каждом сервисе:
1. Название
2. Порт
3. Счетчик SPM сервиса - позволяет определить наиболее популярные сервисы
4. Кнопка редактирования сервиса
6. Кнопка добавления нового сервиса
7. Кнопка открытия настроек
### Обзор сайдбара
![Скриншот сайдбара](../screenshots/Screenshot_Sidebar.png)
В левой панели Packmate находятся стримы выбранного сервиса.
Отображается номер стрима, протокол, TTL, сервис, время, хэш User-Agent (для http сервисов) и найденные паттерны.
Совет: иногда на CTF забывают перезаписать TTL пакетов внутри сети. В таком случае по TTL можно отличить запросы от чекеров и от других команд.
Совет #2: по User-Agent можно отличать запросы из разных источников. К примеру, можно предположить, что на скриншоте выше запросы 4 и 5 пришли из разных источников.
Совет #3: нажимайте на звездочку, чтобы добавить интересный стрим в избранное. Этот стрим будет выделен в списке, и появится в списке избранных стримов.
#### Управление просмотром
<img alt="Панель управления" src="../screenshots/Screenshot_Sidebar_header.png" width="400"/>
1. Пауза: Остановить/возобновить показ новых стримов на экране. Не останавливает перехват стримов и показ другим пользователям! Полезно, если стримы летят слишком быстро.
2. Избранные: показать только стримы, отмеченные как избранные
3. Переключить текстовый/hexdump вид
4. Начать анализ: появляется только при запуске в режиме `FILE`
5. Промотать список стримов до самого нового
### Обзор меню паттернов
![Список паттернов](../screenshots/Screenshot_Patterns.png)
1. Кнопка добавления паттерна
2. Выбор всех стримов (убрать фильтрацию по паттерну)
3. Список паттернов. В каждой строчке:
1. Описание паттерна
2. Кнопка Lookback - позволяет применить паттерн к стримам, обработанным до создания паттерна.
3. Пауза - паттерн нельзя удалить, но можно поставить на паузу. После этого он не будет применяться к новым стримам.
Совет: создавайте отдельные паттерны для входящих и исходящих флагов. Так легче отличать чекер, кладущий флаги, от эксплоитов.
Совет #2: используйте Lookback для исследования найденных эксплоитов.
Пример: вы обнаружили, что сервис только что отдал флаг пользователю `abc123` без видимых причин.
Можно предположить, что атакующая команда создала этого пользователя и подготовила эксплоит в другом стриме.
Но в игре слишком много трафика, чтобы найти этот стрим вручную.
Тогда можно создать `SUBSTRING` паттерн со значением `abc123` и активировать Lookback на несколько минут назад.
После этого со включенным фильтром по паттерну будут отображаться только стримы, где упоминался этот пользователь.
### Горячие клавиши
Для быстрой навигации по стримам можно использовать следующие горячие клавиши:
* `Ctrl+Up` -- переместиться на один стрим выше
* `Ctrl+Down` -- переместиться на один стрим ниже
* `Ctrl+Home` -- перейти на последний стрим
* `Ctrl+End` -- перейти на первый стрим

110
docs/USAGE_EN.md Normal file
View File

@@ -0,0 +1,110 @@
## Usage
### Settings
When attempting to access the web interface for the first time, your browser will prompt for a login and password, which were specified in the env file.
If necessary, additional parameters can be configured via the gear icon in the top right corner of the screen.
<img alt="Screenshot of settings" src="../screenshots/Screenshot_Settings.png" width="400"/>
### Creating Services
First, you need to create services that are present in the game. If you don't do this, no streams will be saved!
To do this, a dialog box is called by clicking the `+` button in the navbar,
where you can specify the name and port of the service, as well as additional options.
<img alt="Screenshot of service creation window" src="../screenshots/Screenshot_Service.png" width="600"/>
#### Service Parameters:
1. Name
2. Port (if the service uses multiple ports, you need to create a Packmate service for each port)
3. Chunked transfer encoding: automatically decode [chunked](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#chunked_encoding) HTTP packets
4. Urldecode: automatically perform URL decoding of packets. Should be enabled by default for HTTP services.
5. Merge adjacent packets: automatically merge adjacent packets in the same direction. Should be enabled by default for non-binary services.
6. Inflate WebSockets: automatically decompress [compressed](https://www.rfc-editor.org/rfc/rfc7692) WebSocket packets.
7. Decrypt TLS: automatically decrypt TLS traffic (HTTPS). Only works with TLS_RSA_WITH_AES_* cipher suites and requires the private key used in the server's certificate (just like Wireshark).
### Creating Patterns
To conveniently capture exploits in the application, a pattern system exists.
To create a pattern, open the dropdown menu `Patterns` and click the `+` button,
then specify the pattern parameters and save.
Important: the pattern will only apply to streams captured after its creation. But you can use Lookback to analyze past streams.
<img alt="Screenshot of pattern creation window" src="../screenshots/Screenshot_Pattern.png" width="400"/>
#### Pattern Parameters:
1. Name: it will be displayed in the list on streams that contain this pattern.
2. Pattern: the content of the pattern itself. It can be a string, a regular expression, or a hex string depending on the pattern type.
3. Pattern ation:
1. Highlight will highlight the found pattern. Example: searching for flags.
2. Ignore will delete the stream containing this pattern.
Example: you patched a service from a certain vulnerability and no longer want to see a specific exploit in the traffic. You can add this exploit as a pattern with IGNORE type, and it will no longer be saved.
4. Color: the color with which patterns of Highlight type will be highlighted.
5. Search method: substring, regular expression, binary substring
6. Search type: everywhere, only in requests, only in responses
7. Service: search in the traffic of all services or in a specific one.
### Game Start
In LIVE mode, the system will automatically capture streams and display them in the sidebar.
In FILE mode, click the corresponding button in the sidebar to start processing a file.
When you click on a stream in the main window, a list of packets is displayed;
you can switch between binary and text representation using the button in the sidebar.
### Navbar Overview
![Navbar screenshot](../screenshots/Screenshot_Navbar.png)
1. Title
2. SPM counter - Streams Per Minute
3. PPS counter - (average number of) Packets Per Stream
4. Button to open the list of patterns
5. List of services. In each service:
1. Name
2. Port
3. SPM counter for the service - allows you to determine the most popular services
4. Service edit button
6. Button to add a new service
7. Button to open settings
### Sidebar Overview
![Sidebar screenshot](../screenshots/Screenshot_Sidebar.png)
Tip: Sometimes during CTFs, admins forget to overwrite the TTL of packets inside the network. In such cases, you can differentiate requests from checkers and other teams based on TTL.
Tip #2: User-Agent can be used to differentiate requests from different sources. For example, in the screenshot above, requests 4 and 5 may have come from different sources.
Tip #3: Click on the star icon to add an interesting stream to your favorites. This stream will be highlighted in the list and will appear in the list of favorite streams.
#### Control Panel
<img alt="Control Panel" src="../screenshots/Screenshot_Sidebar_header.png" width="400"/>
1. Pause: Stop/resume displaying new streams on the screen. It does not stop intercepting streams or showing them to other users! Useful if streams are flying by too quickly.
2. Favorites: Show only streams marked as favorites.
3. Switch text/hexdump view.
4. Start analysis: Only appears when running in `FILE` mode.
5. Scroll stream list to the newest.
### Pattern Menu Overview
![Pattern List](../screenshots/Screenshot_Patterns.png)
1. Add Pattern Button
2. Select All Streams (do not filter by pattern)
3. Pattern List. Each line contains:
1. Pattern Description
2. Lookback Button - applies the pattern to streams processed before the pattern creation.
3. Pause - pattern cannot be deleted, but can be paused. It will not be applied to new streams after pausing.
Tip: Create separate patterns for incoming and outgoing flags to easily distinguish between flag checkers and exploits.
Tip #2: Use Lookback to investigate discovered exploits.
Example: You found that the service just handed out a flag to user `abc123` without an apparent reason.
You can assume that the attacking team created this user and prepared an exploit in another stream.
But there is too much traffic in the game to manually find this stream.
Then you can create a `SUBSTRING` pattern with the value `abc123` and activate Lookback for a few minutes back.
After that, with the pattern filter enabled, only streams mentioning this user will be displayed.
### Hotkeys
Use the following hotkeys for quick navigation through streams:
* `Ctrl+Up` -- Move one stream up.
* `Ctrl+Down` -- Move one stream down.
* `Ctrl+Home` -- Go to the last stream.
* `Ctrl+End` -- Go to the first stream.