How to Gate pip install in AI Agent Workflows

SafeClaw by Authensor blocks pip install commands by default when AI agents attempt them, stopping unauthorized Python packages from entering your environment. Install SafeClaw with npx @authensor/safeclaw and every pip invocation — including pip3, python -m pip, and uv pip — is intercepted, denied, and logged until explicitly allowed.

Why pip install Is Dangerous When AI Agents Do It

Python's package ecosystem has no built-in install-time sandboxing. When an AI agent runs pip install, the package's setup.py executes arbitrary Python code during installation — before you ever import it. Agents hallucinate package names regularly; a nonexistent package name may match a malicious squatter on PyPI. Dependency confusion attacks are well-documented: internal package names that overlap with PyPI names let attackers inject code via --extra-index-url configurations. An agent installing packages also modifies the environment's dependency tree, potentially breaking version constraints for existing packages. In virtual environments, this may be recoverable; in system Python, it can corrupt the host.

The Exact SafeClaw Policy to Gate pip install

Add these rules to .safeclaw/policy.yaml:

rules:
  - id: deny-pip-install
    action: shell.exec
    match:
      command: "pip install*"
    effect: deny
    audit: true
    message: "pip install is blocked. Python packages require manual review."

- id: deny-pip3-install
    action: shell.exec
    match:
      command: "pip3 install*"
    effect: deny
    audit: true
    message: "pip3 install is blocked."

- id: deny-python-m-pip
    action: shell.exec
    match:
      command: "python -m pip install"
    effect: deny
    audit: true
    message: "python -m pip install is blocked."

- id: deny-uv-pip-install
    action: shell.exec
    match:
      command: "uv pip install*"
    effect: deny
    audit: true
    message: "uv pip install is blocked."

Four rules cover the common pip invocation patterns. The python -m pip install glob catches both python -m pip and python3 -m pip. The uv pip install rule covers the increasingly popular uv package manager's pip compatibility mode.

What Happens When the Agent Tries

When a Claude or OpenAI agent attempts pip install requests:

1. SafeClaw's policy engine intercepts the shell.exec action.
2. The deny-pip-install rule matches pip install*.
3. The command is blocked. No network call to PyPI. No setup.py execution.
4. An audit entry is hash-chained to the log:

{
  "timestamp": "2026-02-13T16:45:12Z",
  "action": "shell.exec",
  "command": "pip install requests",
  "effect": "deny",
  "rule": "deny-pip-install",
  "agent": "data-analyst-02",
  "hash": "d9e3f7...chain"
}

1. The agent receives the denial and can report the required package to the operator.

How to Allow pip install with Approval

For data science workflows where agents frequently need new packages:

rules:
  - id: pip-install-approval
    action: shell.exec
    match:
      command: "pip install*"
    effect: approval
    audit: true
    approvers:
      - role: data-engineer
    timeout: 300
    message: "pip install requires data engineer approval."

To allow requirements file installs but block ad-hoc packages:

rules:
  - id: allow-pip-requirements
    action: shell.exec
    match:
      command: "pip install -r requirements*.txt"
    effect: allow
    audit: true

- id: deny-pip-all-else
    action: shell.exec
    match:
      command: "pip install*"
    effect: deny
    audit: true
    message: "Only requirements file installs are permitted."

The first rule matches pip install -r requirements.txt or pip install -r requirements-dev.txt. First-match-wins ensures it evaluates before the blanket deny. This lets agents set up known, reviewed dependencies while blocking arbitrary package additions.

Verification

npx @authensor/safeclaw simulate --action 'shell.exec' --command 'pip install numpy'
Expected: deny, rule: deny-pip-install

Related Pages

• How to Gate npm install in AI Agent Workflows
• Supply Chain Agent Attack Threat
• How to Gate Shell Command Execution in AI Agents
• Deny-by-Default Explained