From 902b1534a8176bcb540f08acedb86763f7e1a098 Mon Sep 17 00:00:00 2001 From: crschnick Date: Sun, 16 Apr 2023 23:06:59 +0000 Subject: [PATCH] Update read me --- DEVELOPMENT.md | 72 ++++++++++++++++++++++++++++++ README.md | 118 +++++++++++++------------------------------------ SECURITY.md | 6 +++ 3 files changed, 108 insertions(+), 88 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..62ea88ad --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,72 @@ +# Development + +Any contribution is welcomed! +There are no real formal contribution guidelines right now, they will maybe come later. + +## Repository Structure + +The following for modules make up the X-Pipe API and a licensed under the MIT license: + +- [core](core) - Shared core classes of the X-Pipe Java API, X-Pipe extensions, and the X-Pipe daemon implementation +- [beacon](beacon) - The X-Pipe beacon component is responsible for handling all communications between the X-Pipe + daemon + and the client applications, for example the various programming language APIs and the CLI + +The other modules make up the X-Pipe implementation and are licensed under GPL: + +- [app](app) - Contains the X-Pipe daemon implementation, the X-Pipe desktop application, and an + API to create all different kinds of extensions for the X-Pipe platform +- [dist](dist) - Tools to create a distributable package of X-Pipe +- [ext](ext) - Available X-Pipe extensions. Essentially every feature is implemented as an extension + +### Open source model + +X-Pipe utilizes an open core model, which essentially means that +the main application is open source while certain other components are not. +Select parts are not open source yet, but may be added to this repository in the future. +Some tests and especially test environments and that run on private servers +are also not included in this repository (Don't want to leak server information). +Finally, scripts and workflows to create and publish installers and packages +are also not included to prevent attackers from easily impersonating the X-Pipe application. + +## Modularity + +All X-Pipe components target [JDK 19](https://openjdk.java.net/projects/jdk/19/) and make full use of the Java Module System (JPMS). +All components are modularized, including all their dependencies. +In case a dependency is (sadly) not modularized yet, module information is manually added using [moditect](https://github.com/moditect/moditect-gradle-plugin). +Further, note that as this is a pretty complicated Java project that fully utilizes modularity, +many IDEs still have problems building this project properly. +For example, you can't build this project in eclipse or vscode as it will complain about missing modules. +The tested and recommended IDE is IntelliJ. + +## Setup + +You need to have an up-to-date version of X-Pipe installed on your local system in order to properly +run X-Pipe in a development environment. +This is due to the fact that some components are only included in the release version and not in this repository. +X-Pipe is able to automatically detect your local installation and fetch the required +components from it when it is run in a development environment. + +## Building and Running + +You can use the gradle wrapper to build and run the project: +- `gradlew app:run` will run the desktop application. You can set various useful properties in `app/build.gradle` +- `gradlew dist` will create a distributable production version in `dist/build/dist/base`. +- `gradlew :test` will run the tests of the specified project. + +You are also able to properly debug the built production application through two different methods: +- The `app/scripts/xpiped_debug` script will launch the application in debug mode and with a console attached to it +- The `app/scripts/xpiped_debug_attach` script attaches a debugger with the help of [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme). + Just make sure that the attachme process is running within IntelliJ, and the debugger should launch automatically once you start up the application. + +Note that when any unit test is run using a debugger, the X-Pipe daemon process that is started will also attempt +to connect to that debugger through [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme) as well. + +## FAQ + +#### Why are there no GitHub actions workflows in this repository? + +There are several test workflows run in a private environment as they use private test connections +such as remote server connections and database connections. +Other private workflows are responsible for packaging, signing, and distributing the releases. +So you can assume that the code is tested! diff --git a/README.md b/README.md index 5e7bd093..c0d60d26 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,22 @@ drawing -### A smart connection manager and remote file explorer +### A flexible connection manager and remote file explorer -X-Pipe is a brand-new type of connection manager and remote file explorer that works by exclusively interacting with CLI tools on local and remote shell connections. -This approach makes it much more flexible as it doesn't have to deal with file system APIs or remote file handling protocols at all. +X-Pipe is a brand-new type of connection manager and remote file explorer that works by only interacting with established command-line +tools on local and remote shell connections. +This approach makes it much more flexible as it doesn't have to deal with file system APIs or remote file handling +protocols at all. -X-Pipe integrates with your existing tools and workflows -by outsourcing as many tasks as possible to your +It currently supports: +- Containers located on any host, e.g. [docker](https://www.docker.com/) or [LXD](https://linuxcontainers.org/lxd/introduction/) container instances +- [SSH](https://www.ssh.com/academy/ssh/protocol) connections +- [Windows Subsystem for Linux](https://ubuntu.com/wsl) instances located on any host +- [Powershell Remote Sessions](https://learn.microsoft.com/en-us/powershell/scripting/learn/remoting/running-remote-commands?view=powershell-7.3) +- Any other custom remote connection methods that works through the command-line +- Arbitrary types of proxies to establish connections + +Furthermore, X-Pipe integrates with your existing tools and workflows +by outsourcing as many tasks as possible to your favourite text/code editors, terminals, shells, command-line tools and more. The platform is designed to be extensible, allowing anyone to implement custom functionality through extensions. @@ -19,106 +29,38 @@ Head over to the [releases page](https://github.com/xpipe-io/xpipe/releases/late ### Remote file explorer -- Access files on any remote system +- Access the file system of any remote system - Quickly open a terminal into any directory - Run commands from the explorer interface - Utilize your favourite local programs to open and edit remote files -drawing +Remote file explorer -### Flexible remote connector - -- Can connect to standard servers, database servers, and more -- Supports established protocols like SSH and more -- Also works on non-protocol-based shell connections like docker, WSL, LXD, and more plus any custom connection methods that work through the command-line -- Is able to integrate all kinds of proxies into the connection process - -### Manage all your connections in one place +### Connection manager - Easily create and manage all kinds of remote connections at one location -- Securely stores all information exclusively on your computer and encrypts all secret information. See the [security page](/SECURITY.md) for more info +- Securely stores all information exclusively on your computer and encrypts all secret information. See + the [security page](/SECURITY.md) for more info - Create desktop shortcuts to automatically open your connections in your terminal -drawing +Connection manager ### Instant launch for remote shells and commands - Automatically login into a shell in your favourite terminal with one click (no need to fill password prompts, etc.) -- Works for all kinds of shells. This includes command shells (e.g. bash, PowerShell, cmd, etc.) and database shells (e.g. PostgreSQL Shell) +- Works for all kinds of shells. This includes command shells (e.g. bash, PowerShell, cmd, etc.) and database shells ( + e.g. PostgreSQL Shell) - Comes with integrations for all commonly used terminals for all operating systems - Allows you to customize the launched shell's init environment - Launches from the GUI or command-line -## Community +## Further information + +In case you're interested in development, check out the [development page](/DEVELOPMENT.md). + +For information about the security model of X-Pipe, see the [security page](/SECURITY.md). + +If you want to talk you can also join: -There are several ways to reach out in case you encounter any issues or questions: - The [X-Pipe Discord Server](https://discord.gg/8y89vS8cRb) - The [X-Pipe Slack Server](https://join.slack.com/t/x-pipe/shared_invite/zt-1awjq0t5j-5i4UjNJfNe1VN4b_auu6Cg) - -## Repository Structure - -The following for modules make up the X-Pipe API and a licensed under the MIT license: -- [core](core) - Shared core classes of the X-Pipe Java API, X-Pipe extensions, and the X-Pipe daemon implementation -- [beacon](beacon) - The X-Pipe beacon component is responsible for handling all communications between the X-Pipe daemon - and the client applications, for example the various programming language APIs and the CLI - -The other modules make up the X-Pipe implementation and are licensed under GPL: -- [app](app) - Contains the X-Pipe daemon implementation, the X-Pipe desktop application, and an - API to create all different kinds of extensions for the X-Pipe platform -- [dist](dist) - Tools to create a distributable package of X-Pipe -- [ext](ext) - Available X-Pipe extensions. Essentially every feature is implemented as an extension - -### Open source model - -X-Pipe utilizes an open core model, which essentially means that -the main application is open source while certain other components are not. -Select parts are not open source yet, but may be added to this repository in the future. -Some tests and especially test environments and that run on private servers -are also not included in this repository (Don't want to leak server information). -Finally, scripts and workflows to create and publish installers and packages -are also not included to prevent attackers from easily impersonating the X-Pipe application. - -## Development - -Any contribution is welcomed! -There are no real formal contribution guidelines right now, they will maybe come later. - -### Modularity - -All X-Pipe components target [JDK 19](https://openjdk.java.net/projects/jdk/19/) and make full use of the Java Module System (JPMS). -All components are modularized, including all their dependencies. -In case a dependency is (sadly) not modularized yet, module information is manually added using [moditect](https://github.com/moditect/moditect-gradle-plugin). -Further, note that as this is a pretty complicated Java project that fully utilizes modularity, -many IDEs still have problems building this project properly. -For example, you can't build this project in eclipse or vscode as it will complain about missing modules. -The tested and recommended IDE is IntelliJ. - -### Setup - -You need to have an up-to-date version of X-Pipe installed on your local system in order to properly -run X-Pipe in a development environment. -This is due to the fact that some components are only included in the release version and not in this repository. -X-Pipe is able to automatically detect your local installation and fetch the required -components from it when it is run in a development environment. - -### Building and Running - -You can use the gradle wrapper to build and run the project: -- `gradlew app:run` will run the desktop application. You can set various useful properties in `app/build.gradle` -- `gradlew dist` will create a distributable production version in `dist/build/dist/base`. -- `gradlew :test` will run the tests of the specified project. - -You are also able to properly debug the built production application through two different methods: -- The `app/scripts/xpiped_debug` script will launch the application in debug mode and with a console attached to it -- The `app/scripts/xpiped_debug_attach` script attaches a debugger with the help of [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme). - Just make sure that the attachme process is running within IntelliJ, and the debugger should launch automatically once you start up the application. - -Note that when any unit test is run using a debugger, the X-Pipe daemon process that is started will also attempt -to connect to that debugger through [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme) as well. - -#### Why are there no GitHub actions workflows in this repository? - -There are several test workflows run in a private environment as they use private test connections -such as remote server connections and database connections. -Other private workflows are responsible for packaging, signing, and distributing the releases. -So you can assume that the code is tested! diff --git a/SECURITY.md b/SECURITY.md index b98701ef..0ebfbbd1 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -77,6 +77,12 @@ other information stored by X-Pipe that is not explicitly sent to that host. During development, a lot of focus lies on preventing all sorts of attacks like injection attacks from the remote host +## Issue reports + +Whenever an error occurs within X-Pipe or you choose to open the error reporter dialog, +you have the option to automatically send an error report with optional feedback and attachments. +This error report does not contain any sensitive information + ## Reporting a security vulnerability If you believe that there is a security vulnerability in X-Pipe,