krishna kapoor

Posted on Oct 18

Building GraphGuard: How a Graph Database Transformed Cybersecurity Investigation

#langchain #agents #falkordb #ai

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

Live Demo Video: https://youtu.be/UB7seRPO52Y

Source Code: https://github.com/KrishnaKapoor612/GraphGuard

Agents That Act on Connected Data

1. The Crisis in the SOC: Alert Fatigue and Disconnected Dots
Modern Security Operations Centers (SOCs) are drowning. A standard enterprise security stack generates thousands of alerts every single day: firewall drops, endpoint triggers, authentication anomalies, and DNS spikes.

The industry refers to this as Alert Fatigue. But the real issue isn't just volume—it's lack of context.

In traditional Security Information and Event Management (SIEM) tools, alerts arrive as isolated tabular records:

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

A tier-1 security analyst looking at this single entry might think: "It's an outbound connection on port 443. Could be a developer using a privacy proxy. Let's close it or put it on low priority."

What the analyst cannot see is that:

WORKSTATION-07 is operated by Marcus Chen (an engineering user flagged with an elevated risk level).
The exact same machine initiated an internal port scan across subnet 10.0.0.0/24 (Alert A-105) just 84 minutes earlier.
The destination IP 185.220.101.45 is linked to active Command-and-Control (C2) beaconing (Alert A-106).
Both alerts are part of an ongoing attack campaign (Incident INC-001: Data Exfiltration Campaign).
That incident directly threatens the organization's Payment Processing Service (SVC-001, Criticality: CRITICAL) and HR Portal (SVC-002, Criticality: HIGH).
In relational databases and document stores, discovering this requires 5 recursive SQL JOINs or complex log correlation queries that analysts simply don't have time to write under pressure.

Security data is not a flat spreadsheet. Security data is inherently a graph.

2. Our Hero: FalkorDB

To bridge this gap, an AI agent cannot just rely on vector similarity or prompt engineering—it needs a high-performance, graph-native backbone.

Enter FalkorDB.

FalkorDB serves as the authoritative, central store for GraphGuard's connected security knowledge. In our prototype, FalkorDB does not merely power a pretty frontend diagram; it is the computational brain that transforms disjointed security events into an interconnected graph.

Why FalkorDB is Essential to GraphGuard:

Graph Traversal: In an investigation, the AI agent makes 5 to 7 sequential queries to discover neighbors and trace attack paths. FalkorDB’s C-based, Redis-compatible graph architecture delivers sub-10ms query execution times, making the AI investigation feel instantaneous and responsive.

Expressive OpenCypher Engine: Complex multi-hop relationships that require paragraphs of code in relational or document databases are queried in a few lines of declarative Cypher.
Idempotency with MERGE: Security environments require repeatable demos and reliable pipelines. FalkorDB's full support for MERGE ensures that our synthetic seed scripts and recurring incident logs update relationships without creating duplicate entities.

Persistent Agent Memory Across Sessions: Unlike stateless LLM chatbots that lose context once a browser closes, GraphGuard persists completed investigations and derived evidence as first-class Investigation and Evidence nodes directly in FalkorDB. On future sessions, the agent queries past investigations using graph patterns.

3. The Graph Data Model

GraphGuard models cybersecurity operations as a property graph with 8 node labels and 10 relationship types:

Nodes:

User (id, name, department, role, risk_level)
Device (id, hostname, device_type, status, last_seen)
IPAddress (id, address, reputation, country)
Alert (id, title, severity, category, timestamp, status, description)
Incident (id, title, severity, status, created_at)
Service (id, name, criticality, owner_team)
Investigation (id, question, summary, created_at, outcome, severity_assessment)
Evidence (id, source_type, description, observed_at)

Graph Relationships:

(User)-[:USES]->(Device)
(Device)-[:CONTACTED]->(IPAddress)
(Device)-[:TRIGGERED]->(Alert)
(IPAddress)-[:ASSOCIATED_WITH]->(Alert)
(Alert)-[:PART_OF]->(Incident)
(Incident)-[:AFFECTS]->(Service)
(User)-[:INVOLVED_IN]->(Incident)
(Investigation)-[:EXAMINED]->(Alert)
(Investigation)-[:USED_EVIDENCE]->(Evidence)
(Evidence)-[:SUPPORTS]->(Incident)

The database comes pre-seeded with 27 base entities and 28 relationships representing 3 realistic scenarios:

Scenario A (Multi-Hop Compromise Chain): Alert A-104 linking Marcus Chen, WORKSTATION-07, Tor IP 185.220.101.45, Incident INC-001, and the Payment Processing Service.

Scenario B (Finance Credential Attack): Ryan Patel, LAPTOP-45, suspicious IP 192.0.2.99, failed logins Alert A-301, and Incident INC-002 affecting the Internal Finance System.
Scenario C (Benign Baseline): Alice Thompson, LAPTOP-22, Google DNS 8.8.8.8, and false-positive Alert A-201 (proving the AI doesn't flag everything as malicious).

4. Cypher in Action: The Core Queries

GraphGuard uses a centralized library of over 20 parameterized Cypher queries. Here are the three queries that drive the investigation engine:

1. Tracing the 4-Hop Attack Path (TRACE_INCIDENT_PATH)

When an analyst selects an alert, this single query traverses out 4 hops to map devices, contacted IPs, related alerts, incidents, and endangered 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. Discovering Hidden Pivot Connections (FIND_RELATED_ALERTS_VIA_IP)

Often, two alerts seem unrelated because they occurred at different times on different endpoints. By pivoting through the contacted IP address, FalkorDB uncovers the hidden link:

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. Persistent Cross-Session Memory (SAVE_INVESTIGATION)

When an investigation concludes, findings are committed to FalkorDB so any analyst can resume the investigation tomorrow:

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

5. Our Solution: GraphGuard

GraphGuard pairs FalkorDB with Google Gemini (gemini-3.8-flash) and LangChain to create an interactive investigation platform.


┌────────────────────────────────────────────────────────────────
│                   Streamlit Web Interface                       │
│     Overview  |  Investigate  |  Graph Explorer  |  History     │
└─────────────────────────────────┬──────────────────────────────
                                  │
┌─────────────────────────────────▼──────────────────────────────
│              Agent Service (Gemini + LangChain)                 │
│   7 Predefined Safe Tools — No Arbitrary Cypher Allowed         │
└─────────────────────────────────┬──────────────────────────────
                                  │
┌─────────────────────────────────▼──────────────────────────────
│          Graph & Investigation Service Layer                    │
│   Deterministic Orchestrator, Evidence Integrity, Memory        │
└─────────────────────────────────┬──────────────────────────────
                                  │
┌─────────────────────────────────▼──────────────────────────────
│                  FalkorDB Graph Database                        │
│   Nodes: Users, Devices, IPs, Alerts, Incidents, Services       │
└────────────────────────────────────────────────────────────────

Safety and Epistemic Integrity by Design
A major pitfall in cybersecurity AI agents is "_hallucination under fire"—_an LLM hallucinating IP addresses or making unwarranted claims. GraphGuard solves this with strict guardrails:

Predefined Safe Tool Registry: The LLM is never given direct Cypher execution privileges. It can only call 7 structured tools (get_alert_details, investigate_device, find_related_alerts, trace_incident_path, get_affected_services, save_investigation, and get_previous_investigation).

Confirmed Facts vs. Inferences:
The user interface explicitly separates:

✅ Confirmed Facts: Statements derived directly from verified Cypher query results (e.g., "WORKSTATION-07 connected to 185.220.101.45").

🔶 Inferences: Hypotheses generated by the LLM, strictly prefixed with INFERRED.

❓ Unknowns: Open questions the graph has not yet answered (e.g., "Whether credentials on WORKSTATION-07 were dumped from memory").

No Autonomous Destructive Actions: GraphGuard operates as a defensive decision-support system. All recommended actions include mandatory human-in-the-loop review.

Deterministic Fallback Engine: If the Gemini API key is missing or external APIs are unreachable, GraphGuard automatically falls back to its deterministic graph investigation orchestrator—ensuring SOC continuity without degradation.

6. The User Experience: 4 Intuitive Views

Built with Streamlit GraphGuard features four dedicated workspaces:

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

🔍 Investigation Workspace: The analyst selects an alert (e.g., A-104) or types an investigation question. Within seconds, GraphGuard queries FalkorDB, activates the Gemini agent, and outputs the full incident narrative, graph evidence path, related alerts, affected services, and defensive recommendations.

🕸️ Graph Explorer: An interactive 2D circular/force layout powered by Plotly. Analysts can visually inspect nodes (color-coded by type), click to view properties, and trace incoming and outgoing graph edges.

📁 Investigation History (Persistent Memory): Demonstrates cross-session memory by querying past Investigation nodes stored in FalkorDB. Analysts can ask follow-up questions like "What did we find when we investigated alert A-104 earlier?" and review previous findings.

7. The Walkthrough: Investigating Alert A-104

Here is the exact journey GraphGuard performs 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"). It discovers the alert originated from WORKSTATION-07.

Step 2: The agent calls investigate_device("D-001"). It reveals the device is used by senior developer Marcus Chen (high risk) and previously triggered A-105 (Internal Port Scan).

Step 3: The agent executes trace_incident_path("A-104"). It follows the connection to IP 185.220.101.45 (reputation: malicious, active Tor exit in the Netherlands).

Step 4: The agent pivots to find related alerts. It spots that 185.220.101.45 is also associated with Alert A-106: C2 Beacon Attempt.

Step 5: The path connects to Incident INC-001, which directly affects the Payment Processing Service.

Step 6: GraphGuard saves the full investigation record to FalkorDB for future reference.
In less than 3 seconds, a low-priority outbound connection alert was upgraded to a verified, multi-stage data exfiltration campaign threatening financial infrastructure.

8. Why GraphGuard Must Be Adopted

Solves the Disconnected Data Problem: Security attackers think in graphs; security defenders too often look at lists. GraphGuard levels the playing field by matching the attacker's connected mindset.

Reduces Mean Time to Detect and Respond (MTTD / MTTR): Instead of manually cross-referencing IP blacklists, endpoint logs, and active directory hierarchies across 4 browser tabs, an analyst gets the full connected context in a single query.

Eliminates AI Hallucinations in High-Stakes Environments: By anchoring the agent to real Cypher query outputs and enforcing fact-versus-inference separation, analysts can trust the recommendations.

Continuous Institutional Memory: Turnover in SOC teams often leads to lost investigation context. Persisting investigations in FalkorDB builds an organizational graph brain that gets smarter with every incident investigated.

9. Key Learnings & Engineering Reflections

Building GraphGuard reinforced several crucial software and architectural lessons:

Graph databases are natural context engines for LLMs: Giving an LLM raw documents or flat tables forces it to guess relationships. Giving an LLM a graph database allows it to traverse explicit, verified relationships with surgical precision.
Constrained agency builds robust software: Unrestricted AI agents running arbitrary Cypher are dangerous in production. Restricting the agent to deterministic, parameterized query tools produced 100% reliable results while preventing injection risks.
Idempotency is king: Designing the seed scripts with Cypher MERGE clauses saved hours of reset time and ensured our 14 automated unit tests ran reliably.

10. Verification & Code Quality

GraphGuard isn't a mock-up—it is an end-to-end, tested prototype:

14 Unit Tests Passing: Covering configuration security, Cypher query formatting, deterministic orchestration, and schema validation.

Automated Health Check (6/6 Passing): Verifying live cloud database connection, seed data completeness, multi-hop query resolution, and Gemini API availability.
Check Out the Project!