Metadata-Version: 2.5
Name: byway
Version: 0.6.0
Summary: Userspace client that speaks the Cisco AnyConnect VPN protocol, with an in-process TCP/IP stack
Project-URL: Homepage, https://github.com/dehesselle/byway
Project-URL: Repository, https://github.com/dehesselle/byway
Author-email: René de Hesselle <dehesselle@web.de>
License-Expression: 0BSD
License-File: LICENSE
License-File: LICENSES/0BSD.txt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: platformdirs>=4
Requires-Dist: usernet[httpx]>=0.7
Provides-Extra: keyring
Requires-Dist: keyring>=25; extra == 'keyring'
Description-Content-Type: text/markdown

# byway

> __Byway__ · _English noun_
>
> A secondary road or path, away from the main route.

byway is a userspace client that speaks the Cisco AnyConnect VPN protocol. No tun device, no
virtual adapter, no routing changes, no administrator rights: the tunnel and everything carried
over it live inside the Python process. Access is through a local SOCKS5 proxy, so `ssh` and
`curl` work unchanged, and an in-process API.

Use it when you need to reach a REST API or SSH into a host inside a corporate VPN, but
cannot, or would rather not, install a VPN client, change routing, or use admin rights. VPN
access is scoped to one process rather than to the whole machine.

## Install and run

```console
$ uv tool install byway
$ byway probe vpn.corp.example          # what does this gateway ask for?
$ byway up vpn.corp.example -u user --socks
address   172.29.29.3/255.255.0.0
mtu       1383
routes    10.0.0.0/23
socks5    127.0.0.1:1080
```

`byway up` prompts for the password and holds the tunnel open. From another terminal:

```sh
curl --socks5 127.0.0.1:1080 http://10.0.0.20/
ssh -o ProxyCommand="byway nc --via 127.0.0.1:1080 %h %p" user@10.0.0.32
```

Saved profiles, other ways to pass the password, and certificate pinning are in the
[manual](https://github.com/dehesselle/byway/blob/master/docs/MANUAL.md).

## Use it from your own program

```sh
uv add byway
```

```python
import byway

async with byway.connect("vpn.corp.example", user, password) as vpn:
    reader, writer = await vpn.open_connection("10.0.0.32", 22)

    async with vpn.httpx_client() as http:
        response = await http.get("http://10.0.0.20/v1/things")
```

## Caveats

- Hosts are IP addresses, or names from a fixed table in the profile: there is no in-tunnel
  DNS.
- byway supports IPv4, TLS, outbound TCP and username/password authentication only.
- Many organisations require a sanctioned VPN client, and byway bypasses posture assessment
  (CSD/HostScan) entirely. Check that you are allowed to use it before you point it at a
  corporate gateway.

## Documentation

- [docs/MANUAL.md](https://github.com/dehesselle/byway/blob/master/docs/MANUAL.md) — all commands, profiles, credentials, certificate pinning and the library API.
- [docs/http-async.md](https://github.com/dehesselle/byway/blob/master/docs/http-async.md) — calling REST APIs from async code.
- [docs/http-sync.md](https://github.com/dehesselle/byway/blob/master/docs/http-sync.md) — calling REST APIs from sync code.
- [docs/OPERATIONS.md](https://github.com/dehesselle/byway/blob/master/docs/OPERATIONS.md) — runtime behavior: idle timeouts, reconnects, sessions, throughput, diagnostics.
- [docs/DESIGN.md](https://github.com/dehesselle/byway/blob/master/docs/DESIGN.md) — architecture, core principles and deliberate omissions.
- [docs/protocol.md](https://github.com/dehesselle/byway/blob/master/docs/protocol.md) — protocol notes and gateway observations.
- [docs/throughput.md](https://github.com/dehesselle/byway/blob/master/docs/throughput.md) — throughput measurements.
- [docs/DEVELOPMENT.md](https://github.com/dehesselle/byway/blob/master/docs/DEVELOPMENT.md) — building and testing.

## AI disclosure

Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x. Generated code was tested, but not every line was reviewed in detail.

## License

[0BSD](https://github.com/dehesselle/byway/blob/master/LICENSES/0BSD.txt)
