Security Guardrails¶

Defense-in-depth security for an AI system that translates natural language into database queries and LLM prompts.

Attack Surfaces¶

Graffold has two primary attack surfaces: 1. Prompt injection — manipulating the LLM via crafted user input 2. Cypher injection — manipulating the graph database via crafted query parameters

Plus a data protection concern: 3. PII leakage — personal data appearing in inputs or LLM outputs

Validation Pipeline¶

Every user query runs through validate_input() before reaching the agent:

User Input
  → Empty check
  → Length cap (10,000 characters)
  → Prompt injection detection (block if confidence ≥ 0.6)
  → Cypher injection detection (block on any match)
  → PII scan (log or block depending on domain)
  → Query reaches Agent
  → CypherBuilder (parameterized queries for all DB operations)

All blocked requests are logged to the audit logger with client IP, request ID, matched patterns, and rejection reason.

Prompt Injection Detection¶

SecurityGuardrails.detect_injection() uses 13 compiled regex patterns:

Category	Example Patterns	What It Catches
System message manipulation	"ignore previous instructions", "[system]", "\<system>"	Overriding the system prompt
Role switching	"act as if you are", "you are no longer an assistant"	Changing LLM behavior
Direct command injection	"execute the following command", "neo4j: MATCH..."	Running arbitrary code/queries
Jailbreak attempts	"DAN mode", "developer mode", "repeat after me"	Known jailbreak techniques
Output manipulation	"print your system prompt", "what are your instructions"	Exfiltrating system instructions

Heuristic Scoring¶

Each pattern match adds 0.3 to the confidence score (capped at 1.0)
Long inputs (>1000 chars) with matches get +0.2 boost (attackers often pad with noise)
Excessive special characters (>30% ratio) add +0.1 (potential obfuscation)
Requests at or above 0.6 confidence are blocked with HTTP 400

Cypher Injection Detection¶

The graph database equivalent of SQL injection. Since the system translates natural language into Cypher queries, attackers could try to sneak Cypher syntax into their question.

Detection Layer (`detect_cypher_injection`)¶

Pattern	Attack Type	Example
`UNION ALL MATCH`	UNION injection	Appending unauthorized queries
`; \w`	Statement chaining	Running multiple statements
`//` or `/* */`	Comment injection	Commenting out security filters
`' OR 1=1`	Tautology attack	Bypassing WHERE clauses

Prevention Layer (`CypherBuilder`)¶

Even if detection misses something, all Cypher queries are built safely:

Parameterized queries — all user values use $parameter placeholders, never string interpolation
Label validation — strict regex allowlist: ^[A-Za-z_][A-Za-z0-9_-]*$, max 64 chars
Internal label filtering — labels starting with _ are excluded from user-facing queries

This is the same principle as parameterized SQL queries preventing SQL injection — the database driver handles escaping, not application code.

PII Detection¶

Microsoft Presidio's AnalyzerEngine scans both inputs and outputs:

Detects: names, emails, phone numbers, addresses, and other PII entity types
Configurable entity types and confidence thresholds
Optional redaction via AnonymizerEngine (replaces PII with placeholders like <PERSON>)
Domain-aware behavior:
Biomedical context: logs PII but doesn't block (protein names trigger false positives)
Financial context: would block or redact (real PII in the data)

Audit Logging¶

All security-relevant events are logged with structured data:

Blocked requests: client IP, request ID, correlation ID, matched patterns, rejection reason, query preview
PII detections: entity count, entity types found
KG operations: user_id, kg_id, operation type (create/delete)
Cypher injection attempts: pattern count, matched patterns, query preview

Additional Architectural Controls¶

Provenance tracking — every extracted fact links to its source document
Cost tracking — token counting and cost estimation per request
Multi-tenant isolation — workspace separation, tier-based access control
Rate limiting — per-user Redis sliding window counters (not per-IP)