{"id":17008773,"url":"https://github.com/i-e-b/virtualvpn","last_synced_at":"2025-04-12T07:37:57.199Z","repository":{"id":51447598,"uuid":"520412411","full_name":"i-e-b/VirtualVpn","owner":"i-e-b","description":"An IKEv2/IPSEC VPN gateway that presents an application as if it was on a private network","archived":false,"fork":false,"pushed_at":"2024-04-11T08:07:02.000Z","size":1019,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T02:51:08.784Z","etag":null,"topics":["csharp","ikev2","ikev2-vpn","ipsec","network","production-ready","vpn","working"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/i-e-b.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-08-02T08:22:13.000Z","updated_at":"2025-02-18T00:48:11.000Z","dependencies_parsed_at":"2024-04-11T09:28:13.123Z","dependency_job_id":"3213ad63-74fd-44f2-958b-a2d4a0d7d0e4","html_url":"https://github.com/i-e-b/VirtualVpn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-e-b%2FVirtualVpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-e-b%2FVirtualVpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-e-b%2FVirtualVpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-e-b%2FVirtualVpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i-e-b","download_url":"https://codeload.github.com/i-e-b/VirtualVpn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248536119,"owners_count":21120681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","ikev2","ikev2-vpn","ipsec","network","production-ready","vpn","working"],"created_at":"2024-10-14T05:29:14.656Z","updated_at":"2025-04-12T07:37:57.164Z","avatar_url":"https://github.com/i-e-b.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VirtualVpn\n\nAn IKEv2/IPSEC VPN gateway that presents an application as if it was on a private network\n\nIt will respond to StrongSwan opening a session from outside, and will\ncorrectly start a secured session. It allows communication to and from\na configured web app.\n\nIt is slow compared to a hardware VPN device. It is slow compared to a\npair of tin-cans with a tight string in between. It might be just fast\nenough for a basic API that is called a few times a second at most.\n\nThis VPN does **not** support all IKEv2 settings, and doesn't support IKEv1 at all.\n\nHopefully it's simple enough that any new parts can be added.\n\n## Starting\n\nIn the VirtualVPN project folder (where the `VirtualVPN.csproj` file is), call\n`dotnet run .`\n\nOnce the project is compiled and running, you should get a message like:\n```\nStarting up VirtualVPN. Current platform=Windows\nLog level set to 3 (Info)\n2022-09-06T09:07 (utc) Listening on 4500...\n2022-09-06T09:07 (utc) Listening on 500...\n```\n\nIf you get an error message, you might not have permissions to attach to the network\n(in which case, make sure you are running as root/administrator),\nor there is already VPN software running on these ports.\n\nPress \u003ckbd\u003eenter\u003c/kbd\u003e in the console to get a list of available commands.\n\nYou will want to load a configuration file before connecting to a remote gateway.\nThe default settings can be saved or viewed by typing `save mySettings.json`\u003ckbd\u003eenter\u003c/kbd\u003e into the console.\n\nLoad settings with `load mySettings.json`\u003ckbd\u003eenter\u003c/kbd\u003e\n\nOnce settings are loaded, you can connect from the remote gateway, or request a connection\nby typing `start 192.168.x.x`\u003ckbd\u003eenter\u003c/kbd\u003e at the console (with the IP address of the remote gateway).\n\n## Running as a service\n\nIf you run VirtualVPN with command-line arguments, it will enter 'non-interactive' mode,\ndesigned for running as a service.\n\n- See `VirtualVpn.service` file for information on setting up a systemd service.\n- See `VirtualVpn/RunVpn.sh` for an example of calling command-line arguments.\n\nThe command line arguments are the same as the interactive arguments, and are run\nin the order they are supplied.\n\nIf the first argument is `int`, VirtualVPN will run in interactive mode even when\ncommand line arguments are supplied.\n\n## Health check failure codes\n\nThe health check API end point gives text messages on failure, but in case you only have\naccess to the HTTP status codes (looking at you, uptime-kuma), these are\n\n* 200 - All OK: VpnServer is up with an active session\n* 503 - VpnServer instance is null\n* 410 - VpnServer instance is not running\n* 502 - VpnServer is running, but there are no active sessions\n* 409 - VpnServer is up, a session is established, but **tunnelled** TCP connections are being terminated (indicates some filtering software is misconfigured at the remote side)\n* 408 - VpnServer is up, a session is established, but no traffic (including keep-alive pings) has been received for over 2 minutes\n\n## Layout\n\nThe projects `ProtocolTests`, and `TestProxy` are tools to help with development,\nand are not required when running Virtual VPN\n\n### Virtual VPN parts\n\n- **Crypto** - Diffie-Hellman key exchange, cryptographic routines, secure hashes etc.\n- **Enums** - Standard numeric values for IKE, ESP, and TCP/IP\n- **EspProtocol** - Handlers for Child SAs, ESP packets, IKE packets. This is where the gateway-to-gateway tunnelled traffic is handled\n- **Helpers** - Serialisation tools, low level C# bits\n- **InternetProtocol** - Various IP bits, including packet, addresses, and ICMP bits\n- **Logging** - Log level control, log formatting, and output to Loki servers\n- **TcpProtocol** - Embedded TCP stack to handle termination and re-routing to host web-app\n- **TlsWrappers** - Adaptors to decrypt and re-encrypt TLS/SSL traffic so VirtualVPN can pretend to be a different HTTPS server\n- **Web** - An api and a website for remotely lifting traffic captures off of the VirtualVPN\n- Program - The entry point\n- Settings - Configuration root and documentation. Read the comments to understand the setting values.\n- VpnServer - root listener for IKE and ESP traffic. This directs to one of a set of VpnSessions\n- VpnSession - handler for a single VPN session. This deals with IKEv2 protocol, but not tunnelled traffic.\n\n## Proxy API\n\nVirtualVPN lets other systems call out through the remote gateway as if they were a machine on the\nvirtual network. See `TestProxy/TestProxyApiProgram.cs` for an example of calling this.\nYou will need to supply complete and correct HTTP headers and body.\n\n## Helpful Bash Commands\n\n### Posting a binary file with curl\nhttps://curl.se/docs/manpage.html#-d\n```\ncurl -X 'POST' 'http://55.55.55.55:5223/WeatherForecast/checksum' -H 'accept: */*' -H 'Content-Type: application/octet-stream' -d @CHANGES -v\n```\n\n## Setup for test and development\n\n### Example ipsec.conf\n\nThis config goes in `/etc/ipsec.conf` for StrongSwan to use.\n\"alice\" is a server running both VirtualVPN and the web app.\n\"bob\" is a server running StrongSwan as a test 'remote' VPN\ngateway\n\n```\nconn alice\n    # life cycle #\n    auto=add\n    dpdaction=clear\n    dpddelay=300s\n    rekey=no\n    ## phase 1 ##\n    keyexchange=ikev2\n    ## phase 2 ##\n    authby=secret\n    mark=24\n    type=tunnel\n    # us (bob) #\n    leftauth=psk\n    left=192.168.0.3\n    leftid=192.168.0.3\n    leftsubnet=192.168.0.40/32\n    lefthostaccess=yes\n    leftallowany=yes\n    leftupdown=/etc/ipsec-notify-bob.sh\n    # them (alice) #\n    rightauth=psk\n    right=192.168.0.2\n    rightid=192.168.0.2\n    rightsubnet=55.55.0.0/16\n```\n\n### Notify script\n\nThis goes with the ipsec.conf, in `/etc/ipsec-notify-bob.sh`.\nIt needs to have execute permissions. This script adds a vti \nwhich routes traffic for 55.55.?.? to a VirtualVPN device on\nBob. Because the sub-net is a `/16` range, many IP addresses\nwill route to the one VirtualVPN - but it does not care. All\nrequests will get routed to the web app VirtualVPN is set up\nto use. Ports are also ignored, and the web app will get any\nrequests -- except ICMP pings, which VirtualVPN will respond\nto itself.\n\n```\n#!/bin/bash\necho \"###### BOB UP/DOWN SCRIPT #######\"\necho \"wake...\" \u003e /var/log/vti_state\nset -o errexit\n! echo \"VERB = ${PLUTO_VERB-}\" || true\n\ncase \"${PLUTO_VERB-}\" in\n    \"up-client\")\n        echo \"cleaning old vti devices\" \u003e /var/log/vti_state\n        ! ip tunnel del vti_h || true\n        echo \"creating vti device ${PLUTO_ME} -\u003e ${PLUTO_PEER} mark=${PLUTO_MARK_OUT%%/*}-\u003e${PLUTO_MARK_IN%%/*}\" \u003e /var/log/vti_state\n        #ip tunnel add vti_h mode vti local \"${PLUTO_ME}\" remote \"${PLUTO_PEER}\" key \"${PLUTO_MARK_IN%%/*}\"\n        ip tunnel add vti_h mode vti local \"${PLUTO_ME}\" remote 0.0.0.0 key \"${PLUTO_MARK_IN%%/*}\"\n        echo \"linking\" \u003e /var/log/vti_state\n        ip link set vti_h up mtu 1419\n        echo \"adding routes\" \u003e /var/log/vti_state\n\n        ip addr add 192.168.0.40/32 remote 55.55.0.0/16 dev vti_h\n\n        echo \"setting sysctl\" \u003e /var/log/vti_state\n        sysctl -w \"net.ipv4.conf.vti_h.disable_policy=1\"\n        echo \"up\" \u003e /var/log/vti_state\n        ;;\n    \"up-host\")\n        echo \"cleaning old vti devices\" \u003e /var/log/vti_state\n        ! ip tunnel del vti_h || true\n        echo \"creating vti device ${PLUTO_ME} -\u003e ${PLUTO_PEER} mark=${PLUTO_MARK_OUT%%/*}-\u003e${PLUTO_MARK_IN%%/*}\" \u003e /var/log/vti_state\n        ip tunnel add vti_h mode vti local \"${PLUTO_ME}\" remote \"${PLUTO_PEER}\" okey \"${PLUTO_MARK_OUT%%/*}\" ikey \"${PLUTO_MARK_IN%%/*}\"\n        echo \"linking\" \u003e /var/log/vti_state\n        ip link set vti_h up mtu 1419\n        echo \"adding routes\" \u003e /var/log/vti_state\n\n        ip addr add 192.168.0.40/32 remote 55.55.0.0/16 dev vti_h\n\n        echo \"setting sysctl\" \u003e /var/log/vti_state\n        sysctl -w \"net.ipv4.conf.vti_h.disable_policy=1\"\n        echo \"up\" \u003e /var/log/vti_state\n        ;;\n    \"down-client\")\n        echo \"removing vti_h\" \u003e /var/log/vti_state\n        ! ip tunnel del vti_h || true\n        echo \"down\" \u003e /var/log/vti_state\n        ;;\nesac\n```\n\n## Notes\n\nIf ports are blocked on Windows,  call `netstat -ano` to get\nthe process ids. It's probably the IKE service, which you'll\nneed to turn off.\n\nTo get this fully working, you will either need a good modem\nthat allow you to pass all traffic to your device, or not be\nbehind any kind of NAT, and have a firewall that permits all\ntraffic on ports 500 and 4500 regardless of protocol type.\n\nParts based on, or derived from:\n\n- https://github.com/strongswan/strongswan\n- https://github.com/dschoeffm/go-ikev2\n- https://github.com/alejandro-perez/pyikev2\n- https://github.com/qwj/python-vpn\n- https://github.com/frebib/netstack.git\n\nReferences\n\nhttps://datatracker.ietf.org/doc/html/rfc7296\nhttps://www.rfc-editor.org/rfc/rfc9293\nhttps://security.stackexchange.com/questions/56434/understanding-the-details-of-spi-in-ike-and-ipsec\nhttp://unixwiz.net/techtips/iguide-ipsec.html\nhttps://www.secfu.net/2017/12/23/the-ikev2-header-and-the-security-association-payload/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-e-b%2Fvirtualvpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi-e-b%2Fvirtualvpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-e-b%2Fvirtualvpn/lists"}