Skip to content

README.md

Latest commit

 

History

History
286 lines (207 loc) · 9.4 KB

README.md

File metadata and controls

286 lines (207 loc) · 9.4 KB

agent-shield

Compliance middleware for AI agents. PII redaction, audit logging, consent management, and DPIA generation — in 3 lines of code.

from agent_shield import Shield

shield = Shield()
result = shield.scan("Contact me at john@example.com or 08034567890")

print(result.pii_found)   # {'EMAIL': 1, 'PHONE_NG': 1}
print(result.redacted)     # "Contact me at [EMAIL_REDACTED] or [PHONE_REDACTED]"

Every AI agent processes personal data. Almost none of them handle it compliantly. agent-shield fixes that.

Why this exists

AI agents are being deployed everywhere — customer support, document processing, sales, internal tools. They all process personal data. Under GDPR, the EU AI Act, and Nigeria's NDPA, that processing has legal requirements:

  • You need to know what personal data your agent handles
  • You need audit trails of every LLM call
  • You need consent management per user
  • You need a Data Protection Impact Assessment
  • You need to document where data flows (especially cross-border)

Nobody builds these features. LangChain doesn't. CrewAI doesn't. The Vercel AI SDK doesn't. Your custom agent definitely doesn't.

agent-shield adds all of it as middleware. No framework lock-in. Works with any LLM provider.

Features

Feature What it does
PII Detection Regex-based scanner for emails, phones (Nigerian, UK, international), BVN, NIN, NI numbers, credit cards, DOB, IP addresses, IBAN, SSN
PII Redaction Replace detected PII with typed labels ([EMAIL_REDACTED], [PHONE_REDACTED]) before sending to LLM providers
Audit Logging Tamper-evident log of every LLM call — input, output, PII detected, tokens, user, purpose. Hash-chain integrity verification
Consent Management Per-user consent tracking — grant, withdraw, check, export. Full history for data subject requests
DPIA Generator Auto-generates a Data Protection Impact Assessment skeleton from your audit logs — risks, data flows, mitigations
Data Flow Mapper Markdown table + Mermaid diagram showing where personal data flows to which providers in which countries
User Reports One-call export of all data for a specific user — for GDPR/NDPA data subject access requests

Install

pip install agent-shield

Zero dependencies for core features. Optional provider integrations:

pip install agent-shield[openai]      # OpenAI wrapper
pip install agent-shield[anthropic]   # Anthropic wrapper

Quick start

Scan text for PII

from agent_shield import Shield

shield = Shield()

result = shield.scan("My email is ade@company.ng and BVN: 12345678901")
print(result.pii_found)    # {'EMAIL': 1, 'BVN': 1}
print(result.redacted)     # "My email is [EMAIL_REDACTED] and [BVN_REDACTED]"
print(result.has_pii)      # True

Wrap an OpenAI call

from openai import OpenAI
from agent_shield import Shield

client = OpenAI()
shield = Shield(redact_by_default=True)

result = shield.call_openai(
    client=client,
    messages=[{"role": "user", "content": "My email is test@example.com, help me"}],
    model="gpt-4",
    purpose="customer_support",
    user_id="user_123",
)

# PII was redacted before reaching OpenAI
# The call is logged in the audit trail
# You can generate a DPIA from the logs

Wrap an Anthropic call

from anthropic import Anthropic
from agent_shield import Shield

client = Anthropic()
shield = Shield(redact_by_default=True)

result = shield.call_anthropic(
    client=client,
    messages=[{"role": "user", "content": "Process my order, phone 08012345678"}],
    purpose="order_processing",
    user_id="customer_456",
)

Wrap any LLM (generic)

from agent_shield import Shield

shield = Shield()

def my_llm(text):
    # Your custom LLM call
    return f"Response to: {text}"

result = shield.call(
    my_llm,
    input_text="My NI number is AB123456C",
    provider="custom_llm",
    purpose="data_analysis",
    user_id="analyst_1",
)

Manage consent

shield = Shield()

# Record consent
shield.consent.grant("user_123", "customer_support", method="explicit")
shield.consent.grant("user_123", "marketing", method="opt_in")

# Check before processing
if shield.consent.check("user_123", "customer_support"):
    # Proceed
    ...

# User withdraws
shield.consent.withdraw("user_123", "marketing")

# Export for data subject request
history = shield.consent.export("user_123")

Generate a DPIA

shield = Shield()

# ... after running your agent with shield wrapping calls ...

dpia = shield.generate_dpia(
    system_name="Customer Support Agent",
    controller_name="Your Company Ltd",
    dpo_contact="dpo@yourcompany.com",
)

with open("DPIA.md", "w") as f:
    f.write(dpia)

The generated DPIA includes:

  • Processing description (auto-detected from audit logs)
  • PII types processed
  • External providers and countries (cross-border transfer documentation)
  • Risk assessment
  • Mitigation checklist
  • Sign-off section

Generate a data flow map

shield = Shield()

# Markdown table
print(shield.generate_dataflow())

# Mermaid diagram (paste into any renderer)
print(shield.generate_dataflow_diagram("My Agent"))

Output:

graph LR
    APP[My Agent]
    P0[openai<br/>United States]
    APP -->|EMAIL, PHONE_NG| P0
    P1[anthropic<br/>United States]
    APP -->|data| P1

Verify audit trail integrity

shield = Shield()

valid, count = shield.verify_audit()
print(f"Chain: {'intact' if valid else 'TAMPERED'} ({count} entries)")

Handle a data subject access request

shield = Shield()

# One call gets everything for a user
report = shield.user_report("user_123")

print(report["audit_entries"])    # All LLM calls involving this user
print(report["consent_history"])  # Full consent timeline
print(report["active_consents"]) # Current consent state

PII types detected

Type Pattern Example
EMAIL Standard email format john@example.com
PHONE_NG Nigerian mobile numbers 08034567890
PHONE_UK UK phone numbers 01234 567890
PHONE_INTL International format +234 803 456 7890
BVN Nigerian Bank Verification Number BVN: 12345678901
NIN_NG Nigerian National ID (11 digits) 12345678901
NI_NUMBER_UK UK National Insurance AB123456C
CREDIT_CARD Card numbers 4111-1111-1111-1111
DATE_OF_BIRTH DOB with context DOB: 15/03/1990
IP_ADDRESS IPv4 addresses 192.168.1.100
IBAN International bank account GB29NWBK60161331926819
SSN_US US Social Security Number 123-45-6789

Regulatory context

GDPR (EU/UK) — Articles 5, 6, 13-22, 25, 30, 35. If your agent processes EU personal data, you need lawful basis, transparency, DPIAs for high-risk processing, and records of processing activities. agent-shield generates the evidence.

EU AI Act — High-risk AI obligations apply from August 2, 2026. Transparency, documentation, and human oversight requirements. The audit trail and DPIA generator help satisfy documentation obligations.

NDPA (Nigeria) — Nigeria Data Protection Act 2023. DPO requirements, annual CAR filing, cross-border transfer safeguards. agent-shield's data flow mapper documents every international transfer.

For detailed compliance guidance:

Architecture

agent_shield/
    __init__.py     # Shield class — main interface
    pii.py          # PII detection & redaction (zero dependencies)
    audit.py        # Tamper-evident audit logger (hash-chain)
    consent.py      # Per-user consent state management
    wrapper.py      # LLM call wrappers (OpenAI, Anthropic, generic)
    dpia.py         # DPIA skeleton generator
    dataflow.py     # Data flow mapper (Markdown + Mermaid)

Zero dependencies for core features. Pure Python. No ML models, no spaCy, no torch. Installs in 2 seconds.

Limitations

  • PII detection is regex-based, not ML-based. It catches structured PII (emails, phones, IDs) but may miss unstructured PII (names in running text, addresses without clear formatting). For production use, consider layering ML-based NER on top.
  • The DPIA generator produces a skeleton (~60% of a DPIA), not a finished assessment. It needs human review, legal assessment, and sign-off. agent-shield doesn't replace a qualified DPO — it gives them a head start.
  • Audit log integrity depends on file system security. For production, consider storing logs in an append-only database or write-once storage.

Contributing

Issues and PRs welcome. If you're adding PII patterns for a new jurisdiction, include test cases.

License

MIT — use it however you want.

Credits

Built by Janus Compliance — we build compliant AI systems and provide data protection advisory services across the UK, Ireland, and Nigeria.

Need professional compliance help? Get in touch.