Skip to content

feat(governance): Governance: PII Scan node with deterministic tealtiger guardrails - #549

Open
CodeBhavyaG wants to merge 1 commit into
Ironclad:mainfrom
CodeBhavyaG:feat/governance-node
Open

CodeBhavyaG wants to merge 1 commit into
Ironclad:mainfrom
CodeBhavyaG:feat/governance-node

Conversation

@CodeBhavyaG

Copy link
Copy Markdown

Closes #547

Summary

Adds a Governance: PII Scan plugin node that enforces deterministic
guardrails on graph execution, backed by the tealtiger package
(>=1.5.0, Apache-2.0) — no LLM calls, no network, sub-2.5ms per evaluation.

Node features

Config Options
Mode observe (fail-open, report only) / monitor / enforce
PII categories SSN, Email, Phone, CreditCard (tealtiger) + APIKey (local regex)
PII action detect (report only) / redact (typed tokens: [REDACTED_SSN]) / block

Outputs: output (transformed text), decision
({action: ALLOW|REDACT|DENY, findings[], risk_score, mode, detect_types, correlation_id, latency_ms}), blocked (boolean).

The decision object doubles as a per-execution audit record, per the
governance design in the issue. Observe mode never transforms or blocks;
tealtiger errors fail open and surface as a tealtiger-error finding
instead of crashing the graph.

Bugs hit along the way (and fixes)

  1. TealGuard minimal config is a silent no-op: {pii: true, ...} flags
    don't exist on TealGuardConfig; a fresh TealGuard registers nothing.
    Fixed by registering PIIDetectionGuardrail explicitly.
  2. TealGuard aggregation drops metadata: for pass-style actions
    (redact/mask) TealGuard.check() collapses the guardrail result to
    ALLOW / risk 0 and discards detections[]/redactedText. Fixed by
    wiring GuardrailEngine + PIIDetectionGuardrail directly.
  3. Browser build: tealtiger's ESM bundle statically imports node
    builtins (fs, crypto) and unused provider SDKs whose trees are
    Node-only (aws-sdk, google genai, cohere). Fixed in the app via the
    import export condition, browser shims for fs/crypto (crypto-js
    based), and stubs for the unused SDKs. Note for tealtiger maintainers:
    an unknown detectTypes key failing silently is a footgun worth
    throwing on.

Files changed

  • packages/core/src/plugins/governance/ — new plugin + GovernanceNode
  • packages/core/src/plugins.ts, packages/app/src/plugins.ts — plugin registration
  • packages/core/package.jsontealtiger@^1.5.0 dependency
  • packages/app/vite.config.ts — ESM condition + browser aliases
  • packages/app/src/shims/nodeBuiltins.ts — fs/crypto shims + provider stubs
  • packages/app/package.jsoncrypto-js (shim)
  • yarn.lock — lockfile

How to test

1. Unit tests

cd packages/core && yarn test

2. In the Rivet app

yarn dev   # vite dev app (the installed desktop app won't include this)
  1. Plugins tab → add the Governance plugin
  2. Build: Text → Governance: PII Scan → Output
  3. On the node: Categories SSN, Email, CreditCard, Action Redact, Mode Enforce
  4. Text: My SSN is 123-45-6789, email john@acme.com
  5. Run → Output shows redacted text ([REDACTED_SSN]); Decision port shows {action: "REDACT", risk_score: ..., findings: [...]}
  6. Switch Action to Block → output empty, blocked: true, action: "DENY"
  7. Switch Mode to Observe → original text passes through, decision still reports findings

3. Latency

Each evaluation is pure regex: 0.2–2.5ms (measured), deterministic across runs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Governance node — deterministic PII scanning, cost budgets, and output authorization for AI graphs

1 participant