Graph Database + AI Agent: How GraphGuard Revolutionizes Cybersecurity Investigations

"Every alert has a story. Follow the graph to find it."

Security Operations Centers (SOCs) have long been drowning in a flood of alerts, while real threats often hide among seemingly isolated alerts. The GraphGuard project combines the graph database FalkorDB with an AI agent (built on Gemini and LangChain) to transform fragmented security events into traceable attack graphs, cutting investigation time from hours to seconds. This article takes a deep dive into its architecture, data model, and engineering practices.

The Essence of Alert Fatigue: Lack of Contextual Correlation

Modern enterprise security stacks generate thousands of alerts every day: firewall blocks, endpoint triggers, authentication anomalies, DNS spikes... Security teams face not just a volume problem, but a lack of context. In traditional SIEM tools, alerts are presented as isolated table records:

Alert ID: A-104
Title: Suspicious Outbound Connection to Known Tor Exit Node
Severity: CRITICAL | Device: WORKSTATION-07

A front-line analyst seeing this record might think "it's just a developer using a privacy proxy" and downgrade or close it. But they cannot immediately see that: the device is used by high-risk user Marcus Chen; the same device initiated an internal port scan 84 minutes earlier (A-105); the destination IP is associated with a C2 beacon alert (A-106); these alerts all belong to the same data exfiltration incident (INC-001) and directly threaten the payment processing service (SVC-001, critical).

In a relational database, reconstructing this chain requires 5 levels of recursive JOINs or complex log correlation queries—an analyst under pressure simply has no time to write them. Security data is fundamentally a graph, not a flat table.

SIEM (Security Information and Event Management) is the core infrastructure of a SOC, responsible for collecting, normalizing, correlating, and storing logs and alerts from firewalls, EDR, identity systems, and other security devices. Traditional SIEM's strengths lie in centralized log search and rule-based alert generation, but its data model is typically centered on flat event tables or key-value indexes—good at "filtering and matching," not at "multi-hop relationship traversal." When an attack chain spans multiple entities such as devices, users, IPs, and services, SIEM requires analysts to manually stitch them together or write complex correlation rules—exactly one of the root causes of alert fatigue. Graph databases are not meant to replace SIEM but to supplement it as a relationship layer, reorganizing discrete events produced by SIEM into a traversable attack graph.

FalkorDB: Graph-Native Power for AI Agents

GraphGuard chose FalkorDB as its core storage and computation engine. It is not just the data source for front-end visualization, but the "computational brain" that transforms discrete security events into an interconnected graph. FalkorDB's key features underpin the real-time and reliable nature of investigations:

• Graph traversal performance: During investigations, the AI agent needs to execute 5-7 sequential queries to discover neighbors and attack paths. FalkorDB's C-based, Redis-compatible architecture provides sub-10ms query latency, making the investigation experience nearly instantaneous.
• OpenCypher expressiveness: Multi-hop relationships require large amounts of code in relational databases but only a few lines of declarative queries in Cypher.
• MERGE idempotency: Security environments demand repeatable demos and reliable data pipelines. FalkorDB's full support for MERGE ensures that seed scripts and event log updates do not produce duplicate entities.
• Persistent agent memory: Unlike stateless LLM chatbots, GraphGuard persists completed investigations and evidence as first-class nodes (Investigation, Evidence) in FalkorDB. Future sessions can directly query historical investigation patterns, enabling cross-session memory.

OpenCypher is a declarative query language for property graphs, using ASCII-art style pattern matching syntax such as (a:Alert)-[:TRIGGERED]->(d:Device) to intuitively express "a device triggered an alert." Unlike SQL JOINs, Cypher's variable-length path matching (e.g., [:CONTACTED*1..4]) can express traversals of arbitrary depth in a single statement, and query length does not balloon with the number of hops. FalkorDB implements a subset of OpenCypher and optimizes for sparse matrix storage. For security investigations, this means "starting from one alert, expand four hops outward to find the affected critical service" can be written as a readable, parameterizable, and auditable query rather than hundreds of lines of recursive code—this is also the linguistic foundation that enables a constrained AI agent to safely invoke graph queries.

Graph Data Model: 8 Node Types and 10 Relationship Types

GraphGuard models security operations as a property graph with 8 node types: User, Device, IPAddress, Alert, Incident, Service, Investigation, Evidence; and 10 relationship types: USES, CONTACTED, TRIGGERED, ASSOCIATED_WITH, PART_OF, AFFECTS, INVOLVED_IN, EXAMINED, USED_EVIDENCE, SUPPORTS.

The database is preloaded with 27 base entities and 28 relationships, covering three real-world scenarios:

• Scenario A (multi-hop intrusion chain): Alert A-104 links Marcus Chen, WORKSTATION-07, Tor IP 185.220.101.45, incident INC-001, and the payment processing service.
• Scenario B (financial credential attack): Ryan Patel, LAPTOP-45, suspicious IP 192.0.2.99, failed login alert A-301, and incident INC-002 affecting the internal financial system.
• Scenario C (benign baseline): Alice Thompson, LAPTOP-22, Google DNS 8.8.8.8, and false-positive alert A-201, proving the AI will not flag everything as malicious.

This design allows the agent to traverse precisely over explicit relationships rather than relying on vector similarity guesses.

Cypher in Action: The Core Queries That Drive Investigations

GraphGuard includes a library of 20+ parameterized Cypher queries, three of which form the pillars of the investigation engine:

1. Tracing a four-hop attack path (TRACE_INCIDENT_PATH)
When an analyst selects an alert, a single query traverses four hops outward, mapping the device, contacted IPs, related alerts, incidents, and affected critical services:

MATCH (a:Alert {id: $alert_id})
OPTIONAL MATCH path1 = (d:Device)-[:TRIGGERED]->(a)
OPTIONAL MATCH path2 = (u:User)-[:USES]->(d)
OPTIONAL MATCH path3 = (d)-[:CONTACTED]->(ip:IPAddress)
OPTIONAL MATCH path4 = (ip)-[:ASSOCIATED_WITH]->(related_a:Alert)
OPTIONAL MATCH path5 = (a)-[:PART_OF]->(inc:Incident)
OPTIONAL MATCH path6 = (inc)-[:AFFECTS]->(svc:Service)
OPTIONAL MATCH path7 = (u)-[:INVOLVED_IN]->(inc)
RETURN a.id AS start_alert_id, a.title AS start_alert_title,
       d.hostname AS hostname, u.name AS user_name, u.risk_level AS user_risk_level,
       ip.address AS ip_address, ip.reputation AS ip_reputation,
       related_a.id AS related_alert_id, related_a.title AS related_alert_title,
       inc.id AS incident_id, inc.title AS incident_title,
       svc.name AS service_name, svc.criticality AS service_criticality

2. Finding hidden hub connections (FIND_RELATED_ALERTS_VIA_IP)
Two alerts may appear unrelated due to different times or endpoints. Through a hub query via the contacted IP address, FalkorDB can reveal hidden correlations:

MATCH (a:Alert {id: $alert_id})<-[:TRIGGERED]-(d:Device)-[:CONTACTED]->(ip:IPAddress)-[:ASSOCIATED_WITH]->(other:Alert)
WHERE other.id <> $alert_id
RETURN other.id AS alert_id, other.title AS title, other.severity AS severity,
       other.category AS category, other.timestamp AS timestamp,
       ip.address AS via_ip, ip.reputation AS ip_reputation
LIMIT $limit

3. Persisting cross-session memory (SAVE_INVESTIGATION)
After an investigation concludes, findings are committed to FalkorDB, and any analyst can resume the investigation the next day:

MERGE (inv:Investigation {id: $inv_id})
SET inv.question = $question,
    inv.summary = $summary,
    inv.created_at = $created_at,
    inv.outcome = $outcome,
    inv.recommended_steps = $recommended_steps,
    inv.severity_assessment = $severity_assessment
RETURN inv.id

Solution Architecture: Security and Cognitive Integrity

GraphGuard combines FalkorDB with Google Gemini (gemini-3.8-flash) and LangChain to build an interactive investigation platform. The system is divided into four layers: Streamlit web interface → Agent service (Gemini + LangChain) → Graph and investigation service layer (deterministic orchestration, evidence integrity, memory) → FalkorDB graph database.

A major pitfall for cybersecurity AI agents is "hallucination under pressure"—LLMs fabricating IP addresses or making unfounded assertions. GraphGuard solves this through strict guardrails:

• Predefined secure tool registry: The LLM is never granted permission to execute Cypher directly; it can only invoke 7 structured tools (get_alert_details, investigate_device, find_related_alerts, trace_incident_path, get_affected_services, save_investigation, get_previous_investigation).
• Clear separation of facts and inferences: The interface strictly distinguishes "confirmed facts" (directly from verified Cypher query results, e.g., "WORKSTATION-07 connected to 185.220.101.45"), "inferences" (LLM-generated hypotheses, which must be prefixed with INFERRED), and "unknowns" (open questions the graph has not yet answered).
• No autonomous destructive actions: GraphGuard operates as a defensive decision-support system; all recommended actions require human review.
• Deterministic fallback engine: If the Gemini API key is missing or external APIs are unreachable, the system automatically falls back to a deterministic graph investigation orchestrator, ensuring SOC continuity is unaffected.

LLM hallucination refers to large language models generating plausible but factually incorrect content when lacking grounding, which in security scenarios manifests as fabricated IPs, alert IDs, or causal relationships. Common industry mitigation approaches include retrieval-augmented generation (RAG), function calling, and structured output constraints. GraphGuard adopts a "tool constraint + evidence anchoring" approach: the model does not touch raw Cypher and can only choose from a fixed toolset, with each tool returning real query results from the database. This contrasts with open agents that "let the model freely generate queries and then execute them"—the latter offers more flexibility but introduces risks of query injection, runaway performance, and irreproducibility. In a SOC environment that requires auditability and accountability, sacrificing some flexibility for determinism is a reasonable engineering trade-off.

User Experience: Four Intuitive Views

Built on Streamlit, GraphGuard provides four dedicated workspaces:

📊 Overview Dashboard: Real-time FalkorDB metrics (node and relationship counts, active incidents, alert severities, system health status).

🔍 Investigation Workspace: Analysts select an alert (e.g., A-104) or enter an investigation question. Within seconds, GraphGuard queries FalkorDB, activates the Gemini agent, and outputs a complete incident narrative, graph evidence paths, related alerts, affected services, and defensive recommendations.

🕸️ Graph Explorer: An interactive 2D layout built with Plotly; analysts can visually inspect nodes (color-coded by type), click to view properties, and trace incoming and outgoing edges.

📁 Investigation History (persistent memory): Displays cross-session memory by querying historical Investigation nodes stored in FalkorDB. Analysts can ask "What did we find when we investigated A-104 before?" and review prior findings.

Hands-On Walkthrough: Investigating Alert A-104

Below is the exact flow of GraphGuard during a live investigation:

Alert A-104 (Outbound Tor)
        │ [TRIGGERED]
        ▼
  WORKSTATION-07 ────────[USES]────────► Marcus Chen (HIGH Risk)
        │ [CONTACTED]
        ▼
  185.220.101.45 (Tor Exit) ────[ASSOCIATED_WITH]────► Alert A-106 (C2 Beacon)
        │ [PART_OF]
        ▼
  Incident INC-001 (Data Exfiltration)
        │ [AFFECTS]
        ├────────► Payment Processing Service (CRITICAL)
        └────────► HR Employee Portal (HIGH)

Step 1: The agent executes get_alert_details("A-104") and finds the alert originated from WORKSTATION-07.
Step 2: It calls investigate_device("D-001"), revealing the device is used by senior developer Marcus Chen (high risk) and had previously triggered A-105 (internal port scan).
Step 3: It executes trace_incident_path("A-104"), tracing to IP 185.220.101.45 (reputation: malicious, active Tor exit node in the Netherlands).
Step 4: A hub lookup finds related alerts, revealing the same IP is also associated with alert A-106: a C2 beacon attempt.
Step 5: The path connects to incident INC-001, directly affecting the payment processing service.
Step 6: GraphGuard saves the complete investigation record to FalkorDB for future reference.

In under 3 seconds, a low-priority outbound connection alert escalated into a verified multi-stage data exfiltration campaign threatening financial infrastructure.

Why Adopt GraphGuard

• Solves the data silo problem: Attackers think in graphs, while defenders often look at lists. GraphGuard levels the playing field by matching attackers' associative thinking.
• Reduces MTTD/MTTR: Analysts no longer need to manually cross-reference IP blocklists, endpoint logs, and Active Directory hierarchies across 4 browser tabs—a single query yields complete correlated context.
• Eliminates AI hallucinations in high-risk environments: By anchoring the agent to real Cypher query outputs and enforcing separation of facts and inferences, analysts can trust the recommendations.
• Continuous institutional memory: SOC team turnover often leads to loss of investigation context. Persisting investigations in FalkorDB builds an organizational graph brain that gets smarter with every incident investigation.

Key Engineering Lessons

• Graph databases are the natural context engine for LLMs: Give an LLM raw documents or flat tables, and it can only guess relationships; give an LLM a graph database, and it can traverse explicitly verified relationships with surgical precision.
• Constrained agents build robust software: In production, an unrestricted AI agent running arbitrary Cypher is dangerous. Restricting the agent to deterministic, parameterized query tools yields 100% reliable results and prevents injection risks.
• Idempotency is king: Designing seed scripts with the Cypher MERGE clause saved hours of reset time and ensures 14 automated unit tests run reliably.

MERGE idempotency is a critical detail in graph database data pipeline design. MERGE's semantics are "reuse if matched, otherwise create," but under concurrent writes or property updates, improper use can still produce duplicate nodes or unintended overwrites. GraphGuard's practice shows that designing seed scripts and event log updates uniformly as MERGE operations keyed on unique IDs makes repeated execution leave the final state unchanged, thereby supporting demo resets, test reruns, and incremental data sync. This property is especially important for AI agents: an agent may resubmit the same investigation record due to retries or multi-turn conversations, and idempotent writes ensure the memory layer is not polluted by duplicate calls, while also making automated unit test results reproducible.

Verification and Code Quality

GraphGuard is not a prototype demo but a product tested end to end: 14 unit tests passing, covering configuration security, Cypher query formatting, deterministic orchestration, and schema validation; automated health checks passing 6/6, verifying live cloud database connectivity, seed data integrity, multi-hop query parsing, and Gemini API availability.

Project Resources

• Demo video: https://youtu.be/UB7seRPO52Y
• Source code: https://github.com/KrishnaKapoor612/GraphGuard
• Development context: Graph Hacks 2026 Track 1 — Agents That Act on Connected Data

GraphGuard demonstrates the potential of combining graph databases with AI agents: not replacing analysts with LLMs, but providing them with verifiable contextual correlation, turning security investigations from "digging through alerts" into "following the graph."

One-line Summary

GraphGuard uses the FalkorDB graph database and a constrained Gemini agent to string isolated alerts into traceable attack graphs.

Paragraph Summary

Targeting SOC alert fatigue, GraphGuard proposes a security investigation solution built around the graph database FalkorDB with an AI agent powered by Gemini and LangChain. The article argues that security data is fundamentally a graph rather than flat tables, and that traditional SIEM's five-level recursive JOINs are impractical under pressure. The system models 8 node types and 10 relationship types, includes 20+ parameterized Cypher queries, with four-hop path tracing, IP hub correlation, and investigation persistence forming the pillars of the investigation engine. To prevent LLM hallucinations, GraphGuard restricts the agent to 7 predefined tools, enforces separation of confirmed facts, inferences, and unknowns, and provides a deterministic fallback engine. In practice, a low-priority Tor outbound alert was escalated within 3 seconds into a multi-stage data exfiltration event threatening payment systems, with results persisted to form cross-session institutional memory.