These pages describe PrivacyFence 4.6.1. Download it · What changed

Configuration reference¶

PrivacyFence reads two configuration files:

• settings.yaml: your policy and the daemon's own settings. It carries no secrets. Most of it is edited from PrivacyFence Settings; this page lists every key, including the ones with no control there.
• org_config.json: the organization config bundle. It holds the app credentials for each connected service and, for an organization deployment, the server and identity-provider settings. An administrator builds it with scripts/build_org_bundle.py and people install it from Settings > General > Organization Configuration (or it is placed on the server by hand).

Where both files live on each platform is in Platform support. Both are owned by PrivacyFence's service account on a packaged install, so editing either by hand needs administrator rights.

The command-line options of privacyfence-app are at the end of this page (Command-line options).

How settings.yaml is read¶

• First start. If settings.yaml does not exist, the daemon creates it from the packaged example (src/privacyfence/resources/settings.yaml.example). The Seeded column below is the value that example writes.
• Missing keys. A key that is absent (or commented out) takes the Code default. Where the two columns differ, a fresh install behaves as Seeded and an install whose file lacks the key behaves as Code default.
• When changes apply. A change made from Settings applies straight away. A hand edit to the file applies at the next daemon start.
• Validation. An invalid privacy-filter value, step-up scope or batch, or an unreadable file stops the daemon at start with a configuration error naming the key. Auto-accept rules it cannot read are dropped, never treated as a match.
• Organization mode. The server's own settings.yaml is install-wide: privacy, the other *_privacy groups, pii_detection, logging and web.approvals apply to everyone, and web.mcp.enabled must be true. Each person also gets a settings.yaml of their own, of which only the auto_accept section is used. Keys marked local mode only have no effect on an organization server.

Earlier policy sections¶

A settings.yaml that contains an auto_accept_rules or auto_accept_grants section (even an empty one) is refused at start with a configuration error naming the section. Rules in those sections are not converted: remove the section and recreate the rules on the Auto-accept page.

If the same file also carries the top-level marker migrated_to_policy_v2: true, its rules are already in the auto_accept section. The daemon then removes auto_accept_rules, auto_accept_grants and the marker, rewrites the file, logs a warning naming what it removed, and starts. If the rewrite fails, it starts anyway and tries again next time. See ADR 0041 and ADR 0047.

settings.yaml keys¶

Privacy filter¶

Six groups, one per kind of data, each with a default_policy and per-category values. Each value is allow (pass unchanged), redact (replace with a placeholder that gives only the length; for a list-shaped category, same as block) or block (replace with [BLOCKED BY PRIVACY FILTER]). The filter applies before you see the data on a card, and it is a minimum: approvals still apply. Edited from Settings > Privacy Filter. Details: Approvals and policy.

Code defaults: a category that is not listed takes its group's default_policy. A group that is missing altogether is allow for everything in local mode and block for everything on an organization server.

file_metadata and file_list overlap (both can show a file's name and owners). If one is allow and the other is not, the daemon logs a warning at start.

Connector behaviour¶

PII detection¶

The PII check scans content shown on a card for likely personal data (bank account numbers, card numbers, national ID and tax numbers and similar, in English, German and Hungarian; email addresses and phone numbers are not detected) and asks for a second confirmation when it finds some. See PII detection keywords and Approvals and policy.

Auto-accept rules¶

The auto_accept section holds the rules that let a gated call run without a card. It is written by the Always allow button, Settings > Auto-accept and privacyfence_propose_policy_change, which all validate the rule and compute its id; prefer them to hand-editing. The scopes, verbs and conditions a rule can use are in Approvals and policy.

The seeded rule auto-accepts contact edits that change no email address or phone number. A missing or empty auto_accept section means nothing auto-accepts.

Logging and updates¶

Web server and MCP (local mode only unless noted)¶

Local file transfers¶

Passkey step-up (local mode)¶

Step-up asks for a fresh passkey (Face ID, Touch ID, Windows Hello) before an approving decision is released, and before a sensitive settings change (rules, grants, privacy policy, PII settings). Denying never needs one. Passkeys are enrolled at /security, linked from Settings > General > Security > Manage passkeys. An organization server reads the bundle's step_up section instead (below). Details: Approvals and policy and Security and compliance.

"Packaged install" means the macOS .pkg, the Windows installer or the .deb, which are privilege-separated. A source checkout or a pip/pipx install defaults both keys off. A value written in the file always wins over these defaults, in either direction.

The Turn on button. Once at least one passkey is enrolled, Settings > General > Security shows Step-up for approvals with a Turn on button. It writes step_up.enabled: true and step_up.require_passkey: true together and takes effect immediately, with no restart. There is no control to turn step-up off: set step_up.require_passkey (and step_up.enabled) to false in the file and restart. Changing scope or batch also needs a file edit and a restart. The button is not shown on an organization server.

AI system names¶

Keys the daemon does not read¶

Organization config bundle (org_config.json)¶

Build the bundle with scripts/build_org_bundle.py (Python standard library only; --sign-key and --generate-signing-key also need the cryptography package). Pass only the options for the services you have registered: a connector is offered only if its section is in the bundle. Install it from Settings > General > Organization Configuration. Per-service registration steps are in Google Cloud setup, Slack setup, Salesforce setup and Atlassian setup; Telegram needs no bundle entry (Telegram setup). The server side of an organization deployment is in Organization deployment.

How the daemon treats the file:

• Absent: local mode, and every connector that needs organization credentials is unavailable.
• Unreadable, not valid JSON, or not a JSON object: the daemon refuses to start.
• Signed: the first signed bundle an install reads pins its signing key; from then on every bundle, unsigned ones included, must verify against that key or the daemon refuses to start. To accept a new key, an administrator deletes the pinned org_config_signing_pubkey.txt in the organization config directory.
• "mode": "org": the bundle must be signed.

Build options¶

The organization-only options (--server-*, --idp-*, --authz-*, --step-up-*, --downloads-*, --agent-links, --audit-forwarding-*) are refused unless the bundle is in organization mode (--mode org, or --merge into a bundle that already has it).

Bundle keys not written by build_org_bundle.py¶

The Google, Slack, Salesforce and Atlassian redirect URIs to register for an organization deployment are listed in Organization deployment.

Command-line options¶

privacyfence-app is the daemon's executable. On a packaged install the service starts it; the options below are for running it by hand.

The sign-in options are for an install that is not privilege-separated (a source checkout or a pip/pipx install). On a packaged install the daemon refuses to run as your account, so they fail; connect services from Settings > Connectors instead (see Connecting a service). They need the organization config bundle installed first, except --telegram-setup.