Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure Linux 4 packages are signed and installed with DNF. Language package managers, such as pip, npm, Go modules, and Cargo, download code from public registries instead. That code doesn't pass through Azure Linux package signing, so its integrity depends on how you configure each tool.
Default pip, npm, Go, and Cargo sources and settings
The language package managers aren't installed in the general-purpose image.
They're available from the Azure Linux repository in the python3-pip,
nodejs-npm, golang, and cargo packages.
| Tool | Default source | Defaults that affect supply-chain risk |
|---|---|---|
| pip | Python Package Index (PyPI) | No system configuration file. The Python installation has no EXTERNALLY-MANAGED marker, so sudo pip install isn't blocked. It installs into /usr/local/lib/python3.<minor>/site-packages, which takes precedence over packages installed by DNF. |
| npm | https://registry.npmjs.org/ |
/etc/npmrc sets the global prefix to /usr/local. Package install scripts run (ignore-scripts=false), npm audit runs on install, and TLS certificate checks are on. |
| Go | https://proxy.golang.org,direct |
/usr/lib/golang/go.env sets GOSUMDB=sum.golang.org, so downloaded modules are checked against the checksum database. It also sets GOTOOLCHAIN=local, so the go command doesn't download a different toolchain. |
| Cargo | crates.io | No system configuration file. A build can update Cargo.lock when it doesn't match Cargo.toml, unless you pass --locked. |
Two of these defaults leave supply-chain controls to you:
- npm runs package install scripts.
ignore-scriptsisfalse, so a dependency'spreinstall,install, andpostinstallscripts run with the permissions of the user who runsnpm install. See Install npm dependencies from a lock file. - Python has no
EXTERNALLY-MANAGEDmarker. pip doesn't stop you from installing packages into the system Python environment. See Isolate Python packages.
Prerequisites
An Azure Linux virtual machine (VM).
A user account with
sudoprivileges.The package manager you use, installed with DNF. For example:
sudo dnf install -y python3-pip nodejs-npm golang cargo
Verify pip, npm, Go, and Cargo supply-chain settings
Check the effective settings for each tool before you depend on them. Each
command requires the matching package from Prerequisites.
On a VM without it, the shell reports command not found.
pip
List the configuration files pip reads and any values they set. This command
requires the python3-pip package:
pip3 config debug
Expected result on a new VM when you run the command as root:
env_var:
env:
global:
/etc/xdg/pip/pip.conf, exists: False
/etc/pip.conf, exists: False
site:
/usr/pip.conf, exists: False
user:
/root/.pip/pip.conf, exists: False
/root/.config/pip/pip.conf, exists: False
No global or user file exists. Check for packages installed outside DNF, which take precedence over packages installed by DNF:
ls /usr/local/lib/python3.*/site-packages
Expected result when no packages were installed outside DNF:
ls: cannot access '/usr/local/lib/python3.*/site-packages': No such file or directory
npm
Read the registry and the settings that control install scripts. These
commands require the nodejs-npm package:
npm config get registry
npm config get ignore-scripts
cat /etc/npmrc
Expected result for the default configuration:
https://registry.npmjs.org/
false
prefix=/usr/local
python=/usr/bin/python3
update-notifier=false
Go
Read the module source, checksum database, and toolchain settings. This
command requires the golang package:
go env GOPROXY GOSUMDB GOTOOLCHAIN
Expected result for the default configuration:
https://proxy.golang.org,direct
sum.golang.org
local
With GOTOOLCHAIN=local, a module that requires a newer Go version fails
instead of downloading a toolchain:
go: go.mod requires go >= <version> (running go <installed-version>; GOTOOLCHAIN=local)
Install a newer golang package when one is available, instead of changing
this setting.
Cargo
Check for configuration files that change the registry or sources:
ls ~/.cargo/config.toml .cargo/config.toml 2>/dev/null
No output means Cargo uses crates.io.
Pin and verify language package dependencies
Pin dependencies, verify their integrity, and keep language packages out of the system Python and Node.js installations.
Isolate Python packages
Install Python packages in a virtual environment instead of with sudo pip:
python3 -m venv <environment-path>
<environment-path>/bin/pip install -r requirements.txt
To stop pip from installing outside a virtual environment, set
require-virtualenv in the global configuration:
sudo pip3 config --global set global.require-virtualenv true
pip then refuses installs outside a virtual environment:
ERROR: Could not find an activated virtualenv (required).
If a package was already installed with sudo pip, remove it to restore the
version installed by DNF:
sudo pip3 uninstall <package-name>
Require hashes for Python dependencies
With hash-checking mode, pip installs only packages that match the hashes in your requirements file:
<environment-path>/bin/pip install --require-hashes -r requirements.txt
When a requirement has no hash, pip refuses to install and prints the hash of the downloaded file, for example:
ERROR: Hashes are required in --require-hashes mode, but they are missing from some requirements.
Get hashes from a trusted source, such as a lock file generated in a controlled environment, rather than copying them from a failed install.
Install npm dependencies from a lock file
Commit package-lock.json, and install with npm ci, which installs exactly
the versions in the lock file and fails if package.json doesn't match it:
npm ci
To stop package install scripts from running, set ignore-scripts in the
global configuration:
sudo npm config set ignore-scripts true --location=global
The setting is written to /etc/npmrc. Some packages need their install
scripts to build native code. Test your application, and run the scripts for
those packages explicitly.
Keep Go module verification on
Keep GOSUMDB and GOTOOLCHAIN=local. For private modules, exclude only your
own module paths from the public proxy and checksum database:
go env -w GOPRIVATE=<module-path-prefix>
go env -w writes to your user Go configuration file and overrides
/usr/lib/golang/go.env. Don't set GOSUMDB=off, GONOSUMDB, or
GOINSECURE for public modules.
Note
The Azure Linux go command accepts a non-local GOTOOLCHAIN value only
when MS_GOTOOLCHAIN_ALLOW_NON_LOCAL=1 is set. Toolchains that go
downloads aren't built or updated by Azure Linux.
Build Rust projects from the lock file
Commit Cargo.lock for applications, and build with --locked so that Cargo
fails instead of changing dependency versions:
cargo build --locked
To use a private registry or a mirror, configure source replacement as described in the Cargo source replacement documentation.
Use an internal mirror
To control which package versions your builds can download, point each tool at an internal mirror or artifact feed that you manage:
| Tool | Setting |
|---|---|
| pip | sudo pip3 config --global set global.index-url <mirror-url> |
| npm | sudo npm config set registry <mirror-url> --location=global |
| Go | go env -w GOPROXY=<mirror-url> |
| Cargo | Source replacement in .cargo/config.toml |
Troubleshoot pip, npm, and Go package installs
A system tool fails after sudo pip install
A package in /usr/local/lib/python3.<minor>/site-packages takes precedence
over the version installed by DNF, for every Python program on the VM. Find the
package that Python loads:
python3 -c 'import <module-name>; print(<module-name>.__file__)'
If the path is under /usr/local, remove the package with
sudo pip3 uninstall <package-name>.
npm install fails after setting ignore-scripts
A dependency needs its install script, for example to compile native code.
Run the scripts for that package explicitly, or install with
npm ci --ignore-scripts=false for a reviewed lock file.
go build fails with GOTOOLCHAIN=local
The module requires a newer Go version than the installed golang package.
Update the package with sudo dnf upgrade golang, or use a module version
that supports the installed Go version.