From f333cb1a2beba2558a974e395383c7bf148bc224 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Thu, 1 Dec 2022 12:59:53 -0800 Subject: [PATCH 1/3] docs: Defend install.sh Closes #149 --- README.md | 16 ++++++++-- ci/fmt.sh | 3 ++ ci/release/_install.sh | 6 ++++ ci/release/changelogs/next.md | 2 +- ci/release/changelogs/template.md | 2 +- docs/INSTALL.md | 52 ++++++++++++++++++++++++++----- install.sh | 6 ++++ 7 files changed, 75 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 2bb844ccf..36e20ec24 100644 --- a/README.md +++ b/README.md @@ -98,14 +98,24 @@ curl -fsSL https://d2lang.com/install.sh | sh -s -- You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. -To uninstall: +Or if you have Go installed you can install from source though you won't get the manpage: + +```sh +go install oss.terrastruct.com/d2@latest +``` + +To uninstall with the install script: ```sh curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall ``` -For detailed installation docs, with alternative methods and examples for each OS, see -[./docs/INSTALL.md](./docs/INSTALL.md). +For detailed installation docs, see [./docs/INSTALL.md](./docs/INSTALL.md). +We demonstrate alternative methods and examples for each OS. + +As well, the functioning of the install script is described in detail to alleviate any +concern of its use. We recommend using your OS's package manager directly instead for +improved security but the install script is by no means insecure. ## D2 as a library diff --git a/ci/fmt.sh b/ci/fmt.sh index 75c1f1924..4fb39da34 100755 --- a/ci/fmt.sh +++ b/ci/fmt.sh @@ -6,4 +6,7 @@ cd -- "$(dirname "$0")/.." if is_changed README.md; then sh_c tocsubst --skip 1 README.md fi +if is_changed docs/INSTALL.md; then + sh_c tocsubst --skip 1 docs/INSTALL.md +fi ./ci/sub/fmt/make.sh diff --git a/ci/release/_install.sh b/ci/release/_install.sh index 49f936ffc..510a9c52d 100755 --- a/ci/release/_install.sh +++ b/ci/release/_install.sh @@ -91,6 +91,9 @@ note: Deleting the unarchived releases will cause --uninstall to stop working. You can rerun install.sh to update your version of D2. install.sh will avoid reinstalling if the installed version is the latest unless --force is passed. + +See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#security for +documentation on its security. EOF } @@ -506,4 +509,7 @@ brew() { HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@" } +# The main function does more than provide organization. It provides robustness in that if +# the install script was to only partial download into sh, sh will not execute it because +# main is not invoked until the very last byte. main "$@" diff --git a/ci/release/changelogs/next.md b/ci/release/changelogs/next.md index 4c6e6f979..bb3d79e4f 100644 --- a/ci/release/changelogs/next.md +++ b/ci/release/changelogs/next.md @@ -17,7 +17,7 @@ - `-b/--bundle` flag to `d2` now works and bundles all image assets directly as base64 data urls. [#278](https://github.com/terrastruct/d2/pull/278) -#### Improvements ๐Ÿ”ง +#### Improvements ๐Ÿงน - Local images can now be included, e.g. `icon: ./my_img.png`. [#146](https://github.com/terrastruct/d2/issues/146) diff --git a/ci/release/changelogs/template.md b/ci/release/changelogs/template.md index dd3f64b05..e5cf9fc34 100644 --- a/ci/release/changelogs/template.md +++ b/ci/release/changelogs/template.md @@ -1,5 +1,5 @@ #### Features ๐Ÿš€ -#### Improvements ๐Ÿ”ง +#### Improvements ๐Ÿงน #### Bugfixes ๐Ÿ”ด diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 95d677851..d128de725 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -3,13 +3,12 @@ You may install D2 through any of the following methods. - -- [install.sh](#installsh) -- [macOS (Homebrew)](#macos-homebrew) -- [Standalone](#standalone) -- [From source](#from-source) - - +- install.sh + - Security +- macOS (Homebrew) +- Standalone +- From source +- Coming soon ## install.sh @@ -31,6 +30,37 @@ methods: curl -fsSL https://d2lang.com/install.sh | sh -s -- --help ``` +### Security + +The install script is not the most secure way to install d2. We recommend that if +possible, you use your OS's package manager directly or install from source with `go` as +described below. + +But this does not mean the install script is insecure. There is no major flaw that +the install script is more vulnerable to than any other method of manual installation. +The most secure installation method involves a second independent entity, i.e your OS +package repos or Go's proxy server. + +We're careful shell programmers and are aware of the many footguns of the unix shell. Our +script was written carefully and with detail. For example, it is not vulnerable to partial +execution and the entire script runs with `set -eu` and very meticulous quoting. + +It follows the XDG standards, installs d2 properly into a unix hierarchy path (defaulting +to /usr/local though you can use ~/.local to avoid sudo if you'd like) and allows for easy +uninstall. + +Some other niceties are that it'll tell you if you need to adjust `$PATH` or `$MANPATH` to +access d2 and its manpages. It can also install +[TALA](https://github.com/terrastruct/tala) for you with `--tala`. You can also use it to +install a specific version of `d2` with `--version`. Run it with `--help` for more more +detailed docs on its various options and features. + +If you're still concerned, remember you can run with `--dry-run` to avoid executing +anything permanent. + +The install script does not yet verify any signature on the downloaded release +but that is coming soon. [#315](https://github.com/terrastruct/d2/issues/315) + ## macOS (Homebrew) If you're on macOS, you can install with `brew`. @@ -86,6 +116,14 @@ You can always install from source: go install oss.terrastruct.com/d2@latest ``` +To install a proper release from source clone the repository and then: + +```sh +./ci/release/build.sh --install +# To uninstall: +# ./ci/release/build.sh --uninstall +``` + ## Coming soon - Docker image diff --git a/install.sh b/install.sh index a951260b4..f6f1c4620 100755 --- a/install.sh +++ b/install.sh @@ -576,6 +576,9 @@ note: Deleting the unarchived releases will cause --uninstall to stop working. You can rerun install.sh to update your version of D2. install.sh will avoid reinstalling if the installed version is the latest unless --force is passed. + +See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#security for +documentation on its security. EOF } @@ -991,4 +994,7 @@ brew() { HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@" } +# The main function does more than provide organization. It provides robustness in that if +# the install script was to only partial download into sh, sh will not execute it because +# main is not invoked until the very last byte. main "$@" From 116151cc823d152356bcb5452324ee00764abd99 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Thu, 1 Dec 2022 13:14:09 -0800 Subject: [PATCH 2/3] INSTALL.md: Demonstrate minimal script to install standalone release Closes #150 --- ci/release/changelogs/next.md | 4 ++-- ci/release/changelogs/template.md | 4 ++-- docs/INSTALL.md | 31 +++++++++++++++++++++++++++---- 3 files changed, 31 insertions(+), 8 deletions(-) diff --git a/ci/release/changelogs/next.md b/ci/release/changelogs/next.md index bb3d79e4f..6446165c6 100644 --- a/ci/release/changelogs/next.md +++ b/ci/release/changelogs/next.md @@ -1,4 +1,4 @@ -#### Features ๐Ÿš€ +#### Features ๐Ÿ’ธ - Formatting of d2 scripts is supported on the CLI with the `fmt` subcommand. [#292](https://github.com/terrastruct/d2/pull/292) @@ -32,7 +32,7 @@ - `BROWSER=0` now works to disable opening a browser on `--watch`. [#311](https://github.com/terrastruct/d2/pull/311) -#### Bugfixes ๐Ÿ”ด +#### Bugfixes โ›‘๏ธ - 3D style was missing border and other styles for its top and right faces. [#187](https://github.com/terrastruct/d2/pull/187) diff --git a/ci/release/changelogs/template.md b/ci/release/changelogs/template.md index e5cf9fc34..131061b70 100644 --- a/ci/release/changelogs/template.md +++ b/ci/release/changelogs/template.md @@ -1,5 +1,5 @@ -#### Features ๐Ÿš€ +#### Features ๐Ÿ’ธ #### Improvements ๐Ÿงน -#### Bugfixes ๐Ÿ”ด +#### Bugfixes โ›‘๏ธ diff --git a/docs/INSTALL.md b/docs/INSTALL.md index d128de725..efc1e948b 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -7,6 +7,8 @@ You may install D2 through any of the following methods. - Security - macOS (Homebrew) - Standalone + - Manual + - PREFIX - From source - Coming soon @@ -76,8 +78,28 @@ brew install d2 ## Standalone We publish standalone release archives for every release on Github. -Download the `.tar.gz` release for your OS/ARCH combination and then run the following -inside the extracted directory to install: + +Here's a minimal example script that downloads a standalone release, extracts it into the +current directory and then installs it. +Adjust VERSION, OS, and ARCH as needed. + +```sh +VERSION=v0.0.13 OS=macos ARCH=amd64 curl -fsSLO \ + "https://github.com/terrastruct/d2/releases/download/$VERSION/d2-$VERSION-$OS-$ARCH.tar.gz" \ + && tar -xzf "d2-$VERSION-$OS-$ARCH.tar.gz" \ + && make -sC "d2-$VERSION" install +``` + +To uninstall: + +```sh +VERSION=v0.0.13 make -sC "d2-$VERSION" uninstall +``` + +### Manual + +You can also manually download the `.tar.gz` release for your OS/ARCH combination and then +run the following inside the extracted directory to install: ```sh make install @@ -89,10 +111,11 @@ Run the following to uninstall: make uninstall ``` -If root permissions are required for installation, you'll need to run `make` with `sudo`. +### PREFIX + You can control the Unix hierarchy installation path with `PREFIX=`. For example: -``` +```sh # Install under ~/.local. # Binaries will be at ~/.local/bin # And manpages will be under ~/.local/share/man From 9dede51973d420f704732e3dcf2a21a6b1f073a8 Mon Sep 17 00:00:00 2001 From: Anmol Sethi Date: Thu, 1 Dec 2022 13:23:20 -0800 Subject: [PATCH 3/3] doc/INSTALL.md: Backquote d2 --- docs/INSTALL.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index efc1e948b..97ec69d1b 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,6 +1,6 @@ # install -You may install D2 through any of the following methods. +You may install `d2` through any of the following methods. - install.sh @@ -43,22 +43,21 @@ the install script is more vulnerable to than any other method of manual install The most secure installation method involves a second independent entity, i.e your OS package repos or Go's proxy server. -We're careful shell programmers and are aware of the many footguns of the unix shell. Our +We're careful shell programmers and are aware of the many footguns of the Unix shell. Our script was written carefully and with detail. For example, it is not vulnerable to partial execution and the entire script runs with `set -eu` and very meticulous quoting. -It follows the XDG standards, installs d2 properly into a unix hierarchy path (defaulting +It follows the XDG standards, installs `d2` properly into a Unix hierarchy path (defaulting to /usr/local though you can use ~/.local to avoid sudo if you'd like) and allows for easy uninstall. Some other niceties are that it'll tell you if you need to adjust `$PATH` or `$MANPATH` to -access d2 and its manpages. It can also install +access `d2` and its manpages. It can also install [TALA](https://github.com/terrastruct/tala) for you with `--tala`. You can also use it to install a specific version of `d2` with `--version`. Run it with `--help` for more more detailed docs on its various options and features. -If you're still concerned, remember you can run with `--dry-run` to avoid executing -anything permanent. +If you're still concerned, remember you can run with `--dry-run` to avoid writing anything. The install script does not yet verify any signature on the downloaded release but that is coming soon. [#315](https://github.com/terrastruct/d2/issues/315)