feat(security): deceptive_ui_guard v2 — render diff, zone weighting, allowlists (#314)

[tusharjamunkar]

Resolves #314

Summary of Changes

Upgrades security/deceptive_ui_guard to version 0.2.0:

1. DOM Zone Classification & Severity Multipliers:

   • Subtree zones: checkout (1.5x), modal (1.25x), cmp (1.0x),
     avigation (0.75x), and general (1.0x).
   • Zone summary breakdown (zone_summary) included in execution output.

2. Curated Knowledge Base Allowlists:

   • �llowlist_sr_only.json: Standard accessibility classes (sr-only, �isually-hidden) and patterns.
   • �llowlist_cmp.json: Consent Management Platform selectors (OneTrust, Cookiebot, CookieYes, Klaro, Usercentrics) and benign cookie banner copy.
   • �llowlist_seo.json: Metadata tags, OpenGraph, JSON-LD, and microdata.
   • Suppresses channel mismatch false positives on benign accessibility and CMP elements unless imperative prompt overrides (IMPERATIVE_LEXICON) are detected.

3. Expanded Deceptive UI Taxonomy:

   • Pre-checked opt-in boxes (prechecked_opt_in, default recurring subscriptions, insurance, newsletter).
   • Drip pricing & undisclosed checkout fees (drip_pricing).
   • Fake urgency countdown timers (ake_urgency_timer).
   • Nag loops & confirm-shaming asymmetry (
     ag_loop).
   • Mobile/WebView surface profile heuristics (surface_profile=mobile).
   • Session fingerprint nag loop tracking (session_fingerprint, session_recommendation).

4. Optional Playwright Render Lane:

   • Headless Chromium computed-style diffing (
     ender_mode=auto|force) to expose elements rendered with zero dimensions or zero opacity via external stylesheets. Lazy-imported with zero dependency overhead when
     ender_mode=off (default).

5. 23 Golden HTML Test Corpus:

   • Added 23 categorized HTML fixtures under ests/fixtures/deceptive_ui/ across 8 categories (clean, cmp_ok, sr_only_ok, checkout_trap, �nti_agent, mislabeled_cta,
     ender_css_hidden, ake_urgency).
   • Parametrized integration test in ests/skills/security/test_deceptive_ui_guard.py.

6. Documentation & Validation:

   • Full 5-provider catalog snippets (Claude Tool Use, OpenAI Functions, DeepSeek, Ollama, Gemini) in docs/skills/deceptive_ui_guard.md.
   • Updated card.json, manifest.yaml, instructions.md, skill-trust-model.md, and card_ui_schema fixture.
   • All 580 pytest tests passing 100%.

Verification

• pytest skills/security/deceptive_ui_guard/test_skill.py -v (22 passed)
• pytest tests/skills/security/test_deceptive_ui_guard.py -v (26 passed)
• pytest tests/test_registry_docs.py -v (9 passed)
• pytest tests/test_card_ui_schema.py -v (17 passed)
• pytest (580 passed, 0 failures)
• python examples/deceptive_ui_guard_demo.py (verified all scenarios)

[rosspeili]

Thanks for the substantial v2 work @tusharjamunkar, zones, allowlists, taxonomy, corpus, and bundle tests look strong and match #314 well.

Before merge, please address:

1. Packaging, Add security_deceptive_ui_guard_render = ["playwright"] to pyproject.toml, sync extras (scripts/sync_extras.py --check), and document in docs/usage/install_extras.md. Docs already reference this extra but it does not exist yet.

2. CHANGELOG, Add [Unreleased] entry for security/deceptive_ui_guard v0.2.0.

3. Catalog snippets, Fix five-provider examples to use SkillLoader.to_claude_tool(bundle) / to_openai_tool / to_gemini_tool / to_ollama_prompt (same pattern as prompt_injection_firewall.md). bundle["to_*"]() keys are not on the loader bundle.

4. Render lane tests, Add maintainer or bundle tests with pytest.importorskip("playwright") for render_css_hidden/* fixtures and render_dom_divergence. Parametrized corpus currently has no branch for render_css_hidden (those cases pass with no assertions).

5. Demo, Update examples/deceptive_ui_guard_demo.py for v2 outputs/params.

6. Skill history, Remove or fix placeholder commit SHA, add real row after merge in a follow up commit or I can do it.

7. Rebase onto current main (5 commits behind).

Optional: dedupe or cross-link tests/fixtures/deceptive_ui/ vs examples/fixtures/deceptive_ui/.

Once these are address, happy to re-review and merge if CI is green. Well done <3

[tusharjamunkar]

@rosspeili Thanks for the review and kind words! All requested items have been addressed:

1. Packaging: Added security_deceptive_ui_guard_render = [playwright] to pyproject.toml, verified scripts/sync_extras.py --check passes cleanly, and documented in docs/usage/install_extras.md.
2. CHANGELOG: Added [Unreleased] entry for security/deceptive_ui_guard v0.2.0.
3. Catalog snippets: Aligned 5-provider snippets in docs/skills/deceptive_ui_guard.md to use static SkillLoader.to_claude_tool(bundle), to_openai_tool, to_gemini_tool, to_deepseek_tool, and to_ollama_prompt matching the standard pattern.
4. Render lane tests: Added render_css_hidden branch to the golden fixture corpus test, and added maintainer/bundle tests with pytest.importorskip(playwright) verifying render_dom_divergence detection and clean skipping when Playwright is not installed.
5. Demo: Updated examples/deceptive_ui_guard_demo.py showcasing v2 features (surface_profile, session_fingerprint, render_mode), and displaying zone_summary and session_recommendation in the output.
6. Skill history: Cleaned up the placeholder commit SHA from the catalog page history table.
7. Rebase: Rebased cleanly onto the latest upstream/main (including v0.5.3 updates).
8. Fixture cross-linking: Cross-linked examples/fixtures/deceptive_ui/ with the expanded 23-fixture test corpus in tests/fixtures/deceptive_ui/.

All GitHub Actions CI checks (Python 3.10, 3.11, 3.12, CodeQL, wheel-smoke) are passing green!

[rosspeili]

LGTM @tusharjamunkar, merged. <3