POPIA Compliance Skill

Privacy and security guardrails for South African builders, for every AI coding tool.

An open-source skill that helps you build websites and apps that respect POPIA (the Protection of Personal Information Act) and prove it: a skill your AI tools load, a scanner that finds problems in your code, drop-in components that fix the common ones, and the documents an Information Officer needs.

Maintained by Venus One (Venus ARC (Pty) Ltd) and contributors.

Law current to 18 October 2026. See regulatory watch.

What's inside

Start here

New project, existing codebase or Lovable: docs/quickstart.md has a short path for each.

Install

Claude (claude.ai, Claude Desktop) and Claude Code

Download the repository as a zip and add it as a skill, or copy the folder into your skills directory (for Claude Code: .claude/skills/popia-compliance/ in a project, or ~/.claude/skills/popia-compliance/ for all projects). The skill triggers on anything touching personal information of South Africans.

Cursor, Codex, Copilot, Windsurf, Gemini, Lovable, ChatGPT

Copy the matching file from adapters/ into your project. Table and paths in adapters/README.md.

Any MCP client

claude mcp add popia -- uvx --from git+https://github.com/VenusOne-Lee/popia-compliance popia-kit mcp
# or, from a clone:
claude mcp add popia -- python3 /path/to/popia-compliance/mcp/server.py

Config for Claude Desktop, Cursor, VS Code and Windsurf: docs/mcp.md.

Quick start

Python 3.8 or newer and nothing else. No install needed: run it straight from GitHub with whichever tool you already have.

# uv
uvx --from git+https://github.com/VenusOne-Lee/popia-compliance popia-kit scan .

# pipx
pipx run --spec git+https://github.com/VenusOne-Lee/popia-compliance popia-kit scan .

# npm (still runs the Python tools, so Python 3.8+ must be installed)
npx -y github:VenusOne-Lee/popia-compliance scan .

To keep it installed: pipx install git+https://github.com/VenusOne-Lee/popia-compliance, then use popia-kit anywhere.

Prefer a clone? Every command is also a plain script:

git clone https://github.com/VenusOne-Lee/popia-compliance
cd popia-compliance
python3 scripts/popia_scan.py tests/fixtures/demo-app   # the deliberately broken demo app

In CI

# .github/workflows/popia.yml
on: [pull_request]
permissions: { contents: read, security-events: write }
jobs:
  popia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: VenusOne-Lee/popia-compliance@0192dd213a41c62c2cfeb9e11221bad4af7bc729 # v1.0.0
        with: { fail-on: high }

What the scanner checks

Run python3 scripts/popia_scan.py --list-rules for the full list. Highlights:

• Access control: Supabase tables without RLS, using (true) policies, public buckets, Firebase test-mode rules, identity taken from request bodies.
• Secrets: API keys, private keys, Supabase service_role keys in client code, secrets behind VITE_ / NEXT_PUBLIC_.
• Personal information: valid SA ID numbers and card numbers in code or data files, PI in logs, URLs and browser storage, ID numbers in plain columns.
• Consent and marketing: trackers with no consent mechanism, pre-ticked boxes, bundled consent, marketing without unsubscribe.
• Special PI and children: race, health, biometrics and other special fields; date of birth and school fields.
• Operators and AI: SDKs that make vendors operators and transfers, personal information in LLM prompts, automated decisions.
• Gaps: no privacy notice, no PAIA manual, no deletion or export, no retention job, no security.txt, no security CI.

Findings are leads, not verdicts. Every report redacts the secrets and personal information it detects.

How this maps to POPIA

Every finding and checklist item maps to one of POPIA's eight conditions (accountability, processing limitation, purpose specification, further processing, information quality, openness, security safeguards, data subject participation) or the rules on special personal information, children, direct marketing, automated decisions and cross-border transfers. Start with references/01-popia-legal-map.md.

Contributing

The law changes, enforcement evolves and builders find new ways to leak data. Help keep this current:

• Report a law change: open a law-change issue. A monthly automated watch of the Regulator's site opens these too.
• Add a scanner rule, component, pack or translation: see CONTRIBUTING.md.
• Attorneys and privacy professionals: the legal reviewer seat is open. Small, focused reviews, credited by name, and a review is not legal advice to users. Email popiakit@venusone.africa or see GOVERNANCE.md.

Licence

Code: MIT. Guidance, templates and other content: CC BY 4.0, credit "Venus One (Venus ARC (Pty) Ltd) and contributors". Details in LICENSING.md. Marks: TRADEMARKS.md.