PIIFlow v0.3.0 — Policy-Aware Privacy Flow Analysis

PIIFlow v0.3.0 Release Notes

PIIFlow v0.3.0 adds policy-aware privacy-boundary evaluation on top of the
existing static taint analyzer. The feature set is frozen for this release:
source-code flow detection remains separate from policy decisions, and policy
fields are additive in text and JSON reports.

Major Capabilities

• Static Python AST analysis without executing target applications.
• Structured taint propagation through bounded containers, attributes, aliases,
  helpers, imports, async handlers, and method calls.
• Sensitive-data classification for email, phone, medical, financial,
  government ID, and location signals.
• Sanitizer provenance on the actual propagation path.
• LLM sink provider and trust-zone metadata.
• YAML policy files with first-match allow, deny, and
  require_sanitizer actions.
• Reproducible original and policy benchmark runners.

Original Benchmark Metrics

Frozen 90-case synthetic flow benchmark:

Metric	Value
Precision	0.9545454545454546
Recall	0.84
F1	0.8936170212765958
Accuracy	0.8888888888888888
TP / FP / TN / FN	42 / 2 / 38 / 8

Hashes:

• Manifest:
  2335f30a119652db32aca3163e4b1a4d91a1e2bb8331cec51d247cd444ee51c7
• Content:
  a34c9817f0da31aaf4bd8a9590796614c62cbf33137b6486c3192d794f361f94

Policy Benchmark Metrics

The separate synthetic policy benchmark has 36 cases: 24 in-scope, 12
challenge, 20 violations, and 16 compliant flows.

System	Precision	Recall	F1	Accuracy	TP	FP	TN	FN
policy_blind	0.5555555555555556	1.0	0.7142857142857143	0.5555555555555556	20	16	0	0
piiflow_policy	1.0	1.0	1.0	1.0	20	0	16	0

Hashes:

• Manifest:
  694cf6af4faa5cf7e002a57d650ee3e6ad7aa1204b9d0db0f2c96edcc20a3511
• Content:
  be63a102eff6f4c89100221f153f713dda74475662c5783c257d46efd2eddc66

PIIFlow achieved 1.00 F1 on the 36-case synthetic policy benchmark. This does
not imply perfect real-world behavior.

Benchmark Limitations

Benchmarks are synthetic, small, and project-specific. They do not validate
runtime behavior, legal compliance, production completeness, or performance
against CodeQL, Pysa, Semgrep, commercial tools, or other languages.

Installation

From a checkout:

uv sync --extra dev
uv build
uv pip install dist/piiflow-0.3.0-py3-none-any.whl

Quick Start

uv run piiflow scan examples/vulnerable_app
uv run piiflow scan examples/policy_apps/redacted_email.py --policy examples/policies/sanitized_email.yml

Known Limitations

Known misses include closures, nested functions, dynamic attributes, dynamic sink
construction, exception-flow propagation, framework-generated values,
generators, and implicit/control-flow taint. Known false positives include
decorator-provided sanitization and runtime target checks that are outside the
static model.

Upgrade Notes From v0.2.0

• Use --policy policy.yml to enable policy evaluation.
• Existing scans without --policy keep flow-detection behavior.
• JSON findings may include additional policy fields when a policy is supplied.
• Sink rules can now include provider and trust_zone; omitted metadata
  defaults to generic and external.

Acknowledgements

PIIFlow is authored by Karan Kumar Singh.