docs: "Getting started" manual updates (#5835)

1 files changed, 42 insertions, 4 deletions

diff --git a/docs/getting_started/permissions.md b/docs/getting_started/permissions.md
index c5880225a..317d85046 100644
--- a/docs/getting_started/permissions.md
+++ b/docs/getting_started/permissions.md
@@ -1,15 +1,50 @@
 ## Permissions
 
-<!-- TODO(lucacasonato): what are permissions -->
+Deno is secure by default. Therefore, unless you specifically enable it, a deno
+module has no file, network, or environment access for example. Access to
+security sensitive areas or functions requires the use of permissions to be
+granted to a deno process on the command line.
 
-<!-- TODO(lucacasonato): description of all permissions -->
+For the following example, `mod.ts` has been granted read-only access to the
+file system. It cannot write to it, or perform any other security sensitive
+functions.
+
+```shell
+deno run --allow-read mod.ts
+```
+
+### Permissions list
+
+The following permissions are available:
+
+- **-A, --allow-all** Allow all permissions. This disables all security.
+- **--allow-env** Allow environment access for things like getting and setting
+  of environment variables.
+- **--allow-hrtime** Allow high resolution time measurement. High resolution
+  time can be used in timing attacks and fingerprinting.
+- **--allow-net=\<allow-net\>** Allow network access. You can specify an
+  optional, comma separated list of domains to provide a whitelist of allowed
+  domains.
+- **--allow-plugin** Allow loading plugins. Please note that --allow-plugin is
+  an unstable feature.
+- **--allow-read=\<allow-read\>** Allow file system read access. You can specify
+  an optional, comma separated list of directories or files to provide a
+  whitelist of allowed file system access.
+- **--allow-run** Allow running subprocesses. Be aware that subprocesses are not
+  run in a sandbox and therefore do not have the same security restrictions as
+  the deno process. Therefore, use with caution.
+- **--allow-write=\<allow-write\>** Allow file system write access. You can
+  specify an optional, comma separated list of directories or files to provide a
+  whitelist of allowed file system access.
 
 ### Permissions whitelist
 
-Deno also allows you to control the granularity of permissions with whitelists.
+Deno also allows you to control the granularity of some permissions with
+whitelists.
 
 This example restricts file system access by whitelisting only the `/usr`
-directory:
+directory, however the execution fails as the process was attempting to access a
+file in the `/etc` directory:
 
 ```shell
 $ deno run --allow-read=/usr https://deno.land/std/examples/cat.ts /etc/passwd
@@ -41,6 +76,9 @@ This is an example on how to whitelist hosts/urls:
 $ deno run --allow-net=github.com,deno.land fetch.ts
 ```
 
+If `fetch.ts` tries to establish network connections to any other domain, the
+process will fail.
+
 Allow net calls to any host/url:
 
 ```shell