Metadata-Version: 2.4
Name: wj-firewall
Version: 1.0.0b1
Summary: macOS PF (Packet Filter) firewall configuration TUI
Project-URL: Source, https://gitlab.com/waterjuice/wj-firewall
Author: WaterJuice
License-Expression: Unlicense
License-File: LICENSE
Keywords: curses,firewall,macos,packet-filter,pf,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# wj-firewall

A macOS PF (Packet Filter) firewall configuration tool with both an interactive terminal UI and a command-line interface.

wj-firewall is not a firewall itself — it configures macOS's built-in PF packet filter. It makes it easy to block incoming traffic on specific network interfaces while keeping others open. The typical use case is blocking incoming connections on Wi-Fi while keeping Tailscale or other trusted networks open, so services listening on `0.0.0.0` are only reachable from trusted networks.

## Features

- **Interactive TUI** — curses-based terminal UI for visual interface management
- **CLI** — scriptable command-line interface for automation and quick changes
- **Per-interface blocking** — block incoming traffic on selected interfaces
- **Port exceptions** — allow specific ports through on blocked interfaces (TCP + UDP)
- **ICMP control** — optionally block ICMP (ping, traceroute) on blocked interfaces
- **PF anchors** — rules stored in `/etc/pf.anchors/wj-firewall`, surviving OS updates
- **Zero dependencies** — Python 3.12+ stdlib only

## Requirements

- Python 3.12+
- macOS (uses PF and pfctl)
- Administrator privileges (sudo) for applying firewall rules

## Installation

```bash
pip install wj-firewall
```

Or run directly with uv:

```bash
uvx wj-firewall
```

## Quick Start

### Interactive TUI

```bash
wj-firewall
```

You will be prompted for your password (sudo). The TUI shows all network interfaces and lets you:

- **Space** — toggle "block incoming" on the selected interface
- **p** — open port editing mode (add/remove port exceptions)
- **i** — toggle ICMP blocking on a blocked interface
- **a** — apply changes (writes anchor file and reloads PF)
- **r** — revert to last applied state
- **q** — quit (confirms if unsaved changes)

### Command-Line Interface

```bash
# Show current firewall status
wj-firewall status

# Block incoming traffic on Wi-Fi
wj-firewall block en0

# Allow SSH and HTTP through on a blocked interface
wj-firewall allow en0 22 80

# Block ICMP (ping) on an interface
wj-firewall icmp en0 block

# Remove a port exception
wj-firewall deny en0 80

# Unblock an interface
wj-firewall unblock en0
```

## How It Works

wj-firewall uses macOS PF anchors to manage firewall rules without touching the rest of your `pf.conf`. Rules are stored in `/etc/pf.anchors/wj-firewall` and referenced from `pf.conf` via anchor declarations. The tool automatically adds the anchor references if they are missing.

For each blocked interface, the following PF rules are generated:

1. **Pass outgoing** — all outbound traffic and return traffic is allowed
2. **Pass DHCP** — DHCP discovery is always allowed (so you can get an IP address)
3. **Pass ICMP** — ping, traceroute, and PMTU discovery are allowed (unless ICMP is blocked)
4. **Pass ports** — any port exceptions are allowed through (both TCP and UDP)
5. **Block everything else** — all other incoming traffic is silently dropped

Rules use `quick` for first-match-wins evaluation and `block drop` (silent discard) to avoid triggering macOS Private Relay issues.

## Development

```bash
# Set up development environment
make dev

# Run linting and type checking
make check

# Auto-format code
make format

# Build wheel and docs
make build
```

## Licence

Released under the [Unlicense](https://unlicense.org/) — public domain.
