modes & debug docs

superstes · Oct 1, 2023 · 2929a1b · 2929a1b
1 parent ced0ab5
commit 2929a1b
Show file tree

Hide file tree

Showing 4 changed files with 124 additions and 41 deletions.
diff --git a/docs/source/info/debug.rst b/docs/source/info/debug.rst
@@ -0,0 +1,69 @@
+.. _debug:
+
+.. include:: ../_inc/head.rst
+
+.. include:: ../_inc/in_progress.rst
+
+#####
+Debug
+#####
+
+If you encounter any unexpected behaviour you might want to enable the :code:`debug` mode in your config-file to let Calamary produce more verbose logs.
+
+Examples
+########
+
+Tranparent Mode - Plaintext HTTP
+================================
+
+.. code-block:: bash
+
+    2023-10-02 00:10:30 | DEBUG | service | Accept: tcp://127.0.0.1:4128
+    2023-10-02 00:10:30 | DEBUG | parse | 192.168.11.104 => ? | Parsing TCP connection
+    2023-10-02 00:10:30 | DEBUG | parse | 192.168.11.104 => 135.181.170.219:80 | Processing TCP
+    2023-10-02 00:10:30 | DEBUG | parse | 192.168.11.104 => 135.181.170.219:80 | TLS information: IsTls=false, TlsVersion=0, TlsSni=
+    2023-10-02 00:10:30 | DEBUG | parse | 192.168.11.104 => 135.181.170.219:80 | Packet L5Proto: HTTP | TLS: none
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 0 - DNet: [192.168.100.0/24] vs 135.181.170.219
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 1 - !DPort: [443 80] vs 80
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 2 - Proto L4: [10] vs 10
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 2 - SNet: [192.168.0.0/16 172.16.0.0/12 10.0.0.0/8] vs 192.168.11.104
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 2 - DNet: [192.168.0.0/16 172.16.0.0/12 10.0.0.0/8] vs 135.181.170.219
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 3 - Proto L4: [10] vs 10
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 3 - !DNet: [192.168.0.0/16 172.16.0.0/12 10.0.0.0/8] vs 135.181.170.219
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 3 - DPort: [443 80] vs 80
+    2023-10-02 00:10:30 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:80 | Rule 3 - Applying action 'accept'
+    2023-10-02 00:10:30 | INFO | forward | 192.168.11.104 => 135.181.170.219:80 | Accept
+    2023-10-02 00:10:30 | DEBUG | send | 192.168.11.104 => 135.181.170.219:80 | Connection established
+    2023-10-02 00:10:30 | DEBUG | send | 192.168.11.104 => 135.181.170.219:80 | Forwarding
+    2023-10-02 00:10:30 | DEBUG | send | 192.168.11.104 => 135.181.170.219:80 | 5 bytes sent
+    2023-10-02 00:10:30 | DEBUG | send | 192.168.11.104 => 135.181.170.219:80 | 76 bytes sent
+    2023-10-02 00:10:30 | DEBUG | send | 192.168.11.104 => 135.181.170.219:80 | 351 bytes received
+    2023-10-02 00:10:30 | DEBUG | send | 192.168.11.104 => 135.181.170.219:80 | Closed
+
+Tranparent Mode - HTTPS
+=======================
+
+.. code-block:: bash
+
+    2023-10-02 00:13:20 | DEBUG | service | Accept: tcp://127.0.0.1:4128
+    2023-10-02 00:13:20 | DEBUG | parse | 192.168.11.104 => ? | Parsing TCP connection
+    2023-10-02 00:13:20 | DEBUG | parse | 192.168.11.104 => 135.181.170.219:443 | Processing TCP
+    2023-10-02 00:13:20 | DEBUG | parse | 192.168.11.104 => 135.181.170.219:443 | TLS information: IsTls=true, TlsVersion=771, TlsSni=superstes.eu
+    2023-10-02 00:13:20 | DEBUG | parse | 192.168.11.104 => 135.181.170.219:443 | Packet L5Proto: TLS | TLS: 1.2
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 0 - DNet: [192.168.100.0/24] vs 135.181.170.219
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 1 - !DPort: [443 80] vs 443
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 2 - Proto L4: [10] vs 10
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 2 - SNet: [192.168.0.0/16 172.16.0.0/12 10.0.0.0/8] vs 192.168.11.104
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 2 - DNet: [192.168.0.0/16 172.16.0.0/12 10.0.0.0/8] vs 135.181.170.219
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 3 - Proto L4: [10] vs 10
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 3 - !DNet: [192.168.0.0/16 172.16.0.0/12 10.0.0.0/8] vs 135.181.170.219
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 3 - DPort: [443 80] vs 443
+    2023-10-02 00:13:20 | DEBUG | filter | 192.168.11.104 => 135.181.170.219:443 | Rule 3 - Applying action 'accept'
+    2023-10-02 00:13:20 | INFO | forward | 192.168.11.104 => 135.181.170.219:443 | Accept
+    2023-10-02 00:13:20 | DEBUG | send | 192.168.11.104 => 135.181.170.219:443 | Connection established
+    2023-10-02 00:13:20 | DEBUG | send | 192.168.11.104 => 135.181.170.219:443 | Forwarding
+    2023-10-02 00:13:20 | DEBUG | send | 192.168.11.104 => 135.181.170.219:443 | 517 bytes sent
+    2023-10-02 00:13:20 | DEBUG | send | 192.168.11.104 => 135.181.170.219:443 | 4096 bytes received
+    ...
+    2023-10-02 00:13:20 | DEBUG | send | 192.168.11.104 => 135.181.170.219:443 | 842 bytes sent
+    2023-10-02 00:13:20 | DEBUG | send | 192.168.11.104 => 135.181.170.219:443 | Closed
diff --git a/docs/source/info/getting_started.rst b/docs/source/info/getting_started.rst
@@ -34,45 +34,7 @@ Config-validation only:
 Modes
 #####
 
-Transparent
-===========
-
-**State:** Implemented/Testing
-
-Calamary focuses on transparent traffic interception.
-
-You will have to redirect the traffic: :ref:`Redirect <redirect>`
-
-This mode will work for TCP & UDP.
-
-HTTP/HTTPS Proxy
-================
-
-**State:** Implemented/Testing
-
-You can also choose to let Calamary act as a HTTP/S proxy.
-
-One commonly uses this feature if only some applications should send their traffic over the proxy.
-
-This mode only supports TCP.
-
-Note: Calamary uses TLS-SNI > Host-Header to find its actual target host. It will also check all IPs (IPv6 > IPv4) that are returned by the DNS query for their reachability, before establishing a connection.
-
-SOCKS5 Proxy
-============
-
-**State:** not implemented
-
-Like HTTP/S proxy, but it works for UDP as well.
-
-Proxy-Protocol
-==============
-
-**State:** in development
-
-You can use the proxy-protcol mode if you want to send traffic from remote systems over the proxy.
-
-The commonly used `proxy-protocol <https://www.haproxy.com/blog/use-the-proxy-protocol-to-preserve-a-clients-ip-address>`_ preserves the original source- & destination while minimizing overhead.
+See: :ref:`Modes <modes>`
 
 
 Configuration
@@ -201,5 +163,7 @@ Download and 'install' Golang 1.21 to build the binary from sources: `Golang dow
 .. code-block:: bash
 
     git clone https://github.com/superstes/calamary
-    cd calamary/lib/main
+    cd calamary/lib
+    go mod download
+    cd main/
     go build -o calamary
diff --git a/docs/source/info/modes.rst b/docs/source/info/modes.rst
@@ -11,6 +11,17 @@ Modes
 Transparent
 ###########
 
+Info
+====
+
+**State:** Implemented/Testing
+
+Calamary focuses on transparent traffic interception.
+
+You will have to redirect the traffic: :ref:`Redirect <redirect>`
+
+This mode will work for TCP & UDP.
+
 Behaviour
 =========
 
@@ -77,10 +88,25 @@ DNAT - TLS
     </html>
     * Connection #0 to host superstes.eu left intact
 
+----
 
 HTTP Proxy
 ##########
 
+Info
+====
+
+**State:** Implemented/Testing
+
+You can also choose to let Calamary act as a HTTP/S proxy.
+
+One commonly uses this feature if only some applications should send their traffic over the proxy.
+
+This mode only supports TCP.
+
+Note: Calamary uses TLS-SNI > Host-Header to find its actual target host. It will also check all IPs (IPv6 > IPv4) that are returned by the DNS query for their reachability, before establishing a connection.
+
+
 Behaviour
 =========
 
@@ -173,26 +199,50 @@ HTTPS
     </html>
     * Connection #0 to host (nil) left intact
 
+----
 
 HTTPS Proxy
 ###########
 
+Has the same behaviour like 'HTTP Proxy' but the transport from client to proxy is also encrypted.
+
 Behaviour
 =========
 
 tbd
 
+----
+
 Proxy Protocol
 ##############
 
+Info
+====
+
+**State:** in development
+
+You can use the proxy-protcol mode if you want to send traffic from remote systems over the proxy.
+
+The commonly used `proxy-protocol <https://www.haproxy.com/blog/use-the-proxy-protocol-to-preserve-a-clients-ip-address>`_ preserves the original source- & destination while minimizing overhead.
+
 Behaviour
 =========
 
 tbd
 
+----
+
 SOCKS5
 ######
 
+Info
+====
+
+
+**State:** not implemented
+
+Like HTTP/S proxy, but it works for UDP as well.
+
 Behaviour
 =========
 

diff --git a/lib/go.mod b/lib/go.mod
@@ -5,10 +5,10 @@ go 1.21
 require golang.org/x/sys v0.12.0
 
 require (
+	github.com/creasty/defaults v1.7.0
 	github.com/pires/go-proxyproto v0.7.0
 	github.com/prometheus/client_golang v1.17.0
 	gopkg.in/yaml.v3 v3.0.1
-	github.com/creasty/defaults v1.7.0
 )
 
 require (