Metadata-Version: 2.4
Name: pfsense-redactor
Version: 1.2.0
Summary: Enterprise-grade tool to redact secrets and anonymise identifiers in pfSense/Netgate config.xml exports. Preserves network topology while removing passwords, VPN keys, certificates, public IPs, domains, and MACs for safe sharing with support teams, consultants, AI tools, and forums.
Author: pfSense Redactor Contributors
License: MIT
Project-URL: Homepage, https://github.com/grounzero/pfsense-redactor
Project-URL: Repository, https://github.com/grounzero/pfsense-redactor
Project-URL: Bug Tracker, https://github.com/grounzero/pfsense-redactor/issues
Project-URL: Documentation, https://github.com/grounzero/pfsense-redactor#readme
Project-URL: Changelog, https://github.com/grounzero/pfsense-redactor/blob/main/CHANGELOG.md
Project-URL: Source Code, https://github.com/grounzero/pfsense-redactor
Keywords: pfsense,netgate,firewall,configuration,config,config.xml,security,privacy,redaction,anonymiser,anonymizer,sanitiser,sanitizer,xml,vpn,wireguard,openvpn,ipsec,config-sanitizer,data-privacy,gdpr,compliance,network-security,firewall-management,devops,automation,msp,managed-services,siem,log-sanitization,pfsense-plus,pfsense-ce,netgate-tnsr
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Framework :: Pytest
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest==9.1.1; python_version >= "3.10" and extra == "dev"
Requires-Dist: pytest==8.4.2; python_version < "3.10" and extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: pytest-xdist==3.8.0; extra == "dev"
Dynamic: license-file

# pfSense XML Configuration Redactor

[![PyPI version](https://badge.fury.io/py/pfsense-redactor.svg)](https://pypi.org/project/pfsense-redactor/)
[![Python Versions](https://img.shields.io/pypi/pyversions/pfsense-redactor.svg)](https://pypi.org/project/pfsense-redactor/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/grounzero/pfsense-redactor/actions/workflows/tests.yml/badge.svg)](https://github.com/grounzero/pfsense-redactor/actions/workflows/tests.yml)
[![Downloads](https://pepy.tech/badge/pfsense-redactor)](https://pepy.tech/project/pfsense-redactor)

Redact secrets from a pfSense `config.xml` so you can share it with Netgate
support, a vendor, a forum or an AI tool, without handing over your passwords,
keys and network layout.

Unlike generic XML redaction, it understands pfSense structures: IPsec, OpenVPN,
WireGuard, captive portal, and the package configs where credentials actually
hide.

## Install

```bash
pip install pfsense-redactor
```

Pure Python standard library, no dependencies, Python 3.9+.

<details>
<summary>If pip reports <code>externally-managed-environment</code></summary>

Common on macOS and recent Linux distributions. Any of these work:

```bash
pipx install pfsense-redactor          # recommended for CLI tools
```

```bash
python3 -m venv venv && source venv/bin/activate
pip install pfsense-redactor
```

```bash
pip install --user pfsense-redactor
```

</details>

<details>
<summary>From source</summary>

```bash
git clone https://github.com/grounzero/pfsense-redactor.git
cd pfsense-redactor
pip install -e .
```

</details>

## Quick start

**Sharing with support, keeping internal addressing readable:**

```bash
pfsense-redactor config.xml redacted.xml --keep-private-ips
```

Removes secrets and public identifiers, leaves RFC 1918 addressing intact so
whoever is helping can still follow your topology.

**Sharing with a vendor, forum or AI tool, anonymising identifiers:**

```bash
pfsense-redactor config.xml redacted.xml --anonymise
```

Replaces addresses and domains with consistent placeholders, so relationships
between rules and interfaces survive while the real values do not.

**Check before you commit to it:**

```bash
pfsense-redactor config.xml --dry-run-verbose
```

Prints what would change, with samples safely masked.

**Using an unusual package?** Add `--aggressive`. Webhook tokens live in URL
paths, and paths are otherwise preserved so package feed URLs are not destroyed.
Slack, Discord and Telegram are recognised and redacted without it; anything
else needs the flag. See
[security](https://github.com/grounzero/pfsense-redactor/blob/main/docs/security.md#what-gets-redacted).

## How well does it work?

Measured against a 46-secret canary corpus that ships with the repository:

| Tool | Caught |
| --- | --- |
| **pfsense-redactor** | **44 / 46** (45 with `--redact-descriptions`) |
| ForesightCyber Config Anonymizer | 17 / 46 |
| netgate-xlsx | 11 / 46 |

The corpus was built alongside this tool, which biases it. Every released
version was re-run against it to measure by how much: 31 of the 46 markers were
planted against gaps this tool had, and none came from outside the project. Both
misses are documented rather than hidden. Run it yourself:

```bash
pfsense-redactor tests/corpus/canary-corpus.xml --stdout --aggressive \
  | grep -oE 'CANARY_[A-Z0-9_]+' | sort -u
```

Full method, caveats and per-secret results in
[the benchmark](https://github.com/grounzero/pfsense-redactor/blob/main/docs/benchmark.md).

## Before you share the output

> **Never restore a redacted file to pfSense.** Comments, CDATA and some
> metadata do not survive the round trip. Keep your original.

Read the run summary. It reports high-entropy values it deliberately *kept*,
with their element paths, so you can audit them. For a second opinion from a
scanner that fails differently, see
[verifying output](https://github.com/grounzero/pfsense-redactor/blob/main/docs/verifying-output.md).

## Documentation

| Guide | Covers |
| --- | --- |
| [CLI reference](https://github.com/grounzero/pfsense-redactor/blob/main/docs/cli-reference.md) | Every flag, with examples |
| [Use cases](https://github.com/grounzero/pfsense-redactor/blob/main/docs/use-cases.md) | Netgate TAC, AI tools, MSP handoff, audits, and how this relates to `diag_sanitize.php` |
| [Allow-lists](https://github.com/grounzero/pfsense-redactor/blob/main/docs/allow-lists.md) | Keep specific IPs, CIDRs and domains readable |
| [Security](https://github.com/grounzero/pfsense-redactor/blob/main/docs/security.md) | Threat model, what gets redacted, path safety |
| [Verifying output](https://github.com/grounzero/pfsense-redactor/blob/main/docs/verifying-output.md) | Checking the result, and using gitleaks alongside |
| [Benchmark](https://github.com/grounzero/pfsense-redactor/blob/main/docs/benchmark.md) | Canary corpus results and known gaps |
| [Examples](https://github.com/grounzero/pfsense-redactor/blob/main/docs/examples.md) | Before/after output, statistics, testing |
| [FAQ](https://github.com/grounzero/pfsense-redactor/blob/main/docs/faq.md) | Common questions |
| [Changelog](https://github.com/grounzero/pfsense-redactor/blob/main/CHANGELOG.md) | Release history |

## Contributing

Issues and pull requests are welcome. If you find a secret that survives
redaction, that is the most valuable report there is. A minimal fragment with
the value replaced by a `CANARY_*` marker can go straight into the corpus so the
miss stays fixed.

Run the tests with:

```bash
pip install -e ".[dev]"
pytest
```

## Licence

MIT. See [LICENSE](https://github.com/grounzero/pfsense-redactor/blob/main/LICENSE).
