Merge pull request #1 from anmolbhatia05/master

Adding package docs, inline comments for readability, testing, client, docker examples

Dockerfile

@@ -1,4 +1,5 @@
-FROM rust:1 as build
+# This Dockerfile is used to build a socks proxy server.
+FROM rust:1.72 as build
 
 RUN rustup component add rustfmt
 
@@ -14,15 +15,15 @@ WORKDIR /socksx
 RUN cargo build --release
 
 # Define final image
-FROM ubuntu:20.04
+FROM ubuntu:22.04
 
 RUN apt-get update && apt-get install -y \
-    libssl1.1 \
+    libssl3 \
     libuv1 \
  && rm -rf /var/lib/apt/lists/*
 
 # Copy `socksx` from the build stage
 COPY --from=build /socksx/target/release/socksx .
 
 EXPOSE 1080
-ENTRYPOINT [ "./socksx" ]
+ENTRYPOINT [ "./socksx" ]

Dockerfile.counter

@@ -0,0 +1,15 @@
+# This Dockerfile is supposed to create a socks proxy server that mimics a firewall.
+# This won't build on apple silicon based macs. Try on Linux or Windows or intel based macs.
+FROM ubuntu:22.04
+
+RUN apt-get update && apt-get install -y \
+    python3 \
+    python3-pip \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install click socksx
+
+COPY ./socksx-py/examples/functions.py /functions.py
+
+EXPOSE 1080
+ENTRYPOINT [ "./functions.py" ]

Dockerfile.encrypt-decrypt

@@ -0,0 +1,30 @@
+# This Dockerfile is used to build a socks proxy server that can be used to encrypt or decrypt the data
+FROM rust:1.72 as build
+
+RUN rustup component add rustfmt
+
+RUN apt-get update && apt-get install -y \
+    cmake \
+    make \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy over relevant crates
+COPY ./socksx /socksx
+
+# Build an optimized binary
+WORKDIR /socksx
+RUN cargo build --example functions --release
+
+# Define final image
+FROM ubuntu:22.04
+
+RUN apt-get update && apt-get install -y \
+    libssl3 \
+    libuv1 \
+ && rm -rf /var/lib/apt/lists/*
+
+# Copy `brane-log from the build stage
+COPY --from=build /socksx/target/release/examples/functions .
+
+EXPOSE 1080
+ENTRYPOINT [ "./functions" ]

README.md

@@ -1,25 +1,66 @@
-# SOCKS toolkit
-[![Build Status](https://github.com/onnovalkering/socksx/workflows/CI/badge.svg)](https://github.com/onnovalkering/socksx/actions)
+# SOCKS toolkit for Rust
 [![License: MIT](https://img.shields.io/github/license/onnovalkering/socksx.svg)](https://github.com/onnovalkering/socksx/blob/master/LICENSE)
-[![Coverage Status](https://coveralls.io/repos/github/onnovalkering/socksx/badge.svg)](https://coveralls.io/github/onnovalkering/socksx?branch=master)
-[![Crates.io](https://img.shields.io/crates/v/socksx)](https://crates.io/crates/socksx)
 
 A work-in-progress SOCKS toolkit for Rust. SOCKS5 ([rfc1928](https://tools.ietf.org/html/rfc1928)) and SOCKS6 ([draft-11](https://tools.ietf.org/html/draft-olteanu-intarea-socks-6-11)) are supported.
 
 [Documentation](https://docs.rs/socksx/latest)
 
-## Python
-The `socksx-py` crate is a [PyO3](https://github.com/PyO3/PyO3)-based Python interface to `socksx`.
+## Client Usage
+Example client usage can be found in ./socksx/examples/client.rs. To run the example, use the following command:
+```bash
+cargo run --example client -- --host 172.16.238.4 --port 1080 --dest_host 172.16.238.5 --dest_port 12345 --src_port 12346
+```
+Note: The ip addresses are just examples, you should use your own ip addresses. I created a docker network and assigned
+ip addresses to the containers.
 
-You can build and install this Python package locally (requires [`pipenv`](https://github.com/pypa/pipenv) and [`maturin`](https://github.com/PyO3/maturin)):
+## Server Usage
+### Building the binary
+To build the binary, run the following command:
+```bash
+cargo build --release
+```
 
-```shell
-$ pipenv install && pipenv shell
-$ maturin develop -m ./socksx-py/Cargo.toml
+To run the binary, run the following command:
+```bash
+./target/release/socksx --host 0.0.0.0 --port 1080 --protocol socks5
 ```
 
-To build a manylinux releases:
+If you want to using the chaining feature, you can run the following command:
+```bash
+./target/release/socksx --host 0.0.0.0 --port 1080 --protocol socks6 --chain socks6://145.10.0.1:1080
+```
+
+### Docker Image Build
+
+To build the Docker image for the proxy service, use the following command:
+
+(The Dockerfile is located at the root of the repository)
+```bash
+docker build -t proxy:latest -f Dockerfile .
+```
+
+Create a Docker network named `net` with a specified subnet.
+
+```bash
+docker network create --subnet=172.16.238.0/24 net
+```
+
+To run the Docker container, use the following command:
+
+```bash
+docker run --network=net --ip=172.16.238.2 -p 1080:1080 --name proxy proxy:latest --host 0.0.0.0 --port 1080
+```
+
+Make sure to run these commands in the correct sequence: build the image, create the network, and then run the container.
+
+### Docker Compose
+Check out the `docker-compose-proxy.yml` or `docker-compose-extensive.yml` file at the root of the repository for an example of how to use the proxy service with Docker Compose.
+
+
 
-```shell
-$ docker run --rm -v $(pwd):/io konstin2/maturin build --release -m ./socksx-py/Cargo.toml
-```
+## TODO
+- [ ] support chaining in socks 5
+- [ ] add badge for coverage (coveralls)
+- [ ] add badge for crates link 
+- [ ] add badge for CI status (github actions)
+- [ ] add badge for docs.rs and documentation link

docker-compose-extensive.yml

@@ -0,0 +1,96 @@
+# Example of two proxy chains simulating a sender node/domain and a receiver node/domains.
+# On sender side we have socks proxy, which is connected to a counter (mimicing a firewall) and encrypt
+# On receiver side we have socks proxy, which is connected to decrypt and counter
+# Communication looks like this:
+# sender(client) -> proxy (sender's side) -> counter -> encrypt -> proxy (destination's side) -> decrypt -> counter -> destination
+
+version: '3.8'
+
+services:
+  proxy-main:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "1080:1080"
+    command: "--host 0.0.0.0 --port 1080 --chain socks6://counter-1:1080 --chain socks6://encrypt:1080 --chain socks6://proxy-other:1080"
+    depends_on:
+      - counter-1
+      - encrypt
+      - proxy-other
+    networks:
+      net:
+        ipv4_address: 172.16.238.2
+
+  counter-1:
+    build: 
+      context: .
+      dockerfile: Dockerfile.counter
+    command: "--host 0.0.0.0"
+    networks:
+      net:
+        ipv4_address: 172.16.238.3
+
+  encrypt:
+    build:
+      context: .
+      dockerfile: Dockerfile.encrypt-decrypt
+    command: "chacha20"
+    environment:
+      - CHACHA20_KEY="123456789012345678901234567890"
+    networks:
+      net:
+        ipv4_address: 172.16.238.4
+
+  proxy-other:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "1081:1080"
+    command: "--host 0.0.0.0 --port 1080 --chain socks6://decrypt:1080 --chain socks6://counter-2:1080"
+    depends_on:
+      - counter-2
+      - decrypt
+    networks:
+      net:
+        ipv4_address: 172.16.238.5
+
+  counter-2:
+    build: 
+      context: .
+      dockerfile: Dockerfile.counter
+    command: "--host 0.0.0.0"
+    networks:
+      net:
+        ipv4_address: 172.16.238.6
+
+  decrypt:
+    build:
+      context: .
+      dockerfile: Dockerfile.encrypt-decrypt
+    command: "chacha20"
+    environment:
+      - CHACHA20_KEY="123456789012345678901234567890"
+    networks:
+      net:
+        ipv4_address: 172.16.238.7
+
+  netcat:
+    image: busybox
+    command: "nc -l -p 12345"
+    ports:
+      - "12345:12345"
+    restart: always
+    networks:
+      net:
+        ipv4_address: 172.16.238.8
+
+# The reason to create a virtual network is to be able to assign static IP addresses to the destination container
+# in this case, netcat. We can use this ip address from the client to connect to the destination.
+networks:
+    net:
+        ipam:
+            driver: default
+            config:
+                - subnet: "172.16.238.0/24"

docker-compose-proxy.yml

@@ -0,0 +1,33 @@
+# Example of using a standalone proxy to forward traffic to a destination
+
+version: '3.8'
+
+services:
+  proxy:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "1080:1080"
+    command: "--host 0.0.0.0 --port 1080"
+    networks:
+      net:
+        ipv4_address: 172.16.238.2
+
+  # this will be the destination
+  netcat:
+    image: busybox
+    command: "nc -l -p 12345"
+    ports:
+      - "12345:12345"
+    restart: always
+    networks:
+      net:
+        ipv4_address: 172.16.238.3
+
+networks:
+    net:
+        ipam:
+            driver: default
+            config:
+                - subnet: "172.16.238.0/24"

socksx-py/README.md

@@ -0,0 +1,15 @@
+## socksx-py
+The `socksx-py` crate is a [PyO3](https://github.com/PyO3/PyO3)-based Python interface to `socksx`.
+
+You can build and install this Python package locally (requires [`pipenv`](https://github.com/pypa/pipenv) and [`maturin`](https://github.com/PyO3/maturin)):
+
+```shell
+$ pipenv install && pipenv shell
+$ maturin develop -m ./Cargo.toml
+```
+
+To build a manylinux releases:
+
+```shell
+$ docker run --rm -v $(pwd):/io konstin2/maturin build --release -m ./Cargo.toml
+```