Dependency Firewall User Guide

The Dependency Firewall validates imports against an explicit policy.

What it protects you from

• Risky patterns (example: shell execution helpers)
• Unknown dependencies (packages not in your allowlist)
• Typosquatting (misspelled packages that look like common dependencies)

Policy file

The policy lives at:

• .ranex/firewall.yaml

Create it with:

ranex init

Policy modes

• strict
  • Not-allowed packages are treated as blocked.
• audit_only
  • Intended for reporting; enforcement is relaxed.
• disabled
  • Turns off firewall decisions.

Using the firewall from the CLI

• Check one import: ranex firewall check-import <import_path>
  • Exit code 0 when allowed
  • Exit code 2 when blocked/unknown/typosquat
• Check many imports: ranex firewall check-imports <import_path>...
• Analyze a file: ranex firewall analyze-file <file_path>
• Typosquat check: ranex firewall typosquat <package_name>
• Inspect policy:
  • ranex firewall info
  • ranex firewall list-rules
  • ranex firewall allowed-packages
  • ranex firewall blocked-patterns
  • ranex firewall policy-mode

Using the firewall from Python

• Create: Firewall(project_root)
• Check: check_import(...), check_imports(...)
• Analyze a file: analyze_file(...)

Common results

Firewall decisions are summarized with:

• allowed (boolean)
• status (string)
• reason (string)
• suggestion (string; when applicable)

Recommended workflow

• Keep .ranex/firewall.yaml in version control.
• In CI:
  • Run import checks or file analysis on changed files.
• For AI-assisted coding:
  • Require AI to propose new dependencies explicitly.
  • Validate them with the firewall before accepting the change.