mirror of
https://github.com/safedep/pmg.git
synced 2026-08-03 07:24:09 +02:00
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>
This commit is contained in:
Abhisek Datta
@@ -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.
|
||||
+73
-3
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user