added basic docs

O-X-L · Sep 26, 2023 · 4896739 · 4896739
1 parent 7ac91e7
commit 4896739
Show file tree

Hide file tree

Showing 6 changed files with 332 additions and 68 deletions.
diff --git a/README.md b/README.md
@@ -21,65 +21,6 @@ Its focus is set on security filtering for HTTPS.
 
 [docs.calamary.net](https://docs.calamary.net)
 
-## Why?
-
-Forward proxies are very useful to enforce a security-baseline in networks and a must-have for Zero-Trust environments.
-
-Many enterprises and individuals will use proxies integrated with vendor network-firewalls or cloud-services to handle this filtering.
-
-But some of us might like to keep control over that system.
-
-The usage of go-based applications is easy (_single binary_) and can perform well.
-
-### Why not use Squid?
-
-**Squid has some limitations** that make its usage more complicated than it should be.
-
-**Per example**:
-
-* intercept/transparent mode - no native solution for [the DNAT restrictions](http://www.squid-cache.org/Advisories/SQUID-2011_1.txt)
-
-  Related errors:
-
-  * `NF getsockopt(ORIGINAL_DST) failed`
-  * `NAT/TPROXY lookup failed to locate original IPs`
-  * `Forwarding loop detected`
-
-
-* intercept/transparent mode - [host verification - using DNS](http://www.squid-cache.org/Doc/config/host_verify_strict/)
-
-  does hit issues with todays DNS-handling of major providers:
-
-  * TTLs <= 1 min (*p.e. download.docker.com, debian.map.fastlydns.net*)
-
-  Related error: `Host header forgery detected`
-
-
-Squid is a good and stable software. But I get the feeling it needed to grow into more than it was designed for initially. Some behavior is incomsistent between modes and not optimized for todays IT-world.
-
-I would much preferr a keep-it-simple approach. Even if that means that some nice-to-have features are not implemented.
-
-
-## How?
-
-* Use TLS-SNI as target instead of HTTP Host-Header
-
-
-* Optionally use additional DNS-based verfication if TTL > 3 min
-
-
-* Whenever it is not possible to route the traffic through the proxy..
-
-  To overcome the DNAT restriction, of losing the real target IP, the proxy will have a lightweight forwarder mode:
-
-  <img src="https://wiki.superstes.eu/en/latest/_images/squid_remote.png" alt="Proxy forwarder" width="400">
-
-
-* Transparent traffic interception will be the focus.
-
-  Setting the environment-variables 'HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy' and 'https_proxy' for all applications and HTTP-clients may be problematic/too inconsistent
-
-
 ## Roadmap
 
 - [ ] Forwarding

diff --git a/docs/source/_inc/in_progress.rst b/docs/source/_inc/in_progress.rst
@@ -1,2 +1,2 @@
 .. warning::
-    Writing of this documentation is still in progress! Read it with a grain of salt!
+    Development & writing of this documentation is still in progress!
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -9,6 +9,3 @@ Camalary Documentation
     :maxdepth: 1
 
     info/*
-
-
-.. include:: _inc/in_progress.rst
diff --git a/docs/source/info/getting_started.rst b/docs/source/info/getting_started.rst
@@ -0,0 +1,155 @@
+.. _getting_started:
+
+.. include:: _inc/head.rst
+
+.. include:: _inc/in_progress.rst
+
+
+###############
+Getting Started
+###############
+
+Installation
+############
+
+Download the binary for your desired target system from the `latest relase page <https://github.com/superstes/calamary/releases/latest>`_
+
+Run
+###
+
+Just execute it.
+
+.. code-block:: bash
+
+    /usr/bin/calamary
+
+
+Config-validation only:
+
+.. code-block:: bash
+
+    /usr/bin/calamary -v
+
+
+TProxy
+======
+
+To run Calamary as `TPROXY <https://docs.kernel.org/networking/tproxy.html>`_ target - you will have to set [CAP_NET_RAW](https://man7.org/linux/man-pages/man7/capabilities.7.html):
+
+> bind to any address for transparent proxying
+
+You can add it like this:
+
+```bash
+setcap cap_net_raw=+ep /usr/bin/calamary
+
+# make sure only wanted users can execute the binary!
+chown root:proxy /usr/bin/calamary
+chmod 750 /usr/bin/calamary
+```
+
+Read more about TPROXY here: `wiki.superstes.eu - NFTables - TProxy <https://wiki.superstes.eu/en/latest/1/network/nftables.html#tproxy>`_
+
+Systemd service
+===============
+
+Example systemd service to run Calamary:
+
+
+.. code-block:: text
+
+    [Unit]
+    Description=Calamary Forward Proxy
+    Documentation=https://docs.calamary.net
+    Documentation=https://github.com/superstes/calamary
+    After=network-online.target
+    Wants=network-online.target
+
+    [Service]
+    Type=simple
+    Environment=CONFIG=/etc/calamary/config.yml
+
+    # validate before start/restart
+    ExecStartPre=/usr/bin/calamary -f $CONFIG -v
+    ExecStart=/usr/bin/calamary -f $CONFIG
+
+    # validate before reload
+    ExecReload=/usr/bin/calamary -f $CONFIG -v
+    ExecReload=/bin/kill -HUP $MAINPID
+
+    User=proxy
+    Group=proxy
+    Restart=on-failure
+    RestartSec=5s
+
+    StandardOutput=journal
+    StandardError=journal
+    SyslogIdentifier=calamary
+
+    [Install]
+    WantedBy=multi-user.target
+
+
+Configuration
+#############
+
+See :ref:`Rules <rules>`for more details about defining the filter ruleset.
+
+The default config path is :code:`/etc/calamary/config.yml`
+
+Basic config example:
+
+.. code-block:: yaml
+
+    ---
+
+    service:
+    listen:
+      port: 4128
+      ip4:
+        - '127.0.0.1'
+      ip6:
+        - '::1'
+      tcp: true
+      udp: false  # not yet implemented
+      transparent: false  # tproxy mode
+
+    debug: false
+    timeout:
+      connection: 5
+      handshake: 5
+      dial: 5
+      intercept: 2
+
+    output:
+      fwmark: 0
+      interface: ''
+
+    vars:
+      - name: 'net_private'
+        value: ['192.168.0.0/16', '172.16.0.0/12', '10.0.0.0/8']
+      - name: 'svc_http'
+        value: [80, 443]
+
+    rules:
+      - match:
+          dest: '192.168.100.0/24'
+        action: 'drop'
+
+      - match:
+          port: ['!443', '!80']
+        action: 'drop'
+
+      - match:
+          src: '$net_private'
+          dest: '$net_private'
+          port: '$svc_http'
+          protoL4: 'tcp'
+        action: 'accept'
+
+      - match:
+          dest: '!$net_private'
+          port: 443
+          protoL4: 'tcp'
+        action: 'accept' 
+ 
diff --git a/docs/source/info/intro.rst b/docs/source/info/intro.rst
@@ -1,14 +1,93 @@
+.. _intro:
+
+.. |proxy_forwarder| image:: https://wiki.superstes.eu/en/latest/_images/squid_remote.png
+   :class: wiki-img
+
 .. include:: _inc/head.rst
 
 #####
 Intro
 #####
 
-.. toctree::
-    :glob:
-    :maxdepth: 1
+Calamary is a `squid <http://www.squid-cache.org/>`_-like proxy.
+
+Its focus is set on **security filtering for HTTPS**.
+
+**It will not**:
+* act as caching proxy
+* act as reverse proxy
+
+**Features**:
+* basic traffic filtering - see :ref:`Rules <rules>`
+* certificate verification
+* enforce TLS (*deny any unencrypted connections*)
+* detect plain HTTP and respond with generic HTTPS-redirect
+* intercept-, http-proxy and proxy-proto-modes
+
+  * support for `proxy-protocol <https://github.com/pires/go-proxyproto>`_
+
+Getting Started
+###############
+
+ :ref:`Getting started <getting_started>`
+
+Why?
+####
+
+Forward proxies are very useful to enforce a security-baseline in networks and a must-have for Zero-Trust environments.
+
+Many enterprises and individuals will use proxies integrated with vendor network-firewalls or cloud-services to handle this filtering.
+
+But some of us might like to keep control over that system.
+
+The usage of go-based applications is easy (*single binary*) and can perform well.
+
+Why not use Squid?
+==================
+
+**Squid has some limitations** that make its usage more complicated than it should be.
+
+**Per example**:
+
+* intercept/transparent mode - no native solution for `the DNAT restrictions <http://www.squid-cache.org/Advisories/SQUID-2011_1.txt>`_
+
+  Related errors:
+
+  * `NF getsockopt(ORIGINAL_DST) failed`
+  * `NAT/TPROXY lookup failed to locate original IPs`
+  * `Forwarding loop detected`
+
+
+* intercept/transparent mode - `host verification - using DNS <http://www.squid-cache.org/Doc/config/host_verify_strict/>`_
+
+  does hit issues with todays DNS-handling of major providers:
+
+  * TTLs <= 1 min (*p.e. download.docker.com, debian.map.fastlydns.net*)
+
+  Related error: `Host header forgery detected`
+
+
+Squid is a good and stable software. But I get the feeling it needed to grow into more than it was designed for initially. Some behavior is incomsistent between modes and not optimized for todays IT-world.
+
+I would much preferr a keep-it-simple approach. Even if that means that some nice-to-have features are not implemented.
+
+
+How?
+####
+
+* Use TLS-SNI as target instead of HTTP Host-Header
+
+
+* Optionally use additional DNS-based verfication if TTL > 3 min
+
+
+* Whenever it is not possible to route the traffic through the proxy..
+
+  To overcome the DNAT restriction, of losing the real target IP, the proxy will have a lightweight forwarder mode:
+
+  |proxy_forwarder|
 
-    info/*
 
+* **Transparent traffic interception will be the focus**.
 
-.. include:: _inc/in_progress.rst
+  Setting the environment-variables 'HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy' and 'https_proxy' for all applications and HTTP-clients may be problematic/too inconsistent