From adf36e747c7734f7067d9bab1772ca69b4f20a9e Mon Sep 17 00:00:00 2001 From: QuanTH Date: Mon, 5 Oct 2020 10:52:43 +0700 Subject: [PATCH 1/5] JAMES-3400 Architecture Decision Record for new James CLI --- src/adr/0042-james-cli-based-on-webadmin.md | 75 +++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 src/adr/0042-james-cli-based-on-webadmin.md diff --git a/src/adr/0042-james-cli-based-on-webadmin.md b/src/adr/0042-james-cli-based-on-webadmin.md new file mode 100644 index 00000000000..2a756b563a5 --- /dev/null +++ b/src/adr/0042-james-cli-based-on-webadmin.md @@ -0,0 +1,75 @@ +# 42. James CLI based on webadmin API +Date: 2020-10-05 + +## Status +Accepted (lazy consensus). + + ## Context + +James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands. + +Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember. + +Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers. + +Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface. + +## Decision + +We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http. + +* What libraries will we use? + + * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it. + + * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions. + +* How will we limit breaking changes this new CLI will cause? + + * Work on a wrapper to adapt the old CLI API. + +* Where will we locate this cli code? + + * server/protocols/webadmin-cli + +* We decided to adopt a more modern, modular CLI syntax: + +``` +$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT} +``` +where + + OPTION: optional parameter when running the command line, + + ENTITY: represents the entity to perform action on, + + ACTION: name of the action to perform, + + ARGUMENT: arguments needed for the action. + +#### Examples + +Add a domain to the domain list. +``` +$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated +``` + +In above command-line + + OPTION: --url http://127.0.0.1 --port 9999 + + ENTITY: domain + + ACTION: create + + ARGUMENT: domainNameToBeCreated + + +## Consequences + +It aims at providing a more modern and more secure CLI, also bringing compatibility ability with old CLI. + +## References +* [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628) +* [Picocli 2.0: Do More With Less](https://dzone.com/articles/whats-new-in-picocli-20) +* [Picocli Homepage](https://picocli.info/) \ No newline at end of file From b72b6a50fc7681ec6803815d5aff447c146f8570 Mon Sep 17 00:00:00 2001 From: QuanTH Date: Mon, 5 Oct 2020 16:47:19 +0700 Subject: [PATCH 2/5] JAMES-3400 Add README.md for James CLI based on webadmin endpoints. --- server/protocols/webadmin-cli/README.md | 128 ++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 server/protocols/webadmin-cli/README.md diff --git a/server/protocols/webadmin-cli/README.md b/server/protocols/webadmin-cli/README.md new file mode 100644 index 00000000000..01baaea236b --- /dev/null +++ b/server/protocols/webadmin-cli/README.md @@ -0,0 +1,128 @@ +# A WebAdmin based CLI for Apache James + +## Development + +Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface. It also aims at providing a more modern and intuitive interface. + +## Run the command line + +## Syntax + +General syntax to run the command line + +``` +$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT} +``` + +where + + OPTION: optional parameter when running the command line, + + ENTITY: represents the entity to perform action on, + + ACTION: name of the action to perform, + + ARGUMENT: arguments needed for the action. + +Example: +``` +$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain list +``` + +The above command lists all domain names available on domain route at address http://127.0.0.1:9999. +It does not require any argument to execute. Options --url and --port are optional. Without them, the default value is http://127.0.0.0:8000. +As for other commands, arguments might be required after the sub-command (ACTION such as list, add and remove). + +Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here. + +## Navigation menu + +- [Manage Domains](#manage-domains) + - [Create a domain](#create-a-domain) + - [Delete a domain](#delete-a-domain) + - [Check if a domain exists](#check-if-a-domain-exists) + - [Get the list of domains](#get-the-list-of-domains) +- [Manage Users](#manage-users) + - [Create an user](#create-a-user) + - [Test an user existence](#test-a-user-existence) + - [Delete an user](#delete-a-user) + - [Get users list](#get-users-list) + - [Update an user password](#update-a-user-password) + +## Manage Domains + +### Create a domain +Add a domain to the domain list. +``` +{cli} domain create +``` +Resource name **domainToBeCreated**: + +- can not be null or empty +- can not contain ‘@’ +- can not be more than 255 characters +- can not contain ‘/’ + +### Delete a domain + +Remove a domain from the domain list. +``` +{cli} domain delete +``` +Note: Deletion of an auto-detected domain, default domain or of an auto-detected ip is not supported. We encourage you instead to review your [domain list configuration](https://james.apache.org/server/config-domainlist.html). + +### Check if a domain exists +Check whether a domain exists on the domain list or not. +``` +{cli} domain exist +``` + +### Get the list of domains +Show all domains' name on the list. +``` +{cli} domain list +``` + + + +## Manage Users + +### Create an user + +Add an user to the user list. +``` +{cli} user create +``` +Resource name representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html) + +Note: if the user exists already, its password will be updated. + +### Test an user existence + +Check whether an user exists on the user list or not. +``` +{cli} user exist +``` +Resource name representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html) + +### Delete an user + +Remove an user from the user list. +``` +{cli} user delete +``` + +### Get users list + +Show all users' name on the list. + +``` +{cli} user list +``` + +### Update an user password +Same as Create, but an user need to exist. + +If the user do not exist, then it will be created. + + From 63b99e49e0f310453c6ab8f0f0ee133e773bb25e Mon Sep 17 00:00:00 2001 From: QuanTH Date: Wed, 7 Oct 2020 13:53:54 +0700 Subject: [PATCH 3/5] JAMES-3400 fix some grammar errors --- src/adr/0042-james-cli-based-on-webadmin.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/adr/0042-james-cli-based-on-webadmin.md b/src/adr/0042-james-cli-based-on-webadmin.md index 2a756b563a5..7c7ea791cb4 100644 --- a/src/adr/0042-james-cli-based-on-webadmin.md +++ b/src/adr/0042-james-cli-based-on-webadmin.md @@ -1,10 +1,12 @@ # 42. James CLI based on webadmin API + Date: 2020-10-05 ## Status + Accepted (lazy consensus). - ## Context +## Context James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands. @@ -22,7 +24,7 @@ We decided to write a new CLI client, running on top of the JVM, communicating w * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it. - * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions. + * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework written in Java that allows us to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: no need to the follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions. * How will we limit breaking changes this new CLI will cause? From f60b7592c779ff542d05e2b3f655bf14b19cbc14 Mon Sep 17 00:00:00 2001 From: QuanTH Date: Wed, 7 Oct 2020 17:00:49 +0700 Subject: [PATCH 4/5] JAMES-3400 add man page and GraalVM decisions. --- src/adr/0042-james-cli-based-on-webadmin.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/adr/0042-james-cli-based-on-webadmin.md b/src/adr/0042-james-cli-based-on-webadmin.md index 7c7ea791cb4..d7d0061d244 100644 --- a/src/adr/0042-james-cli-based-on-webadmin.md +++ b/src/adr/0042-james-cli-based-on-webadmin.md @@ -34,6 +34,12 @@ We decided to write a new CLI client, running on top of the JVM, communicating w * server/protocols/webadmin-cli +* Distribute this CLI as a GraalVM native image. + +* Write a man page. + + * Picocli generates beautiful documentation for our CLI (HTML, PDF and Unix man pages). + * We decided to adopt a more modern, modular CLI syntax: ``` From 0f4d4e721eec61bfc41e082acaf6e3863dd1982a Mon Sep 17 00:00:00 2001 From: QuanTH Date: Wed, 7 Oct 2020 17:26:24 +0700 Subject: [PATCH 5/5] JAMES-3400 Change James command-line syntax. --- server/protocols/webadmin-cli/README.md | 22 ++++++++++----------- src/adr/0042-james-cli-based-on-webadmin.md | 7 ++++--- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/server/protocols/webadmin-cli/README.md b/server/protocols/webadmin-cli/README.md index 01baaea236b..3b4e5d08f79 100644 --- a/server/protocols/webadmin-cli/README.md +++ b/server/protocols/webadmin-cli/README.md @@ -11,7 +11,7 @@ Webadmin command-line interface is an upcoming replacement for the outdated, sec General syntax to run the command line ``` -$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT} +$ james-cli [OPTION] ENTITY ACTION {ARGUMENT} ``` where @@ -26,15 +26,13 @@ where Example: ``` -$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain list +$ james-cli --url http://127.0.0.1 --port 9999 domain list ``` The above command lists all domain names available on domain route at address http://127.0.0.1:9999. It does not require any argument to execute. Options --url and --port are optional. Without them, the default value is http://127.0.0.0:8000. As for other commands, arguments might be required after the sub-command (ACTION such as list, add and remove). -Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here. - ## Navigation menu - [Manage Domains](#manage-domains) @@ -54,7 +52,7 @@ Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} ### Create a domain Add a domain to the domain list. ``` -{cli} domain create +james-cli domain create ``` Resource name **domainToBeCreated**: @@ -67,20 +65,20 @@ Resource name **domainToBeCreated**: Remove a domain from the domain list. ``` -{cli} domain delete +james-cli domain delete ``` Note: Deletion of an auto-detected domain, default domain or of an auto-detected ip is not supported. We encourage you instead to review your [domain list configuration](https://james.apache.org/server/config-domainlist.html). ### Check if a domain exists Check whether a domain exists on the domain list or not. ``` -{cli} domain exist +james-cli domain exist ``` ### Get the list of domains Show all domains' name on the list. ``` -{cli} domain list +james-cli domain list ``` @@ -91,7 +89,7 @@ Show all domains' name on the list. Add an user to the user list. ``` -{cli} user create +james-cli user create ``` Resource name representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html) @@ -101,7 +99,7 @@ Note: if the user exists already, its password will be updated. Check whether an user exists on the user list or not. ``` -{cli} user exist +james-cli user exist ``` Resource name representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html) @@ -109,7 +107,7 @@ Resource name representing valid users, hence it should match the cri Remove an user from the user list. ``` -{cli} user delete +james-cli user delete ``` ### Get users list @@ -117,7 +115,7 @@ Remove an user from the user list. Show all users' name on the list. ``` -{cli} user list +james-cli user list ``` ### Update an user password diff --git a/src/adr/0042-james-cli-based-on-webadmin.md b/src/adr/0042-james-cli-based-on-webadmin.md index d7d0061d244..52b1c9dfd2d 100644 --- a/src/adr/0042-james-cli-based-on-webadmin.md +++ b/src/adr/0042-james-cli-based-on-webadmin.md @@ -43,7 +43,7 @@ We decided to write a new CLI client, running on top of the JVM, communicating w * We decided to adopt a more modern, modular CLI syntax: ``` -$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT} +$ james-cli [OPTION] ENTITY ACTION {ARGUMENT} ``` where @@ -59,7 +59,7 @@ where Add a domain to the domain list. ``` -$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated +$ james-cli --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated ``` In above command-line @@ -80,4 +80,5 @@ It aims at providing a more modern and more secure CLI, also bringing compatibil ## References * [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628) * [Picocli 2.0: Do More With Less](https://dzone.com/articles/whats-new-in-picocli-20) -* [Picocli Homepage](https://picocli.info/) \ No newline at end of file +* [Picocli Homepage](https://picocli.info/) +* [Native Image Maven Plugin](https://www.graalvm.org/reference-manual/native-image/NativeImageMavenPlugin/) \ No newline at end of file