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 is persistent and applies to any command the package manager runs, whether or not it was intercepted.

How Each Package Manager Is Configured

The Safety index proxies the public PyPI and npm registries. safety init points each package manager at it.

Package manager	System-wide	Per project
pip	index-url in your user pip.conf	-i <index-url> line added to requirements files
uv	An index entry in your user uv.toml	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.

What Can Override Your Configuration

Package managers read configuration from more than one location, and the setting closest to the command wins. Four things override what safety init writes.

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

2. An environment variable such as PIP_INDEX_URL, which overrides your user configuration file.

3. A configuration file closer to the project. A pip.conf inside an active virtual environment overrides your user pip.conf.

4. A managed platform that sets an index for you. Hosted notebook and cluster platforms configure a package index at the workspace or cluster level, above anything a startup script writes.

How each package manager handles more than one index decides what the first three mean for you.

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. pip's own documentation describes the risk.

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.

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

uv stops at the first index that carries a package name, so an added index does not compete for names the Safety index already serves.

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

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.

For uv and Poetry, check the index entries in uv.toml or 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 system-wide and per project

• uv: Supported system-wide and per project

• npm: Supported system-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.