[readme]: WIP

github · Apr 5, 2022 · efb71d2 · efb71d2
1 parent b1117ff
commit efb71d2
Show file tree

Hide file tree

Showing 3 changed files with 144 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -4,6 +4,8 @@ This [GitHub CLI](https://cli.github.com/) extension allows to bridge network be
 
 For instance, if you are using `VPN` to connect to your enterprise network to access a database or any other remote resources on the private network, this extension allows you to get to those resources from whithin a Codespace also, so you can develop fully inside a Codespace!
 
+[About GitHub CLI](https://cli.github.com/)
+
 ## Installation
 
 ```shell
@@ -41,20 +43,71 @@ There are two pannels in the connected view of the extension:
 - Panel on the left (`NAT`) shows the network address translation table for currently opened connections. For successful stateful protocols(e.g. `TCP`) the records are cleaned up automatically after connection is closed so teh records will come and go as connection is established and closed. For stateless protocols (e.g. `UDP` or `ICMP`) or unsuccessful `TCP` connections the records are cleaned up after some time, so those will show up in the list for some time.
 - Panel on the right (`DNS`) shows the resolved `DNS` records, as `hostname`, `record` and `time-to-live` (or `TTL`) values.
 
-
 Press `q` or `ctrl + c` to stop the extension.
 
 ## How it works
 
-How it works notes.
+General diagram is shown below:
+
+<img src="./diagrams/general.png" alt="general schema" />
+
+We bind to the `default gateway` network interface inside the codespace and forward all non-routed traffic to the `SSH tunnel` that connects a Codespace with your local machine. We forward only `L3` (`IP`) traffic and there are few criterias must hold for traffic to be forwarded:
+
+- it must appear on the `default gateway`
+- it must not be addressed tosomething that is on default gateway subnet
+
+This ensures that we fallback to forwaring packets only if they were not handled by any other network interface inside a Codespace.
+
+Once a packet reaches the local machine, we see if we can forward it to a meaningful distanation, for that we resolve network interface that can handle the packet destination. Such network interface must not be a default gateway interface given that the packet destination is not to the gateway subnet, otherwise the packet is addressed to internet which can be handled from whithin the codespace directly.
+
+If such network interface is found, we create a local `network socket` and a `NAT` record for the connection. The NAT reord is used to map remote packet source address to the local network socket address, so it appears to the remote resource as if traffic is comming from the local machine. When a reply packet is received, we perform reverse address translation and send the packet back to the codespace (so it appears if reply came directly from the Codespace default gateway interface).
+
+For `DNS` packets, we register an address that is on `default gateway` subnet which allows to catch all unresolved `DNS` queries. Once `DNS` packet received, it is passed over to the `local machine` where request to local `DNS` resolver is made and reply sent back to the Codespace.
 
 ## Troubleshooting
 
 Troubleshooting notes.
 
 ## Supported platforms
 
-- MacOSx AMD64
-- Linux AMD64
-
-[About GitHub CLI](https://cli.github.com/)
+| Target platforms        | Local | Inside Codespace |
+|-------------------------|-------|--------------|
+| Mac OSx (Intel)         | ✅     | 🙅          |
+| Mac OSx (Apple)         | 🏃     | 🙅          |
+| Linux (Ubuntu)          | ✅     | ✅            |
+| Linux (Debian)          | ✅     | ✅            |
+| Linux (Fedora)          | ✅     | ✅            |
+| Linux (Red Hat)         | ✅     | ✅            |
+| Linux (Mint)            | ✅     | ✅            |
+| Linux (OpenSUSE)        | ✅     | ✅            |
+| Linux (Centos)          | ✅     | ✅            |
+| Linux (Kali)            | ✅     | ✅            |
+| Linux (Raspberry Pi OS) | ✅     | ✅            |
+| Windows 10              | 🏃     | 🙅          |
+
+✅ - currently supported 🏃 - support in progress 🙅 - not applicable
+
+### DNS
+
+| DNS Record Type | Status |
+|-----------------|--------|
+| A               | ✅      |
+| AAAA            | ✅      |
+| CNAME           | ✅      |
+| NS              | ✅      |
+| TXT             | ✅      |
+| SOA             | ✅      |
+| PTR             | ✅      |
+| NULL            | ✅      |
+| MX              | ✅      |
+| ANY             | ✅      |
+
+## Other GitHub CLI extensions for Codespaces
+
+- [Codespace Compose](https://github.com/github/gh-codespace-compose)
+- [About GitHub CLI](https://cli.github.com/)
+- [GitHub CLI Docs](https://cli.github.com/manual/gh)
+
+## License
+
+License text.
diff --git a/diagrams/general.drawio b/diagrams/general.drawio
@@ -0,0 +1,85 @@
+<mxfile host="65bd71144e">
+    <diagram id="zo_TgSlkXzDTACk1qIh0" name="Page-1">
+        <mxGraphModel dx="194" dy="438" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="5" value="&lt;meta charset=&quot;utf-8&quot;&gt;&lt;div style=&quot;color: rgb(191, 199, 213); background-color: rgb(41, 45, 62); font-family: menlo, monaco, &amp;quot;courier new&amp;quot;, monospace; font-weight: normal; font-size: 12px; line-height: 18px;&quot;&gt;&lt;br&gt;&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+                    <mxGeometry x="200" y="360" width="120" height="120" as="geometry"/>
+                </mxCell>
+                <mxCell id="6" value="Local machine" style="text;html=1;strokeColor=none;fillColor=none;align=right;verticalAlign=middle;whiteSpace=wrap;rounded=0;spacingRight=4;fontStyle=1;fontSize=10;" vertex="1" parent="1">
+                    <mxGeometry x="230" y="450" width="90" height="30" as="geometry"/>
+                </mxCell>
+                <mxCell id="7" value="&lt;meta charset=&quot;utf-8&quot;&gt;&lt;div style=&quot;color: rgb(191, 199, 213); background-color: rgb(41, 45, 62); font-family: menlo, monaco, &amp;quot;courier new&amp;quot;, monospace; font-weight: normal; font-size: 12px; line-height: 18px;&quot;&gt;&lt;br&gt;&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+                    <mxGeometry x="500" y="360" width="120" height="120" as="geometry"/>
+                </mxCell>
+                <mxCell id="8" value="Codespace" style="text;html=1;strokeColor=none;fillColor=none;align=right;verticalAlign=middle;whiteSpace=wrap;rounded=0;spacingRight=4;fontSize=10;fontStyle=1" vertex="1" parent="1">
+                    <mxGeometry x="530" y="450" width="90" height="30" as="geometry"/>
+                </mxCell>
+                <mxCell id="9" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+                    <mxGeometry x="520" y="400" width="80" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="10" value="Default Gateway" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+                    <mxGeometry x="530" y="405" width="60" height="30" as="geometry"/>
+                </mxCell>
+                <mxCell id="11" value="" style="endArrow=classic;startArrow=classic;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;strokeColor=#F0F0F0;rounded=0;" edge="1" parent="1" source="5" target="7">
+                    <mxGeometry width="50" height="50" relative="1" as="geometry">
+                        <mxPoint x="430" y="400" as="sourcePoint"/>
+                        <mxPoint x="480" y="350" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="12" value="SSH Tunnel" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+                    <mxGeometry x="360" y="390" width="100" height="30" as="geometry"/>
+                </mxCell>
+                <mxCell id="14" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+                    <mxGeometry x="220" y="400" width="80" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="15" value="DNS Resolver" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+                    <mxGeometry x="230" y="405" width="60" height="30" as="geometry"/>
+                </mxCell>
+                <mxCell id="16" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+                    <mxGeometry x="220" y="360" width="80" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="17" value="Network Router" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+                    <mxGeometry x="230" y="365" width="60" height="30" as="geometry"/>
+                </mxCell>
+                <mxCell id="18" value="" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;fillColor=default;" vertex="1" parent="1">
+                    <mxGeometry x="194" y="160" width="120" height="80" as="geometry"/>
+                </mxCell>
+                <mxCell id="21" value="" style="endArrow=none;html=1;strokeWidth=1;rounded=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;strokeColor=#858585;" edge="1" parent="1" target="7">
+                    <mxGeometry width="50" height="50" relative="1" as="geometry">
+                        <mxPoint x="520" y="420" as="sourcePoint"/>
+                        <mxPoint x="460" y="300" as="targetPoint"/>
+                        <Array as="points"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="22" value="" style="endArrow=none;html=1;strokeWidth=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;strokeColor=#858585;" edge="1" parent="1" source="5" target="16">
+                    <mxGeometry width="50" height="50" relative="1" as="geometry">
+                        <mxPoint x="430" y="350" as="sourcePoint"/>
+                        <mxPoint x="480" y="300" as="targetPoint"/>
+                        <Array as="points">
+                            <mxPoint x="310" y="420"/>
+                            <mxPoint x="310" y="380"/>
+                        </Array>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="24" value="" style="endArrow=classic;startArrow=classic;html=1;rounded=0;strokeColor=#F0F0F0;strokeWidth=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.55;entryY=0.95;entryDx=0;entryDy=0;entryPerimeter=0;fontColor=#F0F0F0;" edge="1" parent="1" source="16" target="18">
+                    <mxGeometry width="50" height="50" relative="1" as="geometry">
+                        <mxPoint x="420" y="370" as="sourcePoint"/>
+                        <mxPoint x="470" y="320" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="25" value="" style="endArrow=none;html=1;strokeWidth=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;strokeColor=#858585;" edge="1" parent="1" source="5" target="14">
+                    <mxGeometry width="50" height="50" relative="1" as="geometry">
+                        <mxPoint x="330" y="430" as="sourcePoint"/>
+                        <mxPoint x="310" y="390" as="targetPoint"/>
+                        <Array as="points"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="26" value="Remote resources" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=10;fontStyle=1" vertex="1" parent="1">
+                    <mxGeometry x="227" y="187" width="60" height="30" as="geometry"/>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+</mxfile>
diff --git a/diagrams/general.png b/diagrams/general.png