aau-network-security/riotpotХоніпот для IoT и операционных технологий
| :loudspeaker: ВНИМАНИЕ!!! |
|:---------------------------|
| Этот репозиторий был перемещён в [проект Honeynet](https://github.com/honeynet/riotpot) :) |
# RIoTPot
<!-- markdownlint-disable MD033 -->
<div align="center" style="box-shadow: 0px 4px 4px rgba(0, 0, 0, 0.25); background-color: #EDF2F4; border-radius: 4px; margin: 2em 0;">
<img src="https://assets.kitploit.com/production/public/readmes/4899/f848f9e56cc0e660137556ca8ee44ff935c577dd24352435beb10c364dbfa2f5.png" height="100px;" style="margin: 1em 0; padding: 1em;">
<div>
<!-- Workflow status -->
<a href="https://github.com/aau-network-security/RIoTPot/actions">
<img alt="GitHub Actions status" src="https://github.com/aau-network-security/RIoTPot/workflows/cyber/badge.svg">
</a>
<a href="https://pkg.go.dev/riopot">
<img src="https://pkg.go.dev/badge/riopot.svg">
</a>
<a href="https://goreportcard.com/badge/github.com/aau-network-security/RIoTPot">
<img src="https://goreportcard.com/badge/github.com/aau-network-security/RIoTPot?style=flat-square">
</a>
<a href="">
<img src="https://img.shields.io/github/release/RIoTPot/project-layout.svg?style=flat-square">
</a>
</div>
</div>
RIoTPot — это гибридный honeypot взаимодействия, в первую очередь ориентированный на эмуляцию протоколов IoT и OT, хотя он также способен эмулировать другие сервисы. По сути, RIoTPot действует как прокси-сервис для других honeypot-ов, включённых в систему. Поэтому вы можете запускать любые honeypot-ы и другие сервисы вместе с RIoTPot. Кроме того, есть веб-приложение с пользовательским интерфейсом, которое вы можете использовать для управления маршрутизацией.
Honeypot поставляется с несколькими низкоинтерактивными сервисами, готовыми к использованию. Поскольку эти сервисы написаны как [плагины](https://pkg.go.dev/plugin), они поддерживаются только на Linux; однако вы можете запустить RIoTPot без них. В следующей таблице приведён список сервисов, включённых в RIoTPot по умолчанию, их внутренние порты и прокси-порты.
<div align="center">
| Сервис | Внутренний порт | Прокси-порт |
| ------- | ------------- | ---------- |
| Echo | 20007 | 7 |
| SSH | 20022 | 22 |
| Telnet | 20023 | 23 |
| HTTP | 28080 | 80 |
| Modbus | 20502 | 502 |
| MQTT | 21883 | 1883 |
| CoAP | 25683 | 5683 |
</div>
> ## Содержание
>
> - [RIoTPoT](#riotpot)
> - [1. Architecture](#1-architecture)
> - [2. How to use RIoTPot](#2-how-to-use-riotpot)
> - [3. Commands](#3-commands)
## 1. Architecture
Архитектура RIoTPot основана на прокси-соединениях с внутренними и окружающими (или внешними) сервисами (например, honeypot-ами, полноценными сервисами, контейнерами, удалёнными хостами и т.д.). Для этого honeypot управляет рядом определённых пользователем `прокси`, которые ретранслируют соединения между сервисами и RIoTPot [^proxies]. Таким образом, RIoTPot может решать, как и куда направлять входящие атаки. Логика, используемая для определения того, как обрабатывать входящую атаку, реализована в виде `промежуточных слоёв` [^middlewares]. Для управления сервисами, промежуточными слоями и прокси RIoTPot поставляется с REST API [^api] и веб-интерфейсом [^ui] «из коробки». Веб-интерфейс доступен через браузер по адресу `localhost:2022`, а с конечными точками API можно ознакомиться по адресу `localhost:2022/api/swagger`, где отображается интерфейс [Swagger](https://swagger.io/).
[^proxies]: Внутренние и окружающие сервисы недоступны через Интернет.
Внутренние сервисы интегрированы и доступны только для RIoTPot.
Эти сервисы загружаются при запуске и не могут быть удалены, но их можно остановить.
Окружающие сервисы **должны** находиться в той же сети, что и RIoTPot.
Внешние сервисы **должны** заносить RIoTPot в белый список **только**.
[^middlewares]: Промежуточные слои в настоящее время находятся в разработке.
[^api]: API RIoTPot **не должен** быть доступен из Интернета.
Независимо от этого, в настоящее время API принимает соединения только с локального хоста.
В будущем это может быть изменено путём предоставления белого списка хостов и стандартной аутентификации.
[^ui]: Хотя веб-интерфейс может использоваться как отдельный компонент, он встроен в бинарный файл RIoTPot.
**Рисунок 1** показывает архитектуру RIoTPot, включая два основных приложения, составляющих RIoTPot (сам RIoTPot и RIoTPot UI), и их компоненты, а также раздел для внешних (или смежных) сервисов.
<div align="center" style="margin: 2em 0">
<div style="max-width: 60%; text-align: justify; display: flex; flex-direction: column;">
<img src="https://assets.kitploit.com/production/public/readmes/4899/1e1d6c536610212491afb2ce713b6f78f703837315bacc8e11b4b06b5a925fdd.png">
<div>
<b>Рисунок 1.</b> Архитектура RIoTPot, включая основное приложение, внешние сервисы и веб-приложение с пользовательским интерфейсом для управления экземплярами RIoTPot.
</div>
</div>
</div>
RIoTPot написан на [Golang](https://go.dev/)[^os].
Каждый экземпляр RIoTPot предоставляет зарегистрированные прокси (на основе их порта) по требованию.
Чтобы обслуживать прокси, **должен** быть привязан сервис, и порт прокси **должен** быть доступен (в настоящее время RIoTPot не принимает несколько сервисов, работающих на одном порту).
Когда прокси привязан и обслуживается, злоумышленники смогут отправлять сообщения RIoTPot на этот порт, ретранслируя сообщения привязанному сервису и обратно атакующему[^reversed].
[^os]: Хотя базовое приложение кроссплатформенно, внутренние сервисы (плагины) могут использоваться только в средах [Linux, FreeBSD и macOS](https://pkg.go.dev/plugin).
Мы планируем преодолеть это ограничение, заменив плагины микросервисами, общающимися через [gRPC](https://grpc.io/).
[^reversed]: По этическим соображениям и соображениям безопасности RIoTPot не допускает нежелательных запросов наружу, т.е. реверс-шеллы и тому подобное запрещены.
Для удобства доступа несколькими экземплярами RIoTPot можно управлять из веб-приложения RIoTPot UI.
В дополнение к управлению прокси, зарегистрированными в каждом экземпляре, UI позволяет создавать, использовать и редактировать `профили`.
Каждый профиль содержит ряд прокси, названных в честь протоколов или других сервисов, что делает экземпляр RIoTPot похожим на реальное устройство (например, домашний помощник).
Короче говоря, профили ускоряют процесс настройки и предоставления экземпляра RIoTPot с конкретными конфигурациями.
UI написан с использованием библиотеки React для фронтенда на JavaScript (для этого проекта мы используем Typescript) и библиотеки управления состоянием [Recoil](https://recoiljs.org/).
Поскольку RIoTPot довольно мал, на данный момент он не использует базу данных.
## 2. How to use RIoTPot
Запуск RIoTPot относительно прост.
В целом у вас есть три варианта.
**Первый** — скачать релиз RIoTPot; вы можете выбрать как последний, так и предыдущий релиз.
**Второй вариант** — собрать проект самостоятельно.
**Последний вариант** — использовать исходный код для создания Docker-контейнера с RIoTPot и некоторыми дополнительными приложениями для расширения функциональности honeypot.
<details open>
<summary><b>Использование релизной версии</b></summary>
> **_Информация_:** Это руководство предназначено для пользователей без особых потребностей, которые хотят получить простой опыт «из коробки».
Каждый релиз поставляется в папке с именем `riotpot`, содержащей исполняемый бинарный файл (также) с именем `riotpot` и папку `plugins`, заполненную различными сервисами (или низкоинтерактивными honeypot-ами).
Важно сохранять внутреннюю структуру папок для правильной работы RIoTPot.
📁 riotpot
┕ riotpot
┕ 📁 plugins
---
1. Сначала скачайте релиз на ваш выбор со страницы [релизов](https://github.com/aau-network-security/riotpot/releases). Выберите тот, который нужен для вашей операционной системы (ОС).
2. Извлеките папку `riotpot`.
3. Запустите бинарный файл `riotpot`. Это запустит RIoTPot с включённым API, всеми готовыми к использованию плагинами и сервером UI.
- API и UI доступны по адресу `localhost:2022`
</details>
<details>
<summary><b>Сборка самостоятельно</b></summary>
> **_Информация_:** Это руководство предназначено для продвинутых пользователей, уверенно работающих в средах разработки.
<blockquote>
<details>
<summary><b>Требования</b></summary>
- Golang — требуется для сборки проекта
- Node — требуется для сборки UI
**Необязательно**:
- Git — используется для загрузки исходного кода
- Make — для выполнения уже подготовленных команд
</details>
</blockquote>
---
1. Загрузите исходный код RIoTPot с GitHub. Откройте консоль и введите следующую строку.
```bash
git clone [email protected]:aau-network-security/riotpot.git
```
2. Перейдите в папку, куда вы загрузили исходный код RIoTPot, и установите необходимые пакеты Node.
```bash
npm install
```
3. Если у вас установлен [Make](https://www.gnu.org/software/make/), мы включили несколько вспомогательных команд, чтобы помочь вам собрать проект. Проще говоря, вы можете выполнить две простые команды, которые соберут бинарный файл RIoTPot и плагины (и поместят их в нужную папку).
```bash
# Сборка сервера
make build-ui
# Сборка RIoTPot и плагинов
make riotpot-build
```
> **__ПРИМЕЧАНИЕ__:** UI использует [Vite](https://vitejs.dev/) для сборки проекта. Если вы предпочитаете использовать другой сборщик, возможно, вам придётся сначала внести некоторые изменения самостоятельно.
</details>
<details>
<summary><b>Docker (виртуализация)</b></summary>
> **_Информация_:** Это руководство предназначено для продвинутых пользователей, предпочитающих использовать RIoTPot в виртуальной среде.
<blockquote>
<details>
<summary><b>Требования</b></summary>
- Docker — используется для создания образа экземпляра RIoTPot и сервера UI.
- Docker-compose — используется для создания единого контейнера с экземпляром RIoTPot, UI и другими приложениями и сервисами.
</details>
</blockquote>
Основные преимущества использования такой настройки — дополнительные функции безопасности с минимальными изменениями конфигурации контейнера и самих контейнеров.
Например, мы можем определить отдельные виртуальные частные сети и наложенные сети для скрытия, изоляции и инкапсуляции RIoTPot и других смежных сервисов.
Кроме того, контейнеры позволяют нам привязывать сервисы, используя их имена Docker-адресов, а не IP, что очень удобно.
Наконец, мы можем по требованию запускать и останавливать отдельные контейнеры, не затрагивая другие сервисы.
С другой стороны, виртуализация, вероятно, более требовательна, чем использование приложений на «голом железе».
Хотя один экземпляр RIoTPot относительно лёгок, важно учитывать недостатки, связанные с виртуализацией и эмуляцией оборудования (например, задержки отклика).
> **_Предупреждение_:** Технически говоря, целеустремлённый злоумышленник может понять, что RIoTPot на самом деле является honeypot, анализируя и сравнивая задержки отклика, связанные с виртуализацией, с реальными серверами (!!). Хотя такой вид идентификации honeypot ранее изучался, результаты для распространённых интернет-сервисов (например, HTTP, Telnet и SSH) всё ещё не являются окончательными из-за универсальности услуг облачного хостинга, использующих виртуальные машины и детальные конфигурации серверов.
Файл `docker-compose` включает дополнительные сервисы для расширения функциональности RIoTPot.
В следующей таблице приведён список сервисов и приложений, упакованных в этот контейнер.
<blockquote>
<details>
<summary><b>Сервисы</b></summary>
<div align="center">
| Сервис | Изображение | Порт | Детали |
| ------- | ---------------------- | ---- | ------------------------------------------ |
| MQTT | eclipse-mosquitto | 1883 | Mosquito MQTT сервер |
| HTTP | httpd | 80 | Обычный HTTP сервер |
| Modbus | oitc/modbus-server | 502 | Modbus сервер |
| OCPP | ocpp1.6-central-system | 443 | OCPP v1.6 (используется в зарядных станциях для автомобилей) |
</div>
</details>
<details>
<summary><b>Приложения</b></summary>
<div align="center">
| Приложение | Изображение | Детали |
| ----------- | --------------- | --------------------------------------------------------- |
| TCPDump | kaazing/tcpdump | Запись пакетов. Сохраняет сетевой трафик в файлах .pcap |
</div>
</details>
</blockquote>
---
Контейнер можно настроить за три простых шага:
1. Загрузите исходный код RIoTPot с GitHub. Откройте консоль и введите следующую строку.
```bash
git clone [email protected]:aau-network-security/riotpot.git
```
2. Перейдите в папку, куда вы загрузили исходный код RIoTPot.
3. При запущенном Docker: если у вас установлен Make, выполните следующую команду. В противном случае выполните команду docker-compose, используя файл docker-compose, включённый в папку `build/docker`.
- С make
```bash
# С make
make up
```
- С Docker-compose
```bash
# С docker-compose
docker-compose -p riotpot -f build/docker/docker-compose.yaml up -d --build
```
</details>
## 3. Commands
RIoTPot поставляется с флагами команд, которые влияют на то, что и как запускается.
Пример:
```bash
# Запуск RIoTPot без UI
./riotpot --ui false
```
| Флаг | Тип | По умолчанию | Описание |
| --------- | ------- | -------------------------------------- | -------------------------------------------------------- |
| debug | Boolean | false | Установить уровень журнала для отладки |
| api | Boolean | true | Запускать ли API |
| plugins | Boolean | true | Загружать ли плагины низкоинтерактивных honeypot |
| whitelist | String | http://localhost,http://localhost:3000 | Список разрешённых хостов, разделённых запятыми, для доступа к API |
| ui | Boolean | true | Запускать ли UI |