If you discover a security vulnerability in pfSentinel, please do not open a public GitHub issue.

Instead, report it through one of these channels:

• Contact form: nx1xlab.dev/contact
• GitHub private reporting: privately report a vulnerability on this repository

Please include:

• A description of the vulnerability and its potential impact
• Steps to reproduce or a proof-of-concept (if applicable)
• The version of pfSentinel where you found the issue

I will do my best to acknowledge your report promptly and work toward a fix. This is a community-driven project, so response times may vary. Contributions to security fixes are welcome.

The following behaviors are intentional design decisions for homelab use cases. They are documented here for transparency.

Behavior: pfSentinel uses paramiko.WarningPolicy for SSH connections. Unknown host keys are logged as warnings but the connection proceeds.

Reason: Home firewall host keys frequently change (firmware updates, full reinstalls). Strict rejection would break backups silently after common maintenance events in a homelab environment.

Risk: An attacker on your local network capable of ARP spoofing could perform a man-in-the-middle attack on SSH connections. This is unlikely in a typical homelab but is a real threat on untrusted networks.

Mitigation: Set strict_host_keys: true in your device config (or use --strict-host-keys when adding a device). This uses paramiko.RejectPolicy — the host must already be in ~/.ssh/known_hosts or the connection is refused.

Additional steps:

1. Pre-populate ~/.ssh/known_hosts for your pfSense device: ssh-keyscan -p 22 <host> >> ~/.ssh/known_hosts
2. Use SSH key authentication instead of passwords.c
3. Prefer SSH over HTTPS as the primary connection method.

Behavior: verify_ssl defaults to True. It can be set to False per-device (via --no-verify-ssl at device-add time, or in the config file).

Reason: pfSense ships with a self-signed certificate. Many homelab users do not have a trusted CA certificate installed. Disabling verification allows HTTPS backup without certificate management overhead.

Risk: When verify_ssl=False, HTTPS connections are vulnerable to man-in-the-middle attacks. An attacker could intercept the session and steal the pfSense admin password.

Recommendation: Use SSH (the default and recommended connection method) rather than HTTPS. SSH does not depend on TLS certificates.

Behavior: pfSentinel supports HTTP (unencrypted) as an explicit fallback connection method.

Risk: HTTP transmits the pfSense admin username and password in cleartext. Any device on the same network can capture these credentials with a packet sniffer.

When it might be used: Some very old pfSense installations with HTTP-only access. Use SSH or HTTPS whenever possible.

Passwords and tokens are stored in the OS-native keyring:

Note on headless/WSL fallback: When no native keyring is available, pfSentinel tries backends in this order:

1. EncryptedKeyring — encrypts credentials with a master password at ~/.local/share/python_keyring/crypted_pass.cfg. You will be prompted for the master password on first use.
2. PlaintextKeyring — stores credentials unencrypted at ~/.local/share/python_keyring/keyring_pass.cfg. File permissions are automatically set to 0o600 (owner-only). A warning is logged.
3. In-memory — credentials are lost when the process exits.

If you are on PlaintextKeyring, consider installing a system keyring backend or verify permissions manually:

chmod 600 ~/.local/share/python_keyring/keyring_pass.cfg

pfSentinel does not log passwords, tokens, or credential values. Log files contain only hostnames, operation status, and error messages. Verify with --debug if you are unsure what is being recorded.

To audit dependencies locally:

pip install pip-audit
pip-audit

For a full license and dependency audit, see docs/LICENSE_AUDIT.md.

pfSentinel does not require or request administrator/root privileges for normal operation.

This is a solo-maintained community project. The following is a best-effort process for handling security incidents.

1. Triage — When a vulnerability report is received (via private reporting or contact form), I will acknowledge receipt and assess severity.
2. Fix — A patch is developed in a private fork or branch. For critical/high severity issues, this takes priority over other work.
3. Release — A new patch release is published with the fix. The security changelog below is updated.
4. Disclosure — A GitHub Security Advisory is published with details, affected versions, and upgrade instructions. If the vulnerability was reported by a researcher, they are credited (unless they prefer anonymity).
5. Notification — Release notes and the advisory will describe the fix. Users on older versions should upgrade promptly.

For critical vulnerabilities with evidence of active exploitation, a fix will be released as quickly as possible and the advisory will note the urgency.

A living record of security findings, fixes, and hardening measures. For the full initial audit report, see docs/security-audit.md.

Fixes applied from pre-release audit (19 findings, all fixed):

Additional hardening measures: