Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Signed-off-by: Ricardo Yaben <32867697+RicYaben@users.noreply.github.com>
  • Loading branch information
RicYaben authored Mar 20, 2023
1 parent b2a286f commit 51e3c55
Showing 1 changed file with 15 additions and 1 deletion.
16 changes: 15 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
</div>
</div>

<p align="justify">
RIoTPot is a hybrid interaction honeypot, primarily focused on the emulation IoT and OT protocols, although, it is also capable of emulating other services.
In essence, RIoTPot acts as a proxy service for other honeypots included in the system.
Therefore, you can run any honeypot and other services alongside RIoTPot.
Expand All @@ -29,6 +30,7 @@ In addition, there is an UI web-application that you can use to manage your rout
The honeypot comes with multiple low-interaction services ready to use.
Since these services are written as [plugins](https://pkg.go.dev/plugin), they are only supported on Linux; however, you can start RIoTPot without them.
The following table contains the list of services included in RIoTPot by defaul, their internal port, and proxy port.
</p>

<div align="center">

Expand All @@ -53,12 +55,14 @@ The following table contains the list of services included in RIoTPot by defaul,
## 1. Architecture

<p align="justify">
The RIoTPot architecture is based on proxy connections to internal and surrounding (or external) services (e.g., honeypots, full-services, containers, remote hosts, etc.).
For this, the honeypot manages a number of user-defined `proxies` that relays connections between services and RIoTPot [^proxies].
This way, RIoTPot can decide how and where to route incomming attacks.
The logic used to determine how to handle the incomming attack is implemented in the form of `middlewares` [^middlewares].
To manage services, middlewares and proxies, RIoTPot ships with a REST API [^api] and a webapp UI [^ui] out-of-the-box.
The UI can be accessed through your browser at `localhost:2022` and you can fiddle with API endpoints at `localhost:2022/api/swagger` showing a [Swagger](https://swagger.io/) interface.
</p>

[^proxies]: Internal and surrounding services are not accessible through the Internet.
Internal services are integrated and only accessible to RIoTPot.
Expand All @@ -74,7 +78,9 @@ The UI can be accessed through your browser at `localhost:2022` and you can fidd

[^ui]: Although the Web interface can be used as a separate component, it is embeded with the RIoTPot binary.

<p align="justify">
**Figure 1** shows the RIoTPot architecture, including the two main applications that constitute RIoTPot (RIoTPot itself, and RIoTPot UI) and their components, and a section to enclose external (or adjacent) services.
</p>

<div align="center" style="margin: 2em 0">
<div style="max-width: 60%; text-align: justify; display: flex; flex-direction: column;">
Expand All @@ -85,30 +91,36 @@ The UI can be accessed through your browser at `localhost:2022` and you can fidd
</div>
</div>

<p align="justify">
RIoTPot is written in [Golang](https://go.dev/)[^os].
Each RIoTPot instance exposes registered proxies (based on their port) on demand.
To serve a proxy, it **must** have a binded service and the proxy port **must** be available (currently, RIoTPot does not accept multiple services running in the same port).
When a proxy has been binded and served, attackers will be able to send messages to RIoTPot on that port, relying the messages to the binded service and back to the attacker[^reversed].
<p>

[^os]: While the base application is interoperable, internal services (plugins) can only be used in [Linux, FreeBSD and macOS environments](https://pkg.go.dev/plugin).
We plan to overcome this limitation by replacing plugins with micro-services communicating through [gRPC](https://grpc.io/).

[^reversed]: For ethical and security reasons, RIoTPot does not allow unsolicited requests to the outside, i.e., reversed shells and the like are not allowed.

<p align="justify">
For ease of access, multiple instances of RIoTPot can be managed from the RIoTPot UI webapp.
In addition to managing the proxies registered in each instance, the UI allows you to create, use and edit `profiles`.
Each profile contains a number of proxies named after protocols or other services making a RIoTPot instance resemble a real-life devices (e.g. a home assistant).
In few words, profiles speed up the process of setting up and provision a RIoTPot instance with specific configurations.
The UI is written using the React fonrt-end JavaScript library (we use Typescript for this project) and [Recoil](https://recoiljs.org/) state management library.
Since RIoTPot is rather small, for the moment, it does not use a database.
</p>

## 2. How to use RIoTPot

<p align="justify">
Running RIoTPot is relatively simple.
Overall, you have three options.
**The first** is to download a RIoTPot release; you can either choose to download the latest release, or previous one.
**The second option** is to build the project yourself.
**The last option** is to use the source code to create a Docker container with RIoTPot and some additional applications to enhance the honeypot.
</p>

<details open>
<summary><b>Using a Release Version</b></summary>
Expand Down Expand Up @@ -193,13 +205,15 @@ It is important to keep the internal folder structure for RIoTPot to work as int
</details>
</blockquote>

Some of main the advantages of using this setup are the additional security features with minimal changes to the container configuration and the containers themselves.
<p align="justify">
The main advantages of using this setup are the additional security features with minimal changes to the container configuration and the containers themselves.
For example, we can define separated virtual private networks and overlay networks to hide, sandbox and encapsule RIoTPot and other adjacent services.
In addition, containers allow us to bind services using their docker addres name rather than their IP, which is very convenient.
Lastly, we can spawn and stop separated containers on demand without affecting other services.

On the other hand, virtualisation is arguably more demanding than usign applications on bare-metal.
While a single instance of RIoTPot is relatively lightweight, it is important to consider the shortcomings introduced by virtualisation and hardware emulation (e.g., reponse delays).
</p>

> **_Warning_:** Technically speaking, a dedicated attacker may realize that RIoTPot is in fact a honeypot by analysing and comparing the response-time delays introduced by virtualisation to real servers (!!). While this type of honeypot fingerprinting has been studied before, the results for common Internet services are still inconclussive (e.g., HTTP, Telnet and SSH), due to the commoditization of cloud hosting services using virtual machines and detailed server configurations.

Expand Down

0 comments on commit 51e3c55

Please sign in to comment.