> For the complete documentation index, see [llms.txt](https://docs.safetycli.com/safety-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.safetycli.com/safety-docs/firewall/installation-and-configuration.md).
# 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
{% hint style="warning" %}
Safety Firewall works with pip, uv, poetry, and npm. We'll automatically detect and configure the package managers on your system.
{% endhint %}
## Before You Begin
### Create a Safety Account
If you don't already have a Safety account, [sign up here](https://platform.safetycli.com/register).
### 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](mailto:support@safetycli.com).
{% hint style="info" %}
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](mailto:support@safetycli.com).
{% endhint %}
## 1. Installation
### 1.1 Install Safety CLI
Open your terminal and run the following command:
{% tabs %}
{% tab title="pip" %}
```bash
pip install safety
```
{% hint style="info" %}
If you already have Safety installed, please use `pip install -U safety` . The minimum version required to run Safety Firewall is v3.5.0.
{% endhint %}
{% endtab %}
{% tab title="UV" %}
```bash
uv tool install safety
```
{% endtab %}
{% endtabs %}
### 1.2 Authenticate with Safety
Run the authentication command:
```bash
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:
```bash
safety auth status
```
This should display your email address and confirm that you're authenticated.
{% hint style="warning" %}
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.
{% endhint %}
## 2. Initialization of Safety Firewall
After installing the Safety CLI and authenticating your account, you can initialize Safety Firewall with a single command:
```bash
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
{% hint style="warning" %}
**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.
{% endhint %}
## 3. Verifying Firewall Installation
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
{% tabs %}
{% tab title="Mac/Linux" %}
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
```bash
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.
{% endtab %}
{% tab title="CMD.exe" %}
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
```bash
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.
{% endtab %}
{% tab title="PowerShell" %}
After initialization, you can verify that Safety Firewall is correctly installed by checking your package manager aliases:
```bash
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.
{% endtab %}
{% endtabs %}
## 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](#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 ` 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 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](https://pip.pypa.io/en/stable/cli/pip_install/)
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](#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:
```bash
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:
```bash
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:
```bash
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:
```bash
command uv pip install --dry-run --refresh -v
```
Read the `Sending fresh GET request for: //` 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)
{% hint style="info" %}
Most users won't need to manually edit these files. Configuration changes are typically made through the Safety CLI or Safety Platform
{% endhint %}
## 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:
```bash
safety codebase init
```
Follow the prompts to name the code base and set up initial scanning.
{% hint style="info" %}
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.
{% endhint %}
### 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](#how-each-package-manager-is-configured).
Additional package managers will be added in future updates.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.safetycli.com/safety-docs/firewall/installation-and-configuration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
