doc: create initial documentation with mkdocs (#177)

* doc: create initial documentation with mkdocs

- add intro page
- add setup page
- add configuration page
- add extension and faqs

* fix: update docs to remove redundancy

- update logger in extension.md
- remove redundant stuff in README and add readthedocs link
- update FAQs

Author: furusiyya

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation with Mkdocs
+mkdocs:
+   configuration: mkdocs.yml

README.md

@@ -2,41 +2,13 @@
 ![Tests](https://github.com/mushorg/glutton/actions/workflows/workflow.yml/badge.svg)
 [![GoDoc](https://godoc.org/github.com/mushorg/glutton?status.svg)](https://godoc.org/github.com/mushorg/glutton)
 
-Setup `go 1.21`. 
+Glutton is a protocol-agnostic, low-interaction honeypot that intercepts network traffic and logs interactions to help analyze malicious activities. It's built using Golang and leverages iptables and TPROXY to redirect all traffic to specific protocol handlers.
 
-Install required system packages:
+## Documentation
+For more details, please read the [documentation](https://go-glutton.readthedocs.io/en/latest/), which provides the following sections:
 
-Debian:
-```
-apt-get install gcc libpcap-dev iptables
-```
-
-Arch:
-```
-pacman -S gcc libpcap iptables
-```
-
-Fedora:
-```
-sudo dnf install gcc libpcap-devel iptables
-```
-
-Build glutton:
-```
-make build
-```
-
-To run/test glutton:
-```
-sudo bin/server
-```
-
-To get this to work on WSL, use this kernel: https://github.com/Locietta/xanmod-kernel-WSL2
-
-### Setting up the Dev Container environment with VS Code
-
-Since this project requires a Linux environment to build and run, you need to use a Docker container on other operating systems. For development, we recommend using the Dev Container Extension for VS Code.
-
-First, install the Dev Container extension. To learn more about setting up and using dev containers, check out the following resources:  
-- [Install Dev Container](https://code.visualstudio.com/docs/devcontainers/containers)  
-- [Learn More](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+* [Introduction](https://go-glutton.readthedocs.io/en/latest/)
+* [Setup](https://go-glutton.readthedocs.io/en/latest/setup/)
+* [Configuration](https://go-glutton.readthedocs.io/en/latest/configuration/)
+* [Extension](https://go-glutton.readthedocs.io/en/latest/extension/)
+* [FAQs](https://go-glutton.readthedocs.io/en/latest/faq/)

docs/configuration.md

@@ -0,0 +1,96 @@
+# Configuration
+
+Glutton’s behavior is controlled by several configuration files written in YAML (and JSON for schema validation). This page details the available configuration options, how they’re loaded, and best practices for customizing your setup. 
+
+## Configuration Files
+
+### config/config.yaml
+
+This file holds the core settings for Glutton. Key configuration options include:
+
+- **ports:** Defines the network ports used for traffic interception.
+  - **tcp:** The TCP port for intercepted connections (default: `5000`).
+  - **udp:** The UDP port for intercepted packets (default: `5001`).
+  - **ssh:** Typically excluded from redirection to avoid interfering with SSH (default: `22`).
+- **interface:** The network interface Glutton listens on (default: `eth0`).
+- **max_tcp_payload:** Maximum TCP payload size in bytes (default: `4096`).
+- **conn_timeout:** The connection timeout duration in seconds (default: `45`).
+- **confpath:** The directory path where the configuration file resides.
+- **producers:** 
+    - **enabled**: Boolean flag to enable or disable logging/producer functionality.
+    - **http:** HTTP producer for sending logs to a remote endpoint, like [Ochi](https://github.com/honeynet/ochi).
+    - **hpfeeds:** [HPFeeds](https://github.com/hpfeeds/hpfeeds) producer for sharing data with other security tools.
+- **addresses:** A list of additional public IP addresses for traffic handling.
+
+Example configuration:
+
+```yaml
+# config/config.yaml
+
+ports:
+  tcp: 5000
+  udp: 5001
+  ssh: 22
+
+rules_path: config/rules.yaml
+
+addresses: ["1.2.3.4"]
+
+interface: eth0
+
+producers:
+  enabled: true # enables producers
+  http:
+    enabled: true # enables http producer
+    # Connect with Ochi here or other remote log aggregation servers 
+    remote: http://localhost:3000/publish?token=token 
+  hpfeeds:
+    enabled: false # disables HPFeeds
+    host: 172.26.0.2
+    port: 20000
+    # HPFeeds specific details go here
+    ident: ident
+    auth: auth
+    channel: test
+
+conn_timeout: 45
+max_tcp_payload: 4096
+```
+
+### config/rules.yaml
+
+This file defines the rules that Glutton uses to determine which protocol handler should process incoming traffic.
+
+Key elements include:
+
+- **type**: `conn_handler` to pass off to the appropriate protocol handler or `drop` to ignore packets.
+- **target**: Indicates the protocol handler (e.g., "http", "ftp") to be used.
+- **match**: Define criteria such as source IP ranges or destination ports to match incoming traffic, according to [BPF syntax](https://biot.com/capstats/bpf.html).
+
+Example rule:
+
+```yaml
+# config/rules.yaml
+
+rules:
+  - name: Telnet filter
+    match: tcp dst port 23 or port 2323 or port 23231
+    type: conn_handler # will find the appropriate target protocol handler
+    target: telnet
+  - match: tcp dst port 6969
+    type: drop # drops any matching packets
+    target: bittorrent
+```
+
+## Configuration Loading Process
+Glutton uses the [Viper](https://github.com/spf13/viper) library to load configuration settings. The process works as follows:
+
+- **Default Settings**: Glutton initializes with default values for critical parameters.
+- **File-based Overrides**: Viper looks for `config.yaml` in the directory specified by confpath. If found, the settings from the file override the defaults.
+- **Additional Sources**: Environment variables or command-line flags can further override file-based configurations, allowing for flexible deployments.
+
+## Best Practices
+
+- **Backup Your Files**: Always save a backup of your configuration files before making changes.
+- **Validate Configurations**: Use YAML validators and the provided JSON schema to ensure your configuration is error-free.
+- **Test Changes**: After modifying your configuration, restart Glutton and review the logs to confirm that your changes have been applied as expected.

docs/extension.md

@@ -0,0 +1,65 @@
+# Extension
+
+Glutton is built to be easily extensible. Developers can add new protocol handlers or modify existing behavior to suit custom requirements.
+
+## Adding a New Protocol Handler
+
+### Create a New Module
+
+   - Add your new protocol handler in the appropriate subdirectory under `protocols/` (e.g., `protocols/tcp` or `protocols/udp`).
+   - Implement the handler function conforming to the expected signature:
+     - For TCP: `func(context.Context, net.Conn, connection.Metadata, logger interfaces.Logger, h interfaces.Honeypot) error`
+     - For UDP: `func(context.Context, *net.UDPAddr, *net.UDPAddr, []byte, connection.Metadata) error`
+   
+   For example:
+
+
+            // protocols/tcp/new_protocol.go
+
+            package tcp
+
+            import (
+               "context"
+               "net"
+               
+               "github.com/mushorg/glutton/connection"
+               "github.com/mushorg/glutton/protocols/interfaces"
+            )
+
+            // HandleNewProtocol handles incoming connections.
+            func HandleNewProtocol(ctx context.Context, conn net.Conn, md connection.Metadata, logger interfaces.Logger, h interfaces.Honeypot) error {
+               // Log the connection for demonstration purposes.
+               logger.Info("Received NewProtocol connection from %s", conn.RemoteAddr().String())
+               // Here you could add protocol-specific handling logic.
+               // For now, simply close the connection.
+               return conn.Close()
+            }
+
+
+### Register the Handler
+   - Modify the mapping function (e.g., `protocols.MapTCPProtocolHandlers` or `protocols.MapUDPProtocolHandlers` in `protocols/protocols.go`) to include your new handler.
+   - Update configuration or rules (in `config/rules.yaml` or `rules/rules.yaml`) if needed to route specific traffic to your handler.
+
+For example:
+
+            func MapTCPProtocolHandlers(log interfaces.Logger, h interfaces.Honeypot) map[string]TCPHandlerFunc {
+               protocolHandlers := map[string]TCPHandlerFunc{}
+               protocolHandlers["smtp"] = func(ctx context.Context, conn net.Conn, md connection.Metadata) error {
+                  return tcp.HandleSMTP(ctx, conn, md, log, h)
+               }
+               ...
+               protocolHandlers["new"] = func(ctx context.Context, conn net.Conn, md connection.Metadata) error {
+                  return tcp.HandleNewProtocol(ctx, conn, md, log, h)
+               }
+               ...
+            }
+
+3. **Test Your Extension:**
+      - Write tests similar to those in `protocols/protocols_test.go` to verify your new handler’s functionality.
+      - Use `go test` to ensure that your changes do not break existing functionality.
+
+## Customizing Logging and Rules
+
+- **Logging:** The logging mechanism is provided by the Producer (located in `producer/`). You can modify or extend it to suit your logging infrastructure.
+- **Rules Engine:** The rules engine (found in `rules/`) can be extended to support additional matching criteria or custom rule types.
+

docs/faq.md

@@ -0,0 +1,21 @@
+# Frequently Asked Questions
+
+### Q: What is Glutton?
+**A:** Glutton is a protocol-agnostic honeypot that intercepts network traffic, applies customizable rules, and logs interactions to help analyze malicious activities.
+
+### Q: Which protocols does Glutton support?
+**A:** Out of the box, Glutton supports multiple protocols via its TCP and UDP handlers. The repository includes handlers for protocols such as HTTP, FTP, SMTP, Telnet, MQTT, and more. You can extend support to additional protocols as needed.
+
+### Q: How do I add a new protocol or extend existing functionality?
+**A:** You can add a new protocol handler by implementing the appropriate interface in the `protocols/` directory and registering your handler in the corresponding mapping function. See the [Extension](extension.md) section for detailed instructions.
+
+### Q: How do I configure Glutton?
+**A:** Configuration is managed through YAML files:
+
+- **config/config.yaml:** General settings such as port numbers and interface names.
+- **config/rules.yaml:** Defines rules for matching and processing network traffic.
+
+See the [Configuration](configuration.md) section for detailed instructions.
+
+### Q: What are the system prerequisites?
+**A:** Glutton requires a Linux system, so if you're using a different OS, you'll have to use Docker to set it up. Specific installation commands are provided in the [Setup](setup.md) section. 

docs/index.md

@@ -0,0 +1,13 @@
+# Introduction
+
+Glutton is a protocol-agnostic honeypot designed to emulate various network services and protocols. It is built in Go and aims to capture and analyze malicious network activity by intercepting connections and logging detailed interaction data. Glutton is highly configurable, allowing users to define custom rules and extend its functionality by adding new protocol handlers.
+
+Key features include:
+
+- **Protocol Agnostic:** Supports TCP and UDP traffic across a variety of protocols.
+- **Rule-Based Processing:** Uses configurable rules to determine how incoming connections are handled.
+- **Extensibility:** Easily extend the tool by adding new protocol handlers.
+- **Logging and Analysis:** Captures connection metadata and payloads for further analysis.
+
+This documentation will guide you through the installation, deployment, understanding its network interactions, extending its functionality, and addressing common questions.
+

docs/setup.md

@@ -0,0 +1,106 @@
+# Setup
+
+Follow these steps to install Glutton on your system.
+
+## Environment Requirements
+
+
+- **Linux Required:** Glutton must be built and run on a Linux system.
+- **Non-Linux Users:** For Windows or macOS, use Docker or the VSCode Dev Container Extension.
+- **WSL Users:** When using WOS, we recommend running glutton with the [xanmod-kernel-WSL2](https://github.com/Locietta/xanmod-kernel-WSL2)
+- For setting up the development environment using VS Code Dev Containers, refer to:
+    - [Install Dev Container](https://code.visualstudio.com/docs/devcontainers/containers)  
+    - [Learn More](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+## Prerequisites
+
+Ensure you have [Go](https://go.dev/dl/) installed (recommended version: **Go 1.21** or later). In addition, you will need system packages for building and running Glutton:
+
+### Debian/Ubuntu
+
+```bash
+sudo apt-get update
+sudo apt-get install gcc libpcap-dev iptables
+```
+
+### Arch Linux
+```bash
+sudo pacman -S gcc libpcap iptables
+```
+
+### Fedora
+```bash
+sudo dnf install gcc libpcap-devel iptables
+```
+
+## Building Glutton
+
+Clone the repository and build the project:
+
+```bash
+git clone https://github.com/mushorg/glutton.git
+cd glutton
+make build
+```
+
+This will compile the project and place the server binary in the `bin/` directory.
+
+## Testing the Installation
+
+```bash
+bin/server --version
+```
+Replace `<network_interface>` (e.g., `eth0`) with the interface you want to monitor. You should see output similar to:
+
+```bash
+  _____ _       _   _
+ / ____| |     | | | |
+| |  __| |_   _| |_| |_ ___  _ __
+| | |_ | | | | | __| __/ _ \| '_ \
+| |__| | | |_| | |_| || (_) | | | |
+ \_____|_|\__,_|\__|\__\___/|_| |_|
+
+	
+glutton version v1.0.1+d2503ba 2025-02-21T05:48:07+00:00
+```
+
+## Usage
+
+Glutton can be configured using several command-line flags:
+
+- **--interface, -i**: `string` - Specifies the network interface (default: `eth0`)
+- **--ssh, -s**: `int` - If set, it overrides the default SSH port
+- **--logpath, -l**: `string` - Sets the file path for logging (default: `/dev/null`)
+- **--confpath, -c**: `string` - Defines the path to the configuration directory (default: `config/`)
+- **--debug, -d**: `bool` - Enables debug mode (default: `false`)
+- **--version**: `bool` - Prints the version and exits
+- **--var-dir**: `string` - Sets the directory for variable data storage (default: `/var/lib/glutton`)
+
+For example, to run Glutton with a custom interface and enable debug mode, you might use the following command:
+
+```bash
+bin/server --interface <network_interface> --debug
+```
+
+Replace `<network_interface>` (e.g., `eth0`) with the interface you want to monitor. The command starts the Glutton server, which sets up TCP/UDP listeners and applies iptables rules for transparent proxying.
+
+**Configuration:** Before deployment, ensure your configuration files, in the `config/` folder by default, are properly set up. For detailed instructions, refer to the [Configuration](configuration.md) page.
+
+## Docker
+
+To deploy using Docker:
+
+1. Build the Docker image:
+   
+    ```
+    docker build -t glutton .
+    ```
+
+2. Run the Container:
+   
+    ```
+    docker run --rm --cap-add=NET_ADMIN -it glutton
+    ```
+
+The Docker container is preconfigured with the necessary dependencies (iptables, libpcap, etc.) and copies the configuration and rules files into the container.
+

mkdocs.yml

@@ -0,0 +1,11 @@
+site_name: Glutton Documentation
+version: 1.0
+nav:
+  - Introduction: index.md
+  - Setup: setup.md
+  - Configuration: configuration.md
+  - Extension: extension.md
+  - FAQs: faq.md
+theme:
+  name: readthedocs
+