Docs and stuff

[anoduck]

This is awesome. Is there anyway I can help write the documentation? I am a good writer, formally educated to do so.

[XOR-op]

Thanks a lot for your appreciation! The current documentations are quite outdated and incomplete, and I'll welcome any contribution to the documentations.

I believe what we lack are the following:

1. What BoltConn can do: currently BoltConn supports a) proxy traffic via multiple protocols (and nesting proxy like Tor without server support!); b) rule-based routing for fine-grained control (proxy/block only a website or an App etc.); c) use MitM to modify traffic like mitmproxy/burpsuite; d) audit applications (a recently added feature which uses a pub-sub style to enable external program collecting and analyzing local traffic). However, I haven't found a systematic way to present all these features to potential users.
2. The detailed configuration guide: configuration is the core to BoltConn. However, currently there is no clear documentation on what can be configured and how they work. Advanced users may look at boltconn/src/config to get some basic ideas, but that's not user friendly at all.
3. CLI and RESTful API: those APIs are the ways to adjust the behavior of BoltConn at runtime. Thanks to clap crate, CLI has some basic documentations. However, more documentations for these two are still welcome!

If you have any interest in any of these aspects (or other part you are interested in), feel free to discuss with me or create a PR.

[anoduck]

This is a good start. I didn't even think about looking at boltconn/src/config, instead I went looking for the main runner. I will start digging there, and working through the source. Rust is readable, I do not use it for programming, but it is really cool.

Not coming from a javascript background, I have never had to work with restful apis before. They have been plentiful throughout my experience, but found some way of working around them. This will give me a chance to pick up knowledge on working with the technology.

1. I noticed there is not a "stop" command for the cli. Guessing you just haven't had time to get to it.
2. Are you hoping to integrate boltconn as a systemd service?

[XOR-op]

The boltconn/src/config covers most of the configurations that are defined by yaml structure. However, there are something not falling in this scope, like rules and some MitM actions. If you find some code too messy to understand, don't hesitate to let me know.

The RESTful APIs are basically under web_controller.rs. The APIs started with /ws/ are not RESTful APIs but WebSocket connections. They are used for streaming data without repeated calls.

For your two questions:

1. The biggest reason is, in my prior implementation, there is no global id for a connection. So at that time, the "stop" function is pretty useless and I forgot about that. With the current implementation, I'll add that function to CLI soon.
2. I have an example for systemd service here:

[Unit]
Description=BoltConn Service
After=network.target

[Service]
ExecStartPre=/usr/local/bin/boltconn clean
ExecStart=/usr/local/bin/boltconn start
ExecStop=/usr/local/bin/boltconn clean
Restart=always
User=root
Group=root

[Install]
WantedBy=multi-user.target

We can add that as an pure example, or after a better installation script/guide is done and change the installation path correspondingly.

I'm also considering adding a up-to-date and more completed configuration example recently. Currently I'm working on adding Windows support, so when I'll work for this is unsure though.

[anoduck]

Currently I'm working on adding Windows support

But why? ...jk 😆

[XOR-op]

Because I also have some Windows machines and I want to control their network activities :)

[anoduck]

Repo is here: https://github.com/anoduck/BoltConn-Docs

---

Is it just me or is this socks5 proxy being assigned three different ports? Also, which one is being assigned to which end?

enable-tun: false
http: 1080
socks5:
  - 2000
  - host: 0.0.0.0
    port: 8080
  - port: 3000
    auth:
      alice: bob
      browser: none

[XOR-op]

@anoduck Thanks for your work! Would you mind creating a new Pull Request to this repository and put them under /docs? In this way it's easy to correct mistakes and be updated for the future change, and you will also be credited for your contribution. (A small reminder is that you may want to use the no-reply email linked to your github account for the proper credit.)

As for the socks5 inbound, BoltConn supports listening on multiple ports simutaneously, and each port can be configured with authentication individually. With this design, we can use INBOUND rule to match different policies to different applications (e.g. Firefox multi-account containers can configure proxy individually, but we cannot use PROCESS-* rules to distinguish them since they have the same process information). Their functionalities are identical, and the main reason to use them is to use with INBOUND rule conjunctively.

[anoduck]

@anoduck Thanks for your work! Would you mind creating a new Pull Request to this repository and put them under /docs? In this way it's easy to correct mistakes and be updated for the future change, and you will also be credited for your contribution. (A small reminder is that you may want to use the no-reply email linked to your github account for the proper credit.)

Do you want me to merge it into the pre-existing docs, or do you want me to set it up so you can use it as submodule? The latter would allow you to separate the version management of the docs from BoltConn itself. Just something to think about.

[XOR-op]

I prefer the former one. To me, putting documentations and examples together with code is not a bad idea for most open-source project (except some extremely large project like kubernetes), and it's easier to release a new version with corresponding documentations. Feel free to overwrite the existing outdated documentations.

[anoduck]

Alright, I am forking, merging, and pr-ing.

Still need to finish the write-up for rules, interceptors, and one other thing that slips the mind.