Deploy Package Firewall to developer machines with MDM

This setup is a package manager client deployment. MDM pushes the Package Firewall configuration to developer machines. Mobile device management (MDM) deployment lets an IT administrator configure many developer machines at once. You generate a self-contained script, push it through your MDM tool, and it configures each machine’s package manager clients to route installations through Package Firewall. Developers do nothing, and the scripts preserve existing package manager client configuration. The scripts cover the following ecosystems. They are idempotent, so they are safe to re-run on every MDM check-in. Except for the VS Code script on Linux, they have no runtime dependencies beyond the shell. The Package Firewall MDM scripts also cover protection against malicious VS Code extensions from the Microsoft Marketplace. See VS Code extensions to learn more.

The scripts are available in the Endor Labs MDM scripts repository under the package-firewall/ directory.

Before you begin

Create an API key dedicated to the Package Firewall so that the deployment scripts can authenticate to it. You can create it through one of the following methods:

Using the Endor Labs user interface, with the Package Firewall User role. See API keys to learn more.
Using endorctl, with the SYSTEM_ROLE_PACKAGE_FIREWALL role. Make sure to install and configure endorctl before you create the key.

To create the key using endorctl, run the following command and replace:

<namespace> with your namespace.
<API key name> with the name of the API key for the Package Firewall use case.
<YYYY-MM-DDTHH:MM:SSZ> with the API key expiration in ISO 8601 UTC format, for example 2026-12-31T23:59:59Z.

export NAMESPACE="<namespace>"
export KEY_NAME="<API key name>"

endorctl api create -r APIKey -n "$NAMESPACE" --data '{
  "meta": { "name": "'"$KEY_NAME"'" },
  "spec": {
    "permissions": { "roles": ["SYSTEM_ROLE_PACKAGE_FIREWALL"] },
    "expiration_time": "<YYYY-MM-DDTHH:MM:SSZ>"
  },
  "propagate": true
}'

To deploy the VS Code script on Linux, install Python 3 on the device. The patch method also requires systemd.

Generate the MDM scripts

Clone the generator repository and run it with your namespace and Package Firewall credentials. Select your platform for the matching commands.

The generated scripts default to https://factory.endorlabs.com. If you use Endor Labs with an EU tenant, set ENDOR_FQDN=https://factory.eu.endorlabs.com when you run the generator. The browser generator has a region picker for the same setting.

You can also generate the scripts in the browser using the MDM script generator. The generator fetches the real source files from the Endor Labs MDM scripts repository (https://github.com/endorlabs/mdm-scripts). The GitHub repository is the authoritative source for the scripts.

macOS / Linux
Windows

Clone the generator repository: Clone the repository and change into the bash generator directory.
git clone https://github.com/endorlabs/mdm-scripts cd mdm-scripts/package-firewall/bash
Generate the scripts: Pass your credentials as environment variables. This keeps them out of your shell history.
ENDOR_NAMESPACE=<namespace> \ ENDOR_API_KEY_ID=<api-key-id> \ ENDOR_API_SECRET=<api-secret> \ ./generate.sh
Alternatively, store the variables in a .env file, add .env to .gitignore, and source it.
set -a; source .env; set +a ./generate.sh

The generator writes endor-js.sh, endor-python.sh, endor-go.sh, endor-maven.sh, endor-nuget.sh, endor-ruby.sh, endor-vscode.sh, endor-all.sh, and endor-remove.sh to out/<namespace>/. It also writes endor-vscode-disable-patch.sh and endor-vscode-disable-policy.sh, which each turn off one VS Code method. Re-running generate.sh overwrites the same directory.endor-vscode.sh and endor-all.sh leave VS Code unchanged unless you add ENDOR_VSCODE_ENABLE_PATCH=true, ENDOR_VSCODE_ENABLE_POLICY=true, or both to the generator command. Compare the two methods before you set them. With ENDOR_VSCODE_ENABLE_POLICY=true, the generator also writes endor-vscode.mobileconfig and endor-vscode-policy.plist, the VS Code policy for macOS. See Deliver the gallery policy on macOS.

Clone the generator repository: Clone the repository and change into the PowerShell generator directory.
git clone https://github.com/endorlabs/mdm-scripts cd mdm-scripts/package-firewall/powershell

Generate the scripts: Set your credentials as environment variables, then run the generator.

$env:ENDOR_NAMESPACE  = '<namespace>'
$env:ENDOR_API_KEY_ID = '<api-key-id>'
$env:ENDOR_API_SECRET = '<api-secret>'
./generate.ps1

The generator writes endor-js.ps1, endor-python.ps1, endor-go.ps1, endor-maven.ps1, endor-nuget.ps1, endor-ruby.ps1, endor-vscode.ps1, endor-all.ps1, and endor-remove.ps1 to out/<namespace>/. It also writes endor-vscode-disable-patch.ps1 and endor-vscode-disable-policy.ps1, which each turn off one VS Code method. Re-running generate.ps1 overwrites the same directory.endor-vscode.ps1 and endor-all.ps1 leave VS Code unchanged unless you set $env:ENDOR_VSCODE_ENABLE_PATCH = 'true', $env:ENDOR_VSCODE_ENABLE_POLICY = 'true', or both before you run the generator. Compare the two methods before you set them.

The generated scripts contain your API key and secret in plain text, because the scripts need them to write credentials on each device. MDM deployment then copies that one credential to every enrolled machine. Scope the key to the Package Firewall role only, keep the scripts and the out/ directory out of source control, restrict who can view the MDM policy, and rotate the key on a schedule by redeploying the script.

Upload the scripts to your MDM tool

Each generated script is self-contained, so you upload it directly to your MDM tool. On macOS and Linux the scripts use the .sh extension. On Windows, they use .ps1.

macOS / Linux
Windows

Run the scripts as root. The script detects the logged-in console user and writes configuration files to the correct home directory.When no user is logged in, such as at the login window or during Setup Assistant, the package manager scripts and endor-all.sh exit with code 1 and change nothing. Run them at login or at a recurring check-in. endor-vscode.sh and the VS Code disable scripts do not need a logged-in user.

Kandji

Add the script: Go to Library > Custom Scripts > Add Script.
Provide the script: Paste the script content or upload the file.
Set the run context: Set Run as to Root.
Set the frequency: Set Execution Frequency to Run once per device, or to every check-in for ongoing enforcement.
Assign the script: Assign the script to the relevant device blueprint.

Jamf Pro

Add the script: Go to Settings > Scripts > New and paste the script content.
Create a policy: Go to Policies > New Policy > Scripts and add your script.
Set the frequency: Set the Execution Frequency as appropriate.
Scope the policy: Scope the policy to the target devices.

Generic MDM

Upload the script file and run it as root. The script detects the logged-in console user and writes configuration files to the correct home directory.

Run the scripts as SYSTEM. The script detects the logged-in console user through explorer.exe and writes configuration files to the correct user profile.

Microsoft Intune

Add the script: Go to Devices > Scripts and remediations > Platform scripts > Add.
Upload the file: Upload the .ps1 file.
Set the run context: Set Run this script using the logged on credentials to No, so the script runs as SYSTEM.
Set the signature check: Set Enforce script signature check to No.
Set the PowerShell architecture: Set Run script in 64-bit PowerShell to Yes.
Assign the script: Assign the script to the target device group.

Intune bypasses the execution policy for managed scripts, so you do not need to change the device policy.

Generic MDM

Upload the script file and run it as SYSTEM. The script detects the logged-in console user through explorer.exe and writes configuration files to the correct user profile.

How credentials are stored

The scripts write your credentials to a single source on each device and reference them from the package manager client configuration files. The storage mechanism depends on your platform.

macOS / Linux
Windows

The scripts write all credentials to ~/.config/endor/env.sh and set the file permissions to 600.

export ENDOR_API_KEY_ID="..."
export ENDOR_API_SECRET="..."
export ENDOR_ATTR_USER="..."         # attributed Basic-auth username, see User attribution
export ENDOR_AUTH_B64="..."          # base64(attributed-user:secret) for npm, pnpm, yarn, and bun
export ENDOR_API_SECRET_B64="..."
export ENDOR_NPM_REGISTRY_URL="..."  # for npm and yarn 2+
export POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME="..."   # attributed user
export POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD="..."

Each shell profile (.zshrc, .bash_profile, and .bashrc) gets a one-line block that sources this file. The configuration files reference these variables instead of embedding credentials, except pip.conf, uv.toml, and the go env file, which cannot expand variables and get a literal index URL baked in at install time.To rotate credentials, redeploy the MDM script to update env.sh on the target machines. You do not need to change any configuration files.

The scripts write persistent user-level environment variables to the HKCU:\Environment registry key.

ENDOR_API_KEY_ID                          = <key-id>
ENDOR_API_SECRET                          = <secret>
ENDOR_ATTR_USER                           = <attributed Basic-auth username, see User attribution>
ENDOR_AUTH_B64                            = <base64(attributed-user:secret)>
ENDOR_API_SECRET_B64                      = <base64(secret)>
ENDOR_NPM_REGISTRY_URL                    = https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/npm/
POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME = <attributed user>
POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD = <secret>

Every process the user starts inherits HKCU:\Environment variables, including Makefiles, git hooks, IDE terminals, and scheduled tasks. No shell profile sourcing is required. pip.ini, uv.toml, and the go env file cannot expand environment variables, so they get a literal index URL baked in at install time instead.To rotate credentials, redeploy the MDM script. It updates HKCU:\Environment, plus pip.ini, uv.toml, and the go env file, which hold literal credentials, in place.

User attribution

The generated scripts label each machine’s Package Firewall traffic with the developer who owns it. The firewall logs then attribute activity to a person and machine rather than to a shared API key. By default the label is <console-user>@<machine>, built at install time from the logged-in console user and the machine name. The scripts encode the label into the Basic-auth username they write for every package manager client they configure. They store the encoded username as ENDOR_ATTR_USER in the credential store, which is env.sh on macOS and Linux and HKCU:\Environment on Windows. See User attribution to choose a different label, learn how the encoding works, or attribute traffic from the other deployment models.

What the scripts do

Each install script writes the credential store and an Endor-managed block to the package manager client configuration files. The file locations depend on your platform.

macOS / Linux
Windows

The endor-js.sh script writes ~/.config/endor/env.sh and an Endor-managed block to the following files.The endor-go.sh script writes ~/.config/endor/env.sh and an Endor-managed block to the following file.The endor-python.sh script writes ~/.config/endor/env.sh and an Endor-managed block to the following files.The endor-maven.sh script writes ~/.config/endor/env.sh and an Endor-managed block to the following file.The endor-nuget.sh script writes ~/.config/endor/env.sh and Endor-managed blocks to the following file.

The endor-js.ps1 script writes the registry environment variables and an Endor-managed block to the following files.The endor-go.ps1 script writes the registry environment variables and an Endor-managed block to the following file.The endor-python.ps1 script writes the registry environment variables and an Endor-managed block to the following files.The endor-maven.ps1 script writes the registry environment variables and an Endor-managed block to the following file.

Configure each package manager client

The scripts apply a few package manager client-specific behaviors that are the same on every platform unless noted otherwise.

JavaScript

The scripts write _auth (base64) instead of _authToken, which bun requires. Yarn classic reads authentication from .npmrc, so the .npmrc write covers it. The scripts do not write the project-level bunfig.toml.

The scripts find the go env file with go env GOENV and write GOPROXY to it.
If go is not installed, they use the default path: ~/Library/Application Support/go/env on macOS, ~/.config/go/env on Linux, or %APPDATA%\go\env on Windows.
Credentials are written as is, because go env files cannot expand environment variables.
GOPROXY ends in ,direct, so Go downloads a module from its source if the firewall does not serve it.
The go env file applies to every go command in any shell. A GOPROXY environment variable takes precedence, so project-level overrides still work.

Python (pip)

The scripts write the pip settings in a [global] section. If the file already has a [global] section, they merge the Endor keys into it, because pip rejects duplicate [global] sections. The scripts disable any conflicting keys, such as an existing index-url, with an #endor-bak# prefix and restore them when the remove script runs.

Python (uv)

uv ignores pip.conf, so the scripts write the user-level uv.toml with the firewall index URL. The scripts bake the URL in literally because uv cannot expand environment variables in its config, so it carries the attributed username.

Python (Poetry)

Poetry reads credentials from the POETRY_HTTP_BASIC_ENDOR_FIREWALL_* environment variables, so you do not need a separate write step. Add the source to your pyproject.toml:Poetry reads the registry URL from pyproject.toml and the credentials from environment variables. Add the Package Firewall as a source in each project. The source includes the URL only, never the credentials.

[[tool.poetry.source]]
name = "endor-firewall"
url = "https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/pypi/simple/"
priority = "primary"

Maven

The scripts write a user-level settings.xml (~/.m2/settings.xml, or %USERPROFILE%\.m2\settings.xml on Windows) with a <mirror> of * that points at the firewall, plus a matching <server>.
Credentials are not stored in the file. The <server> references ${env.ENDOR_ATTR_USER} and ${env.ENDOR_API_SECRET}, which Maven reads at runtime from the environment variables the credential store sets.
Gradle uses the same settings when it reads ~/.m2/settings.xml.

.NET (NuGet)

The macOS and Linux scripts merge the Endor source into <packageSources> in ~/.nuget/NuGet/NuGet.Config.
The block starts with <clear />, so the firewall replaces nuget.org and every source listed before it.
If the file lists a private feed, such as Artifactory or Azure Artifacts, the script warns and exits with code 1. Re-add that feed in a repository-level nuget.config, or use the JFrog Artifactory integration instead.
Credentials are not stored in the file. <packageSourceCredentials> references %ENDOR_ATTR_USER% and %ENDOR_API_SECRET%, which NuGet reads at runtime from the environment variables that env.sh sets.
IDEs launched outside a shell, such as from the macOS Dock, do not inherit env.sh. Their restores fail with a 401 error instead of bypassing the firewall.

A repository-level nuget.config overrides the user-level file for that repository. A repository that commits <clear /> followed by nuget.org bypasses the firewall. For full enforcement, commit endor-firewall as the only public source in each repository. The key must be exactly endor-firewall so that the user-level credentials apply. A repository nuget.config that only adds a source keeps that source active next to the firewall.

Preserve existing configuration

The scripts use a sentinel block pattern. Each script writes only a clearly delimited section to a configuration file and leaves everything else untouched, so existing settings survive every deployment. The following example shows an .npmrc file that already contains administrator settings. The script adds only the Endor-managed block between the BEGIN and END markers.

# Existing configuration — never touched
legacy-peer-deps=true

# ===== BEGIN ENDOR PACKAGE FIREWALL (managed — do not edit) =====
registry=https://factory.endorlabs.com/v1/namespaces/<namespace>/firewall/npm/
always-auth=true
//factory.endorlabs.com/v1/namespaces/<namespace>/firewall/npm/:_auth=${ENDOR_AUTH_B64}
# ===== END ENDOR PACKAGE FIREWALL =====

The following table describes how the scripts handle each configuration scenario.

Remove the configuration

To offboard a machine, deploy the remove script. It strips the Endor block from every managed file and removes the credentials the install scripts added. To turn off only one VS Code method and keep the package manager configuration, deploy a VS Code disable script instead. See Switch or turn off a VS Code method.

macOS / Linux
Windows

Deploy endor-remove.sh. It removes the Endor block from each configuration file, removes the credentials from ~/.config/endor/env.sh, and removes both VS Code methods. See Remove the VS Code configuration for details. For the macOS VS Code daemon, it also restores Microsoft’s original app when available and removes the signing identity. See Remove the daemon for the fallback when no original is available.When no user is logged in, endor-remove.sh removes the machine-wide configuration, such as the VS Code methods, and leaves the user’s files. It then exits with code 1. Deploy it again after a user logs in.

Deploy endor-remove.ps1. It removes the Endor block from each configuration file, deletes the ENDOR_* and POETRY_HTTP_BASIC_ENDOR_FIREWALL_* values from HKCU:\Environment, deletes configuration files that are empty after block removal, and removes both VS Code methods. See Remove the VS Code configuration for details. Preview the changes with -DryRun before you apply them.

.\endor-remove.ps1 -DryRun
.\endor-remove.ps1

Security notes

The scripts store credentials on each device. Review the following before you deploy.

Generate your MDM script in the browser

Select your platform, ecosystem, MDM tool, and region, then enter your namespace and API key. The remove and VS Code disable scripts need only the namespace. Select US or EU based on where your Endor Labs tenant is hosted. The region sets the Package Firewall URL. The generator builds the script entirely in your browser. It never sends your credentials to Endor Labs or GitHub, and only bakes them into the script you download. For scripts that include VS Code, select Patch VS Code’s product.json, Set VS Code’s gallery policy, or both. Neither is selected by default, and without one the script leaves VS Code unchanged. Compare the two methods before you deploy.

The generated install scripts contain your API key and secret in plain text, because they need them to write credentials on each device. MDM deployment then copies that one credential to every enrolled machine. Scope the key to the Package Firewall role only, and keep generated scripts out of source control. Restrict who can view the MDM policy, and rotate the key on a schedule by redeploying the script.

Introduction

Set up

Configure

Operate

Deploy Package Firewall to developer machines with MDM

Before you begin

Generate the MDM scripts

Upload the scripts to your MDM tool

How credentials are stored

User attribution

What the scripts do

Configure each package manager client

Preserve existing configuration

Remove the configuration

Security notes

Generate your MDM script in the browser

​Before you begin

​Generate the MDM scripts

​Upload the scripts to your MDM tool

​How credentials are stored

​User attribution

​What the scripts do

​Configure each package manager client

​Preserve existing configuration

​Remove the configuration

​Security notes

​Generate your MDM script in the browser

Before you begin

Generate the MDM scripts

Upload the scripts to your MDM tool

How credentials are stored

User attribution

What the scripts do

Configure each package manager client

Preserve existing configuration

Remove the configuration

Security notes

Generate your MDM script in the browser