Building a Safe AI Agent with FalkorDB: BlastShield's Graph Evidence and Constrained Tools

Building an AI agent that responds to security alerts isn't hard because of the model itself—it's hard because you need its decisions to be traceable, verifiable, and trustworthy. BlastShield is a hackathon prototype submitted to Track 01 of Graph Hacks 2026. It uses the graph database FalkorDB to carry access relationships, constrains Gemini's behavior with limited tools, and verifies effects by re-querying after every action.

The Problem: The Multi-Hop Path Behind a Single Alert

An active session alert for developer_07, with a risk score of 35 out of 100, marked medium severity. That score alone doesn't say much. The truly dangerous context is several relationship layers away: developer_07 holds a session → the session can access a build node → the build node runs as a deployment role → the deployment role can assume a production role → the production role can read the customer database.

No single record tells the full story. Only when you traverse the chain of relationships together does the attack path emerge. The core question BlastShield answers is: from the alert to critical assets, what modeled paths exist? If you block one, what remains?

Let's be clear about boundaries: all of BlastShield's data is synthetic. It doesn't connect to real cloud accounts, identity providers, or production telemetry. Paths represent reachability within the model, not proof that a real environment has been compromised; conversely, the absence of a qualifying path in the graph doesn't prove a real environment is safe.

Architecture: The Graph Query Is the Evidence Itself

The stack includes a React + Vite frontend, a FastAPI backend, the FalkorDB graph database, and Gemini accessed through MCP tools. The project ships with four typical scenarios: identity access path (BH-1042, medium 35), excessive IAM permissions (BH-IAM-2001, high 65), exposed workload (BH-WORKLOAD-3001, high 75), and containment scenario (BH-CONTAINMENT-4001, high 60). These scores come from the demo rule set demo-rules-v1—transparent prototype values, not calibrated breach probabilities.

The graph model contains five entity types: Identity, Session, Workload, IAMRole, DataAsset. Edge direction matters: HAS_SESSION, CAN_ACCESS, RUNS_AS, CAN_ASSUME, CAN_READ string together a chain from identity to data. Edges also carry attributes like routing identifiers, containment and response status, permission evaluation, and sensitivity—attributes that let queries distinguish "active paths" from "already-blocked paths."

A Cypher query doesn't just return true or false—it returns the full path, nodes, directed edges, and edge properties. That's the evidence the dashboard can draw, and the material the agent can reason over. FalkorDB is central rather than decorative precisely because: path evidence comes from graph queries, response candidates derive from the returned relationships, and post-action verification depends on a new graph query.

FalkorDB is a graph database built on a Redis module, using sparse matrices (GraphBLAS) as its underlying storage engine, supporting the property graph model and the OpenCypher query language. Compared to traditional graph databases, it offers lower latency for multi-hop traversal and path queries, and can be deployed lightweight as a single instance—suitable for hackathon prototypes that need quick startup. Its edge properties (like routing identifiers and containment status) can be filtered directly in Cypher WHERE clauses, which is exactly the foundation for BlastShield distinguishing active paths from blocked ones.

Multi-Hop Reasoning: One More Hop Changes the Answer

Shallow queries miss the exposure surface behind role assumption. The project added a supplementary audit fixture to demonstrate this: auditor_02 to analytics-cache finds no qualifying path at depth 1, but the path appears at depth 4; to staging-report, depth 4 yields no path, but depth 5 does. That five-hop path depends on a CAN_ASSUME relationship in the middle of the chain—with the depth limit stuck at four, the report looks unreachable; loosen it to five and the path is found.

BlastShield uses bounded directed traversal, with an allowlist limiting which relationship types can be followed. Blocked session routes and relationships are excluded. The depth passed by the caller is validated as an integer between 1 and 6, mapping to six pre-built query templates; caller text is never concatenated into Cypher. The FalkorDB version used in development handled parameterization inconsistently within variable-length path bounds, so fixing six templates both avoids the risk of dynamically building query text and preserves controlled depth adjustment.

The Model Picks Tools, But Doesn't Write Queries

Handing the schema to the model and letting it generate Cypher is tempting, but the degrees of freedom are too large—results become hard to explain and audit. BlastShield's approach is to expose a set of vetted, fixed tools: investigate_alert(alert_id) returns standard graph investigation results, get_blast_radius(alert_id) returns workload, role, and asset entities derived from paths, find_shortest_access_path(source_id, target_id, max_hops) performs bounded traversal, and get_containment_route_statuses(alert_id) returns route statuses for the containment scenario.

Query templates are written by humans, tool inputs are validated before execution, and the tool trace records tool name, input, result, duration, and result count. Equally important is distinguishing "unknown entity" from "disconnected entity": a nonexistent entity should produce an unknown-source or unknown-target result, and two known entities with no qualifying connection should produce a no-path result. Invalid input and query failures are yet other states. None of these should quietly turn into a "the environment is safe" conclusion.

MCP (Model Context Protocol) is an open protocol proposed by Anthropic for establishing a standardized calling interface between LLMs and external tools/data sources. In this project, Gemini reasons through a fixed tool list exposed by an MCP client, where each tool corresponds to a preset Cypher template and parameter validation logic. MCP's "tool declaration" mechanism means the model only sees tool names and parameter schemas, and cannot directly access the database or concatenate query text—achieving "the model picks tools but doesn't write queries" at the architectural level.

Let the Agent Act, But Don't Give It the Keys

Investigation is read-only; response is what can create risk. BlastShield separates "proposing an action" from "executing an action" with three layers of boundaries: the decision service provides only read-only tools to fetch response candidates and select candidates; the FastAPI controller requires explicit confirmation and limits the number of actions per run; a separate action service holds the only mutating capability, executing a single allowlisted write against the synthetic graph.

Candidate lists derive from current graph evidence, not from Gemini's imagination. When Gemini proposes an action, the server re-derives current candidates and rejects selections that no longer exist; the action service validates once more before writing. Gemini has no access to mutating tools and doesn't write Cypher. Synthetic containment operations can mark an active session route in the model as blocked, but this only changes the demo graph state—it doesn't disable a real session or modify cloud resources.

This design deliberately puts the model on a short leash: it can choose among supported options, but server-side code decides whether the choice is valid and which write can execute.

"Allowlisted writes" means the action service accepts only pre-enumerated synthetic containment operations (e.g., marking a session route as blocked) and executes them only against the demo graph state. Any write not on the list, any call to a real cloud API, or any request exceeding the per-run action limit is rejected. This allowlist mechanism confines the model's choice space to a known-safe set of operations—the concrete implementation of the "don't give it the keys" principle.

After Every Action, Re-Ask the Graph

Issuing a command and verifying the effect are two different things. An agent shouldn't declare success just because it requested a change. In BH-CONTAINMENT-4001, the seed model has two independent paths. Blocking only the primary path shouldn't end the run—the alternate path still qualifies. So the controller queries the graph after every action and decides whether to continue based on the new results: investigate → find qualifying paths → select a supported action → apply synthetic change → re-query FalkorDB → verify remaining paths → continue or stop.

The expected seed sequence is: block the primary path, re-query to discover the alternate path, block the alternate path, then query again to confirm no qualifying paths remain. The run is complete only when the controller reaches a "no qualifying paths" result and all actions are verified. Reaching the action limit with paths still present is a "stopped run," not a "completed run." Unknown, invalid, or failed results never count as successful containment.

A regression test exposed a subtle failure in the response loop: if the action result doesn't include a post-action investigation, the controller might reuse the previous snapshot, and the next decision would be based on stale evidence. The fix: when the action response lacks an after object, the controller must fetch a standard investigation from FalkorDB; the test fixture was also corrected to ensure the serialized path list matches actual path data, and the regression test was strengthened to check that the second decision receives the alternate path rather than the primary path again. The lesson is simple: a responsive agent must reason from the latest evidence, not the last snapshot it happened to see.

Don't Trust the Model's Own Narration

Gemini can generate useful briefings, but fluent text isn't evidence. The briefing checker compares proposed summaries against standard investigation, flagging entity IDs not returned by the graph, risk scores that don't match computed values, relationship types that don't exist in the evidence, and unsupported claims of containment when qualifying paths remain. If validation fails or Gemini is unavailable, the UI uses a deterministic summary assembled from standard evidence, clearly labeled as a fallback state.

Tool-level unit tests cover re-query between actions, terminal no-path handling, unknown or invalid results, action limits, and validation failures. The latest backend test run reports 32 passed and 6 skipped. The 6 skipped are real-FalkorDB tests requiring explicit enablement—skipped tests are not verification. Real graph behavior, Gemini/MCP grounding across all scenarios, and the final browser flow still need independent end-to-end checks.

What Wasn't Done Matters Too

The project is candid about its boundaries: no native graph algorithms—the shortest path tool uses bounded Cypher traversal, not algo.SPpaths; no persistent graph memory—containment audit history lives in process memory and clears on API restart; synthetic data only—no connection to any cloud account, identity provider, or production telemetry; risk scores are demo values, not calibrated breach probabilities; Gemini is a necessary component for AI-assisted response decisions—without a configured key, structured graph investigation still works, but autonomous response runs must safely stop rather than fabricate actions.

Five Transferable Lessons

Model the problem before modeling the data—asking "what can reach critical data, and what remains after blocking one path" determines node and relationship design. Let the model choose, not concatenate queries—fixed, vetted parameterized tools are easier to verify and explain than generative Cypher. Separate decision from execution—the model chooses from server-derived candidates, and a separate component holds the only write capability. Verify with the same source of truth—re-query FalkorDB after changes, and let new results decide whether paths remain. Keep empty states honest—unknown entities, no paths, invalid input, and query errors are different results and should stay different.

BlastShield offers a practical path to making AI agent security decisions more auditable: put relationships in a graph, expose only vetted tools, derive actions from current evidence, and re-query the graph after every simulated change. The measure of an agent isn't how well it describes its work—it's what evidence it used and what verification it performed. The project code is open-sourced on GitHub; follow the README to start FalkorDB locally, install dependencies, seed scenarios, and run the frontend and backend.