Installation and Configuration

System Requirements

Before installing Safety Firewall, ensure your system meets the following requirements:

• Operating Systems:

  • macOS 10.14 or later

  • Linux (Ubuntu, Debian, CentOS, RHEL)

  • Windows 10 or later

• Python: Version 3.8 or later

Safety Firewall works with pip, uv, poetry, and npm. We'll automatically detect and configure the package managers on your system.

Before You Begin

Create a Safety Account

If you don't already have a Safety account, sign up here.

Get Your Organization Ready

To use Safety Firewall, your organization must have the Firewall feature enabled. If you're unsure whether your organization has access, contact your Safety administrator or reach out to our support team.

If your Safety account was created before March 2025, the Firewall feature is disabled by default to ensure no breaking changes occur. To enable Firewall, please reach out to our support team.

1. Installation

1.1 Install Safety CLI

Open your terminal and run the following command:

pip

pip install safety

If you already have Safety installed, please use pip install -U safety . The minimum version required to run Safety Firewall is v3.5.0.

UV

uv tool install safety

1.2 Authenticate with Safety

Run the authentication command:

safety auth login

This will open a browser window where you can log in to your Safety account. Once authenticated, your terminal will show a success message.

1.3 Verify Authentication Status

You can check your authentication status at any time with:

safety auth status

This should display your email address and confirm that you're authenticated.

Make sure you're authenticated before proceeding to the next step. If you're not authenticated or don't have the Firewall feature enabled, the safety init command will not be available.

2. Initialization of Safety Firewall

After installing the Safety CLI and authenticating your account, you can initialize Safety Firewall with a single command:

safety init

This command starts the interactive setup process for Safety Firewall.

What Happens During Initialization

When you run safety init, the following actions take place:

1. Safety checks if you're authenticated and asks if you want to setup Safety Firewall.

2. Safety identifies the package managers on your system (pip, poetry, etc.)

3. Safety configures secure aliases for each package manager

4. Safety detects if there is a codebase in your current directory

5. Safety offers to set up this codebase for ongoing protection

IMPORTANT: After initialization, you'll need to refresh your shell environment for the aliases to take effect. This is typically done by running source ~/.safety/.safety_profile or the equivalent for your shell.

3. Verifying Firewall Installation

After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:

Mac/Linux

After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:

which pip

You should see output similar to:

pip: aliased to safety pip

If you don't see this output, your shell environment may need to be reloaded.

CMD.exe

After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:

where pip

You should see output similar to:

pip: aliased to safety pip

If you don't see this output, your shell environment may need to be reloaded.

PowerShell

After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:

gcm pip

You should see output similar to:

pip: aliased to safety pip

If you don't see this output, your shell environment may need to be reloaded.

Understanding Safety Firewall Configuration

How Safety Firewall Intercepts Commands

Safety Firewall intercepts your package manager commands so it can check a package before it installs. The mechanism differs by operating system.

On macOS and Linux, Safety writes shell aliases into ~/.safety/.safety_profile and sources that file from your shell startup files. Running pip install requests matches the pip alias, which routes the command through Safety Firewall.

On Windows, Safety writes .bat shims into %USERPROFILE%\AppData\Local\safety\, adds that directory to your PATH, registers a Command Prompt macro, and adds functions to your PowerShell profile.

Once a command is intercepted, Safety Firewall:

1. Analyzes the requested package(s) for vulnerabilities and malicious code

2. Applies your organization's security policies

3. Either warns, blocks, or allows the installation

4. Records the installation event in the Safety Platform

Where Command Interception Does Not Reach

Interception applies to the command you type, so three cases fall outside it.

1. An alias matches only the first word of a command. python -m pip install requests runs pip without matching the pip alias.

2. A script or tool that starts pip as a subprocess does not inherit the aliases from your interactive shell.

3. A container image build has no shell startup files, so no aliases exist. Write safety pip install explicitly in a RUN line to keep those installs covered.

Safety Firewall also points your package managers at the Safety index, which is a separate mechanism from interception. That configuration lives in a file, so it applies to any command the package manager runs, whether or not it was intercepted. A command-line flag, an environment variable or a project-level file can still override it. What Can Override Your Configuration covers that surface per package manager.

How Each Package Manager Is Configured

The Safety index proxies the public PyPI and npm registries. safety init writes it into each package manager's index configuration. For pip and npm it replaces the configured index. For uv it is added alongside the existing default index, so PyPI stays configured and uv still resolves from it for any name the Safety index does not carry.

Package manager	User-wide	Per project
pip	index-url in your user pip.conf	-i <index-url> line added to requirements files
uv	An additional index entry, written with default = false, in your user uv.toml at $XDG_CONFIG_HOME/uv/uv.toml, ~/.config/uv/uv.toml, or %APPDATA%\uv\uv.toml on Windows	An index entry in pyproject.toml
npm	registry in your global .npmrc	registry in the project .npmrc
poetry	Not configured	A safety source added to pyproject.toml

Poetry is the exception. Safety configures Poetry per project, so a Poetry project that Safety has not configured resolves from PyPI directly. Running a Poetry command through safety poetry adds the source to that project before the command runs.

How uv Resolves Indexes

uv flattens every configured index into one ordered list. Under its default first-index strategy it installs from the first index in that list that carries the package name. "First" means highest priority, and priority runs in this order.

1. --index, or the UV_INDEX environment variable where the flag is absent. These are one tier rather than two, because --index replaces the environment value instead of ranking above it. The deprecated --extra-index-url and UV_EXTRA_INDEX_URL map here.

2. Index entries in configuration files. A project's entries come before your user uv.toml entries, because uv concatenates the two arrays instead of replacing one with the other.

3. The default index, always last. safety init leaves it alone, so it stays as PyPI unless something sets default = true, --default-index or UV_DEFAULT_INDEX.

safety init writes the Safety index into your user uv.toml with default = false.

uv.lock Pins the Index Per Package

uv.lock records source = { registry = ... } for every package resolved from an index, and uv sync --frozen and uv sync --locked install from the recorded registry without re-resolving. A lock file created before safety init therefore keeps resolving from whatever registry it recorded, the same caveat that applies to package-lock.json and npm ci. Re-run uv lock after safety init to move the recorded registries to the Safety index.

Which uv Commands Safety Firewall Audits

The user uv.toml that safety init writes applies to every uv command that reads it. Interception, which is what audits a package before it installs, covers uv add, uv remove, uv sync, uv pip install and uv pip uninstall. uvx is a separate executable with no alias, so it is not intercepted.

What Can Override Your Configuration

Package managers read configuration from more than one location, and the setting closest to the command wins. The overrides below are listed per package manager, because both the flags and the multiple-index behavior differ enough that a rule for one manager is wrong for another.

pip

Three things override the index safety init writes.

1. A command-line flag. pip install --index-url <url> requests replaces the configured index for that command.

2. The PIP_INDEX_URL environment variable, which overrides your user configuration file.

3. A pip.conf closer to the command. One inside an active virtual environment overrides your user pip.conf.

pip treats every configured index as equal. It queries all of them and installs the highest version it finds, with no preference between them. Adding a second index with --extra-index-url therefore does not leave the Safety index in charge.

Using the --extra-index-url option to search for packages which are not in the main repository (for example, private packages) is unsafe. This is a class of security issue known as dependency confusion.

From the pip documentation

Replacing the index with --index-url does not carry this risk, because pip then queries one index only.

uv

uv reads no pip.conf and no PIP_* variable, so a team that standardized on PIP_INDEX_URL for an internal mirror will find uv unaffected by it in both directions. How uv Resolves Indexes covers the priority order these overrides slot into. The list below groups them by kind, because only the first two entries are priority tiers.

1. --index, or UV_INDEX where the flag is absent, which outranks every configured index including the one safety init writes.

2. A project uv.toml, or a pyproject.toml where no project uv.toml exists, whose index entries come before your user uv.toml entries.

3. --default-index or UV_DEFAULT_INDEX, which replaces the lowest-priority default index and leaves the Safety entry in place above it.

4. --index-url and --extra-index-url, both deprecated in uv. --index-url maps to the default index and --extra-index-url maps to --index.

5. --index-strategy or UV_INDEX_STRATEGY, which changes how uv chooses between the configured indexes.

6. --config-file or UV_CONFIG_FILE, and --no-config or UV_NO_CONFIG. Both discard every configuration file uv would otherwise read, a project uv.toml or pyproject.toml included, not only your user uv.toml.

poetry

poetry searches all primary sources for every package. Adding your own primary source alongside Safety's means both are searched.

npm

npm resolves each package from one registry, chosen by the package's scope, and has no equivalent of --extra-index-url. Lock files are the case to watch. A package-lock.json created while a different custom registry was configured records that registry, and npm ci keeps installing from it after you configure the Safety registry.

Checking Your Configuration

To see which index pip uses and which file set it, run:

pip config debug

The output lists every configuration file pip checked, in precedence order, with the values each one sets. pip config list shows the effective values without showing their source.

For npm, run:

npm config get registry
npm config list

npm config list labels each value with the file or environment variable it came from.

uv has no equivalent of pip config debug, and reading uv.toml alone misses environment variables, command-line flags, project-level entries and UV_NO_CONFIG. Resolve a package with logging instead. In a project, run:

uv lock -v --refresh

Outside a project, run this from an active virtual environment. command bypasses the Safety alias, which otherwise injects its own index into the environment you are trying to inspect:

command uv pip install --dry-run --refresh -v <package>

Read the Sending fresh GET request for: <index>/<package>/ lines, which appear highest priority first. --refresh matters, because a warm cache logs Found fresh response for: instead and the index never appears in the output. After a lock, uv.lock records the registry each package resolved from.

For Poetry, check the sources in pyproject.toml directly.

Installs run through Safety Firewall set the index for that command only, so these commands show your configuration rather than the index a Safety-intercepted install used.

Configuration Files

Safety Firewall creates several configuration files on your system:

• ~/.safety/: The main directory for Safety Firewall configuration

• ~/.safety/config.toml: Global configuration file

• .safety-project.ini: Project-specific configuration (created in each code base directory)

Most users won't need to manually edit these files. Configuration changes are typically made through the Safety CLI or Safety Platform

Configuring Your First Codebase

During initialization, Safety may detect a requirements file or Python project in your current directory and offer to configure it as a code base. If you accept, Safety will:

1. Create a .safety-project.ini file in the directory

2. Perform an initial scan of the project's dependencies

3. Upload the scan results to the Safety Platform

4. Configure the directory for ongoing monitoring

Manual Codebase Configuration

If you want to set up a codebase after initialization, navigate to the project directory and run:

safety codebase init

Follow the prompts to name the code base and set up initial scanning.

A "codebase" in Safety refers to a project that is tracked and monitored by the Safety Platform. When a codebase is configured, any package installations or removals within that directory will automatically trigger scans and update the project's security status in the Safety Platform.

Configuration Options

Supported Package Managers

Safety Firewall currently supports the following package managers:

• pip: Supported user-wide and per project

• uv: Supported user-wide and per project. Safety writes your user uv.toml, not uv's system file at /etc/uv/uv.toml or %PROGRAMDATA%\uv\uv.toml

• npm: Supported user-wide and per project

• poetry: Supported per project

Safety configures Poetry by adding a source to a project's pyproject.toml, so a Poetry project that Safety has not configured resolves from PyPI directly. See How Each Package Manager Is Configured.

Additional package managers will be added in future updates.