docs: Add trust doc (#118)

* docs: Add trust doc

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Abhisek Datta <abhisek.datta@gmail.com>

---------

Signed-off-by: Abhisek Datta <abhisek.datta@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

README.md

@@ -27,10 +27,14 @@ See [example](https://safedep.io/malicious-npm-package-express-cookie-parser/)
 Install `pmg` using Homebrew:
 
 ```shell
+# MacOS/Linux with Homebrew
 brew install safedep/tap/pmg
+
+# Other platforms
+npm install -g @safedep/pmg
 ```
 
-**Note**: More [installation options](#installation) are available.
+**Note**: More [installation options](#installation) are available. See [why and how to trust PMG](docs/trust.md).
 
 Set up `pmg` to protect your development environment from malicious packages:
 

docs/config.md

@@ -0,0 +1,15 @@
+# Configuration
+
+PMG supports local configuration through a configuration file. To create the default configuration file, run:
+
+```bash
+pmg setup install
+```
+
+To see the configuration file path and activated configuration, run:
+
+```bash
+pmg setup info
+```
+
+See [config template](../config/config.template.yml) for the configuration schema.

docs/sandbox.md

@@ -1,6 +1,7 @@
 # Sandbox
 
-Design goal for sandbox in PMG context is to protect against unknown supply chain attacks using principle of least privilege.
+PMG sandbox design goal is to protect against unknown supply chain attacks using principle of least privilege.
+
 We do not want to re-invent sandbox and likely rely on OS native sandbox primitives. This is at the cost of developer experience,
 where we have to work within the limitations of the sandbox implementations that we use.
 
@@ -9,13 +10,14 @@ where we have to work within the limitations of the sandbox implementations that
 - Make sure sandbox is enabled in your `config.yml` file.
 - Make sure sandbox profiles are configured for the package managers you want to sandbox. 
   
-See [config/config.template.yml](../config/config.template.yml) for the configuration schema.
+See [configuration](./config.md) and [config/config.template.yml](../config/config.template.yml) for the configuration schema.
+Once sandbox is enabled, you can run package manager commands with sandbox protection.
 
 ```bash
 pmg npm install express
 ```
 
-Explicitly enable sandbox:
+Explicitly enable sandbox if not enabled in the `config.yml` file:
 
 ```bash
 pmg --sandbox --sandbox-profile=npm-restrictive npm install express
@@ -27,6 +29,74 @@ Run sandbox with custom policy file:
 pmg --sandbox --sandbox-profile=/path/to/custom-policy.yml npm install express
 ```
 
+<details>
+<summary>Custom policy overrides using Policy Templates</summary>
+
+Policy templates allow custom policy overrides. To setup custom policy overrides for your package manager,
+start by looking up the PMG configuration directory:
+
+```bash
+pmg setup info
+```
+
+Create a new policy template file in the PMG configuration directory and edit it to suit your needs:
+
+```bash
+# Set the PMG configuration directory
+export PMG_CONFIG_DIR="/path/to/pmg/config/dir"
+
+# Create the policy template file
+cat > $PMG_CONFIG_DIR/sandbox-custom-policy.yml <<EOF
+name: pnpm-macos-custom-sandbox
+description: Custom profile for pnpm in MacOS
+inherits: npm-restrictive
+
+package_managers:
+  - pnpm
+
+allow_pty: true
+
+filesystem:
+  allow_write:
+    # pnpm i need write access here
+    - ${HOME}/Library/pnpm/.tools/**
+
+    # pnpm i creates these tmp files in local dir, at least on MacOS
+    - ${CWD}/_tmp_*
+
+    # pnpm self-update (or likely update) creates temporary package.json files
+    # for writing. This is likely for atomic update using filesystem rename operation
+    # which guarantees atomicity
+    - ${CWD}/package.json.*
+
+    # Need access for dependency resolution
+    - ${CWD}/.pnpm-store
+
+  # Additional deny rules for extra security
+  deny_write:
+    - ${CWD}/.env
+    - ${CWD}/.env.*
+EOF
+```
+
+Edit PMG configuration file to use the custom policy template and override the default
+policy for your package manager:
+
+```yaml
+policy_templates:
+  pnpm-macos-custom-sandbox:
+    path: ./sandbox-custom-policy.yml
+
+policies:
+  pnpm:
+    enabled: true
+    profile: pnpm-macos-custom-sandbox
+```
+
+Next time you run `pmg pnpm install`, the custom policy template will be used instead of the default policy.
+
+</details>
+
 ## Supported Platforms
 
 | Platform | Supported | Implementation                     |

docs/trust.md

@@ -0,0 +1,75 @@
+# Trust
+
+PMG exists to protect developers from malicious open source packages. This effectively means:
+
+1. Open source packages are not *implicitly* trusted
+2. PMG need to be trusted to block malicious packages
+
+The assertion in [2] cannot be *implicit*. If so, it breaks the entire security and trust model. 
+
+## Security Goals
+
+- Adopt software supply chain security best practices so that PMG users can *verify* and only then trust PMG
+- PMG is open source, built in public and reviewed by the community for trust in code
+- PMG leverages GitHub build attestation to verify the integrity of the PMG binary with source provenance
+- PMG npm package has build attestation to verify the integrity of the PMG binary and build environment with source provenance
+- PMG security model is multi-layered without single point of failure
+
+## Verified Installation
+
+Zero-friction installation options are available in [README](../README.md). However, for more control, you can install PMG manually
+after verifying the integrity of the PMG binary. Verified installations allow you to:
+
+- Verify the integrity of the PMG binary and identify the exact source code that was used to build the binary
+- Manually review the source code for trust
+- Build your own binary from source or download a pre-built binary with source provenance guarantee
+
+### GitHub Release
+
+Get the latest attested version of PMG release binaries using GitHub CLI:
+
+```bash
+gh release verify -R safedep/pmg
+```
+
+Optionally, you can checkout the source code from which the binary was built and review the code for trust.
+
+```bash
+export RELEASE_TAG=$(gh release view -R safedep/pmg --json tagName --jq .tagName)
+
+gh repo clone safedep/pmg && \
+cd pmg && \
+git checkout $RELEASE_TAG
+```
+
+Install verified binary for your platform:
+
+```bash
+gh release download $RELEASE_TAG -R safedep/pmg --dir ./pmg-$RELEASE_TAG 
+```
+
+Install the platform specific binary from `./$pmg-$RELEASE_TAG`. To see binary specific attestation metadata, run:
+
+```bash
+gh attestation verify pmg_Linux_x86_64.tar.gz -R safedep/pmg --format json
+```
+
+### npm Release
+
+Verify npm package was built on GitHub Actions:
+
+```bash
+npm view @safedep/pmg --json
+```
+
+Navigate to [npm package](https://www.npmjs.com/package/@safedep/pmg) to verify the package provenance.
+
+## Security Model
+
+PMG aims to provide a multi-layered security model to avoid single point of trust or failure. PMG's security
+model consists of the following layers:
+
+1. Threat Intelligence (provided by [SafeDep](https://safedep.io) with planned support for BYO adapters)
+2. Policy as Code (Planned CEL policy based guardrails to prevent known bad practices)
+3. Sandbox for enforcing least privilege and defense in depth protection
+