SafeDep Documentation

PMG runs as a persistent proxy in CI/CD. The safedep/pmg action starts it once per job. The proxy intercepts installs from every supported package manager and blocks each package flagged as malicious. At the end of the job, the action stops the proxy, writes a job summary, and fails the job when PMG blocked a package.

In CI, PMG is non-interactive: flagged packages are always blocked, never prompted. For local development use the wrapped commands (pmg npm install) covered in the PMG quickstart.

Use the SafeDep PMG action

Add one safedep/pmg step right after actions/checkout. The job needs no other PMG step.

- uses: actions/checkout@v6

- uses: safedep/pmg@v0.34.0
  with:
    api-key: ${{ secrets.SAFEDEP_API_KEY }}
    tenant-id: ${{ secrets.SAFEDEP_TENANT_ID }}

- run: npm ci   # intercepted automatically

Put the action before the language setup steps, so the proxy sees the traffic of every later step. Use one safedep/pmg step per job. A second step fails, and the proxy of the first step keeps running. By default, the action runs the proxy in server mode. On a GitHub hosted runner, it also turns on kernel enforcement. Set timeout-minutes on the job. A proxy that stops serving holds the job until the timeout. PMG blocks malicious packages using SafeDep’s free community intelligence with or without credentials. Add the optional api-key and tenant-id to connect the run to SafeDep Cloud, so block events sync to Endpoint Hub before the runner is destroyed.

Use safedep/pmg@v0.34.0 or a later release tag. The post step, the job summary, and the fail-on-violation, auto-stop and baseline inputs need v0.34.0 and a runner that runs Node 24 actions. A self-hosted runner needs runner version 2.327.1 or later. The v1 tag points at an older action without these inputs. GitHub warns about an unknown input and runs the job without it.

Upgrade from v0.33.0 or earlier

Earlier releases needed a pmg proxy stop --fail-on-violation step at the end of the job. From v0.34.0, the post step of the action does this work. Remove the stop step. Server mode is the default, so the job no longer needs server-mode: true. A job that keeps its own stop step must set auto-stop: false. Otherwise the post step finds no proxy and fails the job, because a stop step could hide a block.

What happens at the end of the job

The action has a post step. GitHub runs it at the end of the job, also when an earlier step fails and when the job is cancelled. The post step:

Stops the proxy. With api-key, the proxy sends its last events to SafeDep Cloud.
Proposes a network profile from the hosts that the job reached. See Allow Only Known Hosts in GitHub Actions.
Writes the job summary. The summary shows the verdict, the number of blocked packages, each denied connection, and each destination host. The run also gets an annotation when PMG blocked a package, and one for each denial.
Fails the job when PMG blocked a package or the network policy denied a connection.

The fail-on-violation, auto-stop, and baseline inputs change the post step. See Inputs.

On a public repository, anyone can read the job summary. It lists the hosts that the job reached. Set baseline: false to leave them out. A denied connection still shows in the summary, with its host.

Example workflow

A full workflow that installs dependencies through PMG on every pull request:

install-dependencies.yml

name: Install Dependencies
on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  install-deps:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v6

      # Start PMG. The post step stops it and fails the job on a block.
      - uses: safedep/pmg@v0.34.0
        with:
          api-key: ${{ secrets.SAFEDEP_API_KEY }}
          tenant-id: ${{ secrets.SAFEDEP_TENANT_ID }}

      # Your usual language setup and install
      - uses: actions/setup-node@v6
        with:
          node-version: "24"

      - run: npm ci

See blocks from every pipeline

With the api-key and tenant-id inputs, the blocks from every job go to one tenant. To review them across all repositories, see Review Package Blocks Across CI Pipelines.

This needs the SafeDep Cloud Team or Enterprise plan. See pricing.

Enforce in the kernel

Proxy variables are a request that a process can ignore. A step that runs env -i, uses sudo, or calls an HTTP client of its own bypasses the proxy. Kernel enforcement makes the Linux kernel route every process on the runner through PMG. The enforce input is auto by default. The action enforces when the job runs on a GitHub hosted runner, on the runner host, with passwordless sudo. GitHub hosted Ubuntu runners meet these conditions. In a job container, on a self-hosted runner, or without sudo, the action runs the proxy without enforcement and says so in the log. Set enforce: true to fail the job where the runner cannot enforce. Set enforce: false to turn enforcement off.

- uses: safedep/pmg@v0.34.0
  with:
    enforce: true
    enforce-namespaces: redirect
    api-key: ${{ secrets.SAFEDEP_API_KEY }}
    tenant-id: ${{ secrets.SAFEDEP_TENANT_ID }}

- run: npm ci

enforce-namespaces: redirect also routes the containers that steps start, such as docker run and docker build. See Protect Docker builds and containers. The action installs the PMG CA into the system trust store, starts the proxy as root, and exports the trust variables. The post step stops the root proxy. A step that runs pmg as root uses the PMG_BIN and PMG_PROXY_STATE variables that the action exports:

- run: sudo "$PMG_BIN" proxy status --state "$PMG_PROXY_STATE"

The runner is not exempt. Its connections to GitHub go through the proxy, which passes them through with the real certificate. If the proxy stops serving but keeps running, the runner cannot report. GitHub then cancels the job after its timeout-minutes, and the post step does not run. The GitHub default is 360 minutes, so set a shorter timeout on every job. The enforce-* inputs set the policy without a config file. See Inputs. With enforce: auto, an enforce-* input fails the job where the action cannot enforce, so a runner change does not turn enforcement off without notice. For the policy keys and what enforcement does not cover, see Kernel Enforcement on Linux. To refuse every host that the job does not need, add a network policy. See Allow Only Known Hosts in GitHub Actions.

Protect Docker builds and containers

With enforce-namespaces: redirect, PMG also checks the packages that a container installs. This includes the RUN steps of docker build, docker run, and Docker actions. PMG reads the registry traffic with its own CA. A container that does not trust this CA fails the TLS handshake. The action exports the path of a CA bundle as PMG_CA_BUNDLE. The bundle holds the PMG CA and the public root CAs, so the other hosts still work. Give this file to each container that installs packages. For a build, pass the bundle as a build secret. The secret is not stored in the image.

docker-build.yml

name: Build Docker Image
on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v6

      - uses: safedep/pmg@v0.34.0
        with:
          enforce: true
          enforce-namespaces: redirect

      - uses: docker/setup-buildx-action@v4

      - uses: docker/build-push-action@v7
        with:
          context: .
          push: false
          tags: app:ci
          secret-files: pmg-ca=${{ env.PMG_CA_BUNDLE }}

Without docker/build-push-action, pass the same secret to the Docker CLI:

docker build --secret id=pmg-ca,src=$PMG_CA_BUNDLE -t app:ci .

In the Dockerfile, mount the secret in each RUN step that installs packages:

Dockerfile

FROM node:24-slim
WORKDIR /app
COPY package.json package-lock.json ./

# The bundle is present only when the build gets the pmg-ca secret.
# A build without the secret, such as a local build, uses the CAs of the image.
RUN --mount=type=secret,id=pmg-ca,target=/run/secrets/pmg-ca.pem,mode=0444 \
    if [ -f /run/secrets/pmg-ca.pem ]; then export NODE_EXTRA_CA_CERTS=/run/secrets/pmg-ca.pem; fi; \
    npm ci

COPY . .
CMD ["node", "index.js"]

mode=0444 is required. BuildKit mounts a secret that only root can read, and the install can run as a different user. Set the variable that your package manager reads:

Package manager	Variable
npm, pnpm	`NODE_EXTRA_CA_CERTS`
pip	`PIP_CERT`
uv, Go	`SSL_CERT_FILE`
Cargo	`CARGO_HTTP_CAINFO`

To give the bundle to a container at runtime, mount it in the container:

docker run
Docker action

docker run -v "$PWD":/app -w /app \
  -v "$PMG_CA_BUNDLE":/pmg-ca.pem:ro -e NODE_EXTRA_CA_CERTS=/pmg-ca.pem \
  node:24 npm ci

A Docker action can read files in the workspace, at /github/workspace. Copy the bundle there in a step before the action:

- run: cp "$PMG_CA_BUNDLE" pmg-ca.pem
- uses: some/docker-action@v1
  env:
    NODE_EXTRA_CA_CERTS: /github/workspace/pmg-ca.pem

Job containers and Docker actions

You need this setup only when the job runs in a job container. Kernel enforcement does not work in a job container. On a job without a job container, use enforce-namespaces: redirect instead. It sends Docker actions, docker:// steps, docker run, and docker build through PMG. See Protect Docker builds and containers.

In a job with a job container (jobs.<job_id>.container), the action and the proxy run inside that container, and run: steps reach the proxy at 127.0.0.1. A Docker action or a docker:// step runs in a different container on the job network, where 127.0.0.1 is its own loopback, so its connection to the proxy fails. Set expose-to-job-network to bind the proxy to the job container’s address on the job network:

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    container:
      image: node:24
      options: --init
    steps:
      - uses: actions/checkout@v6
      - uses: safedep/pmg@v0.34.0
        with:
          expose-to-job-network: true
      - run: npm ci
      - uses: docker://node:24
        with:
          args: npm ci

Every container on the job network can then reach the proxy, including service containers. The runner mounts /github/home in the job container and in Docker actions, so the exported CA path is valid in both. The action fails when the job has no job container, and it warns when HOME, XDG_CONFIG_HOME, or PMG_CONFIG_DIR moves the CA outside /github/home. The action needs a POSIX shell and common tools in the image, such as busybox, plus curl or wget. It does not need bash or Node in the image. Alpine images such as node:24-alpine work as they are. An Alpine job container on arm64 does not work, because the runner has no Node build for it.

Self-hosted runners

enforce: auto does not enforce on a self-hosted runner. Kernel enforcement adds the PMG CA to the trust store of the host, and the CA stays after the job. A host that more than one repository shares then trusts the PMG CA for every job. Set enforce: true on an ephemeral runner, or on a host that only trusted jobs use.

Deploy PMG one way on a runner host. Either use the safedep/pmg action in each workflow, or install PMG for the whole system and run the proxy as a service on the host. PMG does not support both on one host.

To run the proxy as a service on the host, see Kernel Enforcement on Linux. On that host, remove the safedep/pmg step from the workflows. One host proxy serves all jobs, so the jobs get no post step, no job summary, and no verdict for each job. The host proxy routes only the processes on the host. A job container, a Docker action, or a docker run step goes around it unless the proxy redirects containers and each container trusts the PMG CA. See Kernel Enforcement on Linux.

Action inputs and outputs

Inputs

An input that maps to a PMG_* variable or to a config key has no effect when you leave it empty. PMG then uses the value from config-file, or its own default.

Input	Default	Effect
`version`	`latest`	The PMG release to install, for example `v0.34.0`, or `latest`.
`cache`	`false`	Set `true` to keep the PMG binary in the runner tool cache. The action checks the cached file against the release checksum on each run.
`api-key`	Empty	The SafeDep Cloud API key. Set it with `tenant-id`, from a secret. With both inputs, the proxy sends its events to SafeDep Cloud. The action fails when you set only one of them.
`tenant-id`	Empty	The SafeDep Cloud tenant ID. Set it with `api-key`.
`endpoint-id`	`gha/<owner>/<repo>`	The name of the runner in SafeDep Cloud. Applies only with `api-key` and `tenant-id`.
`server-mode`	Empty (server mode)	Set `false` to use the PMG shims instead of the proxy. With shims, the job has no job summary and no kernel enforcement. `sandbox: true` also selects shims.
`fail-on-violation`	`true`	Fail the job at its end when PMG blocked a package or the network policy denied a connection. Set `false` to report a block without a failed job. When PMG cannot stop the proxy, for example after a crash, the job fails with every setting.
`auto-stop`	`true`	Stop the proxy in the post step. Set `false` when a step of the job stops the proxy.
`baseline`	`true`	Show the proposed network profile and the list of destination hosts in the job summary. Set `false` to leave them out.
`enforce`	`auto`	Kernel enforcement: `auto`, `true`, or `false`. See Enforce in the kernel.
`enforce-ports`	Empty	With enforcement, more destination ports that the kernel routes through the proxy.
`enforce-exempt-users`	Empty	With enforcement, users that the kernel never routes.
`enforce-exempt-executables`	Empty	With enforcement, programs that connect directly, as absolute paths or globs.
`enforce-skip-destinations`	Empty	With enforcement, CIDR prefixes that the kernel never routes.
`enforce-namespaces`	`ignore`	With enforcement, what happens to the containers that steps start: `ignore`, `redirect`, or `auto`. `redirect` fails the job when the runner cannot redirect them. `auto` redirects them where the runner can. See Protect Docker builds and containers.
`network-profile`	Empty	The network profile that the proxy applies, as a path in the repository or a built-in name. Turns on server mode, and fails with `server-mode: false`. See Allow Only Known Hosts in GitHub Actions.
`network-mode`	`audit`	With `network-profile`, what the proxy does with a denied destination: `audit` or `enforce`.
`expose-to-job-network`	`false`	In a job with a job container, bind the proxy to the address of the job container on the job network. The action fails when the job has no job container. Ignored with `enforce: true`. See Job containers and Docker actions.
`paranoid`	`false`	Set `true` to block suspicious packages as well as malicious ones. Sets `PMG_PARANOID`.
`cooldown-enabled`	`true`	Set `false` to allow package versions that were published recently. Sets `PMG_DEPENDENCY_COOLDOWN_ENABLED`.
`cooldown-days`	`2`	The number of days that a new package version stays blocked. Sets `PMG_DEPENDENCY_COOLDOWN_DAYS`.
`sandbox`	`false`	Set `true` to run package managers in an OS sandbox. Applies only with shims, so it turns off server mode unless `server-mode` is `true`. The action also relaxes the AppArmor limit on user namespaces on the runner. Sets `PMG_SANDBOX_ENABLED`.
`sandbox-driver`	`landlock`	The sandbox backend: `landlock` or `bubblewrap`. With `bubblewrap`, the action installs it with `apt-get`. Sets `PMG_SANDBOX_DRIVER`.
`verbosity`	`normal`	The PMG output level: `silent`, `normal`, or `verbose`. Sets `PMG_VERBOSITY`.
`disable-telemetry`	`false`	Set `true` to stop anonymous PMG telemetry. Sets `PMG_DISABLE_TELEMETRY`.
`skip-event-logging`	`false`	Set `true` to stop writing audit events to the local event log. This also removes the proposed network profile from the job summary. Sets `PMG_SKIP_EVENT_LOGGING`.
`config-file`	Empty	The path of a PMG `config.yml` in the repository. The action copies it to the PMG config directory before PMG starts. An input that you set overrides the same key in the file.

The enforce-* inputs take a list, separated by commas or new lines. Each list adds to the same list in the config. The proxy-mode input is removed. The value false fails the job. Any other value gives a warning.

Outputs

Output	Value
`version`	The PMG release that the action installed, for example `v0.34.0`.
`bin-dir`	The directory that holds the `pmg` binary on the runner.

To read an output, give the step an id:

- uses: safedep/pmg@v0.34.0
  id: pmg

- run: echo "PMG ${{ steps.pmg.outputs.version }} is in ${{ steps.pmg.outputs.bin-dir }}"

Supported runners

The action supports Linux runners on x86_64 and arm64. On a macOS or Windows runner, the action fails.

Use raw commands

To wire the proxy up directly without the action:

- run: pmg proxy start --daemon
- run: pmg proxy env >> "$GITHUB_ENV"
- run: npm ci
- run: pmg proxy stop --fail-on-violation
  if: always()

pmg proxy env >> "$GITHUB_ENV" sets HTTP_PROXY, HTTPS_PROXY, and the CA variables for every later step. pmg proxy stop does not remove the variables. A step after the stop step that uses the network connects to the stopped proxy and fails, for example actions/upload-artifact with ECONNRESET. Put the stop step last in the job. The action does not have this problem, because its post step empties the proxy variables after the stop.

For the proxy lifecycle, certificate trust, bind address, and cloud event sync, see the persistent proxy server docs.

Allow Only Known Hosts in GitHub Actions

Refuse every host that the job does not need.

Kernel Enforcement on Linux

Route every process and container on the runner through PMG.

PMG

How PMG blocks malicious packages at install time.

Malicious Package

How SafeDep detects malicious packages.

CI/CD Package Blocking

PMG in GitHub Actions

Use the SafeDep PMG action

Upgrade from v0.33.0 or earlier

What happens at the end of the job

Example workflow

See blocks from every pipeline

Enforce in the kernel

Protect Docker builds and containers

Job containers and Docker actions

Self-hosted runners

Action inputs and outputs

Inputs

Outputs

Supported runners

Use raw commands

Allow Only Known Hosts in GitHub Actions

Kernel Enforcement on Linux

PMG

Malicious Package

​Use the SafeDep PMG action

​Upgrade from v0.33.0 or earlier

​What happens at the end of the job

​Example workflow

​See blocks from every pipeline

​Enforce in the kernel

​Protect Docker builds and containers

​Job containers and Docker actions

​Self-hosted runners

​Action inputs and outputs

​Inputs

​Outputs

​Supported runners

​Use raw commands

Allow Only Known Hosts in GitHub Actions

Kernel Enforcement on Linux

PMG

Malicious Package

Use the SafeDep PMG action

Upgrade from v0.33.0 or earlier

What happens at the end of the job

Example workflow

See blocks from every pipeline

Enforce in the kernel

Protect Docker builds and containers

Job containers and Docker actions

Self-hosted runners

Action inputs and outputs

Inputs

Outputs

Supported runners

Use raw commands