Privacy Flow Inspector

Which personal data leaves the browser, who receives it, and how?

Privacy Flow Inspector reads recorded web traffic (HAR files from Chrome, Firefox or Playwright) and reports every place where personal data is sent: in URLs, headers, cookies, JSON, forms, Base64 blobs or login tokens, including hashed forms that ad pixels use. It groups recipients into first and third parties, applies your policy and gives an APPROVE / REVIEW / REJECT decision for CI. It works offline. Reports contain no raw personal data, and it can export a redacted HAR that is safe to attach to a ticket.

Status: v0.2.0, an alpha release on PyPI and the GitHub Marketplace. Tested on Windows, Linux and macOS, including a demo that CI re-records with real Chromium on every run. Findings are technical evidence for a privacy review, not legal advice or a GDPR compliance verdict.

Part of a small software trust toolkit with Software Intake Gatekeeper: the Gatekeeper checks what is inside an app; this tool checks what the app sends out. Both use the same decision model, policy style and report formats.

Where it helps

Quick start

Install from PyPI (Python 3.11+) and scan a HAR file:

python -m pip install privacy-flow-inspector

privacy-flow-inspector scan session.har --config pfi.toml `
  --json reports/report.json --sarif reports/report.sarif --markdown reports/summary.md `
  --redact-dir reports/redacted

Exit status: 0 the decision passed --fail-on (default reject), 1 the gate failed, 2 usage or input error. privacy-flow-inspector rules lists the detectors.

Recording a HAR

Use content="embed": with omit or attach, Playwright leaves request bodies out of the HAR. The inspector detects this and reports a blocking body-not-recorded gap instead of approving.

Try the fictional demo

examples/demo-shop is a deliberately leaky, fictional health shop. scripts/record_demo.py drives it with real Chromium and answers every request locally, so nothing leaves the machine. The recorded capture is committed as examples/recorded/demo-shop.har.

privacy-flow-inspector scan examples/recorded/demo-shop.har --config examples/pfi.toml

Real output:

Decision: REJECT
  - 6 data flow(s) at or above high.
  - 4 data flow(s) between low and high.
Requests: 10 | recipients: 7 (6 third-party) | personas: 3
Findings: critical 1, high 5, medium 2, low 2, info 4
  [CRITICAL] PFI-PERSONA          Test user email sent to legacy-ads.test via query
  [HIGH    ] PFI-PRECISE-LOCATION Precise location sent to geo-widgets.test via query
  [HIGH    ] PFI-IBAN             IBAN sent to payments-processor.test via body (allowed)
  [HIGH    ] PFI-PERSONA          Test user email sent to pixel-tracker.test via query
  [HIGH    ] PFI-PERSONA          Test user phone sent to pixel-tracker.test via query
  [HIGH    ] PFI-DE-KVNR          German health insurance number (KVNR) sent to session-cam.test via body
  [HIGH    ] PFI-HEALTH-FIELD     Health data field sent to session-cam.test via body
  [MEDIUM  ] PFI-PERSONA          Test user email sent to analytics-vendor.test via body
  ...

The Markdown summary contains a data-flow map:

What the demo shows:

• Hashed email and phone sent to an ad pixel (sha256(plain), sha256(digits)).
• An email inside a nested page URL sent over plain HTTP: critical.
• A session-replay vendor receiving a Base64-wrapped form with a health-insurance number and an ICD-10 diagnosis: health data, a GDPR Article 9 special category.
• A payment processor marked allowed because the config lists it as a contracted processor.
• First-party traffic still shows up (as info/low) so reviewers see the whole picture.

How it works

flowchart LR
    H[HAR files] --> P[Bounded HAR parser]
    P --> X[Value extraction: URL, query, headers, cookies, JSON, form, multipart, Base64, JWT, nested URLs]
    X --> D1[Test-persona matching incl. hashes]
    X --> D2[Checked detectors]
    D1 & D2 --> R[Recipient: eTLD+1, first/third party]
    R --> S[Severity: category, party, channel, transport]
    S --> Pol[Policy: approved processors, expiring waivers]
    Pol --> Dec{APPROVE / REVIEW / REJECT}
    Dec --> O[JSON, SARIF, Markdown, redacted HAR]

Detectors

The test-persona detector gives the most reliable results. Use a dedicated test account in your end-to-end tests, list its values in the config, and every encoded or hashed copy is found with essentially no false positives.

Every report lists all third-party recipients and their request counts, including those that received no detected personal data. To gate on those connections too, enable the opt-in rule:

[detectors]
enabled = ["PFI-THIRD-PARTY-CONNECTION"]

Approve a recipient you have a legal basis for with an [[allow]] entry for the online-identifier category.

Severity

Severity starts from the data category and then moves up or down:

For example, an email in a JSON body to your own HTTPS API is info. The same email in a third-party URL over HTTP is critical.

Configuration

See examples/pfi.toml:

version = 1

[gate]
reject_at = "high"
review_at = "low"

[first_party]
domains = ["shop.example"]

[[persona]]
label = "Test user email"
value = "jane.test@example.com"
category = "contact"

# Contracted processors (GDPR Art. 28) may receive the listed categories.
[[allow]]
recipient = "payments-processor.test"
categories = ["financial", "contact"]
reason = "Payment processor with a signed data processing agreement."

[[waivers]]
id = "PFI-IP-ADDRESS"
recipient = "cdn.example"
reason = "CDN logs are covered by the hosting contract; reviewed by the DPO."
expires = 2026-12-31

Unknown keys are rejected. Persona values must be invented test data, never real people. Allowances and waivers need written reasons, and waivers expire. Without [first_party], the first page's site is used and the report says so.

GitHub Action

name: Privacy flows
on: [pull_request]

permissions:
  contents: read
  security-events: write   # only for the SARIF upload

jobs:
  e2e-privacy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      # ... run your Playwright tests with recordHar content "embed" into test-results/ ...
      - name: Privacy Flow Inspector
        id: privacy
        uses: Sushant-Nemade/privacy-flow-inspector@v0
        with:
          har: test-results/**/*.har
          config: .github/pfi.toml
          fail-on: reject
      - name: Upload SARIF
        if: always() && steps.privacy.outputs.sarif != ''
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: ${{ steps.privacy.outputs.sarif }}
          category: privacy-flow-inspector

Outputs: decision and sarif. The Markdown summary is added to the job summary. The action uses hash-pinned dependencies in a private virtual environment, needs no token and makes no network requests. Do not upload raw HAR files as workflow artifacts; upload the redacted copies instead.

Privacy by design

• Offline: no network access and no telemetry.
• No raw values in reports: each value appears only as a short mask (ja********om) and a keyed fingerprint, so the same value can be correlated within one report without being revealed.
• Redacted HAR export: detected values and their encoded forms are replaced, Authorization, Cookie and Set-Cookie values are removed, and response bodies are dropped. The file is re-checked and not written if anything would remain.
• Bounded parsing of untrusted input, and escaping of all capture-derived text in Markdown.

Verification

Limitations

• Only what the HAR contains is checked. WebSocket messages, service-worker traffic and requests made before recording started may be missing.
• Binary or compressed payloads (protobuf, gzip in JSON) are not decoded.
• Field-name detectors depend on meaningful field names. The test-persona detector does not.
• Domains are grouped by registrable domain; a vendor serving from your own subdomain (CNAME cloaking) looks first-party. Name it under [labels] and review it.
• A finding is evidence for a privacy review. Whether a flow is lawful depends on purpose, consent and contracts, which the tool cannot see.

Development

python -m pip install uv
uv sync --frozen --extra dev
uv run --frozen --extra dev pytest -q
uv run --frozen --extra dev playwright install chromium   # optional, for the recording test
$env:PFI_RECORD = "1"; uv run --frozen --extra dev pytest -q tests/test_record.py

License

MIT © 2026 Sushant Nemade. See SECURITY.md for vulnerability reporting. Recipient grouping uses publicsuffixlist (MPL-2.0) with the bundled Public Suffix List.