How I Used FalkorDB to Trace Software Security Risks in Warden

Ayush Khandelwal — Mon, 19 Oct 2026 02:29:55 +0000

You’re right—you want the article body, based on the actual README. Use the title separately, then paste everything under Post content into Dev.to.

Title: Warden: Graph-Based Security Analysis with FalkorDB

Warden helps software teams investigate security risks in a repository by connecting services, dependencies, vulnerabilities, ownership, and change history in a graph.

Instead of looking at vulnerability findings in isolation, engineers can explore how a package relates to a service, how services are modeled as communicating, and what sensitive data may be connected downstream. Warden uses those relationships to show evidence paths, help prioritize investigation, and rehearse possible dependency fixes before a person approves a change.

Project: Warden on GitHub

Live demo: warden-bice.vercel.app

Demo video: Watch the demo

The problem Warden explores

A vulnerability scanner can identify a package with a known advisory. But a finding by itself may leave important questions unanswered:

Which service uses the package?
Is that service connected to an internet-facing entry point?
What other services or data are connected to it?
Who owns the service?
What could change if we upgrade the package?

Warden brings repository structure and security information together so a team can explore these questions with graph queries and visible evidence.

A graph path is evidence of modeled reachability. It does not prove that vulnerable code is called or that an application is exploitable. Warden does not currently perform runtime traffic analysis or function-level vulnerability reachability.

Why FalkorDB?

The relationships between services, dependencies, vulnerabilities, and data are central to Warden’s workflow. FalkorDB provides the graph store Warden uses to represent and query those connections.

Warden loads normalized repository and security information into FalkorDB, then uses graph queries to:

Find vulnerability findings connected to modeled exposure.
Explore paths between services and other graph entities.
Calculate blast radius, rankings, and potential choke points.
Show evidence nodes, edges, sources, and query details.
Compare the modeled graph before and after a candidate dependency upgrade.

For fix planning, Warden rehearses proposed upgrades against a temporary copy of the graph. It reruns exposure analysis and safety checks, then presents the plan and gate result for review. A successful graph rehearsal demonstrates modeled graph impact; it does not guarantee that an upgrade preserves application behavior. The target project’s own tests and CI still need to be reviewed.

From a repository to a graph

When a project is built, Warden reads the selected repository and branch or tag into a project-specific checkout. It discovers services and topology from Kubernetes manifests, Docker Compose files, or supported code and dependency layouts.

It parses supported dependency files into package nodes and dependency relationships, looks up package advisories through OSV, and enriches findings with CISA Known Exploited Vulnerabilities (KEV) and FIRST EPSS data. Optional NVD lookups can provide CVSS information. Where available, Warden also reads Git history and adds curated owner, policy, incident, and data-sensitivity context for the shared sample project.

The ingest pipeline records provenance so users can see whether information came from a repository or feed, was inferred from configuration, or was curated for the sample project.

Supported dependency inputs include npm lockfiles, Python requirements and common Poetry/uv/Pipenv locks, go.mod, NuGet .csproj, Maven POM and Gradle files, Cargo, Ruby Bundler, and Composer lockfiles. The importer supports common repository layouts, not every possible project structure. Results depend on the files and configuration present.

What you can do in Warden

Explore the attack surface

The Home screen shows an attack-surface map and exposure summaries. Select a service to inspect its modeled connections to callers, dependencies, and sensitive data.

The Secure [service] interaction is a visual counterfactual. It highlights which currently modeled internet-to-sensitive-data routes would be cut if a service were secured. It does not modify the repository or graph.

Ask questions and inspect evidence

The Ask screen lets you ask graph-backed questions, such as:

“What should we fix first?”
“Show the path for CVE-2023-44487.”
“Is paymentservice reachable from the internet? Show the evidence.”
“What does this service read, and who owns it?”

The agent selects graph tools through MCP and drafts an answer using their results. The interface can show the tool trace, evidence path, source, Cypher query, and parameters. A deterministic verifier checks important claims against the tools’ results for that turn.

Model-backed answers require an OpenAI-compatible LLM endpoint. Graph tools and non-LLM views can still be used without an LLM key.

Compare and propose fixes

The plan builder can compare candidate dependency upgrade strategies. You can set a maximum number of upgrades, specify frozen services, and disallow major-version upgrades. Warden rehearses candidates on graph copies and displays changes, risk removed, new advisories, residual KEV, and gate results.

A blocked plan cannot be filed. A passing plan can be filed for approval. Filing creates a pending approval; it does not immediately make a GitHub change.

Review pull requests and approvals

The PR impact screen analyzes affected services, graph blast radius, owners, related history, policies, and suggested review feedback.

Plans and PR analyses can be sent to the Approvals screen for human review. Warden does not automatically merge pull requests. With GitHub configured, approved actions can operate on the selected repository target. Review the proposed changes and the pull request’s CI results before merging.

The Watcher also has a clearly labeled demo simulation that can commit a one-line topology change to its configured repository. Use a disposable fork for that demonstration.

Use tools, sync, watch, and evaluate

The Tools screen runs graph tools directly and displays summaries, rows, evidence paths, source details, queries, parameters, and duration. The graph tools are read-only; GitHub write actions use separate approval workflows.

Sync re-reads the configured repository and reports graph changes. The Watcher can poll for branch changes and create pending proposals when it detects new modeled exposure. The Evaluation screen runs designed scenarios against the tools and reports whether their expected outcomes match. These scenarios are a regression suite, not an independent benchmark across arbitrary repositories.

Warden also exposes its graph tool registry through an MCP server for use by Warden’s agent and compatible external MCP clients.

Architecture

Warden uses:

FastAPI for the backend API.
React, TypeScript, and Vite for the frontend.
FalkorDB for repository and security graph data.
PostgreSQL for application records such as accounts, sessions, teams, projects, and conversations.
Cytoscape.js for graph visualizations.
MCP to expose graph tools to the agent and compatible clients.

The backend contains the API, authentication, repository ingestion, graph access, security and topology tools, agent, evaluation, planning, approvals, sync, watcher, and MCP server. The frontend contains screens for Home, Ask, PR impact, Approvals, Tools, Sync, Evaluation, Settings, authentication, and the public landing page.

The basic request path is:

The browser sends an authenticated request to the FastAPI backend.
The API resolves the user’s current project.
The agent or screen calls project-scoped graph tools.
The tools query FalkorDB and return rows and, where available, evidence paths.
The interface displays results and supporting details.

PostgreSQL stores application data; FalkorDB stores repository and security relationships.

Run Warden locally

Requirements

You’ll need Docker Desktop or Docker Engine with Compose, Python 3.11 or newer, Node.js 20 or newer with npm, Git, and internet access for the first repository build and vulnerability-feed requests.

Quick start

Clone the repository, open a terminal in the project directory, and copy the environment template:

Windows PowerShell:

Copy-Item .env.example .env

macOS or Linux:

cp .env.example .env

Edit .env if needed. The backend reads this file from the repository root. Never commit your .env file or put backend secrets in frontend variables.

Then run the project launcher:

Windows:

.\start.ps1

macOS/Linux/Git Bash:

./start.sh

The launcher starts FalkorDB and PostgreSQL, prepares the Python environment, installs dependencies if needed, initializes the sample graph if it is empty, and starts the API and Vite development server. The first ingest can take several minutes.

The local addresses are:

UI: http://localhost:5173
API: http://localhost:8000
API docs: http://localhost:8000/docs
FalkorDB Browser: http://localhost:3000
FalkorDB graph port: localhost:6380
PostgreSQL: localhost:5433

Sign up at /signup. New users can access the shared sample project. You can create another project to build a graph from a GitHub repository and selected branch.

Manual development setup

If you prefer to run the services in separate terminals, start the graph and database from the repository root:

docker compose up -d falkordb postgres

Then install and initialize the backend:

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m warden.ingest.bootstrap
python -m uvicorn warden.api.app:app --host 127.0.0.1 --port 8000

On macOS/Linux, activate the environment with:

source .venv/bin/activate

In another terminal, start the frontend:

cd frontend
npm install
npm run dev

Vite proxies /api to http://127.0.0.1:8000. Set WARDEN_API if the backend is running on a different local port.

Environment variables

The .env.example file documents the available settings. The main ones are:

FalkorDB: FALKORDB_HOST, FALKORDB_PORT, and optional username, password, and TLS settings.
PostgreSQL: DATABASE_URL for user, team, project, session, and conversation data.
Repository ingestion: DEMO_REPO_URL, DEMO_REF, HISTORY_SINCE, and optional WARDEN_NVD.
LLM: LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL for model-backed Ask answers.
GitHub: GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, and GITHUB_BASE for repository access and approved actions.
Sessions and deployment: SESSION_SECRET, COOKIE_SAMESITE, COOKIE_SECURE, CORS_ORIGINS, WARDEN_URL, and VITE_API_URL.

The local defaults in .env.example are for development. Before exposing an API publicly, use a long random SESSION_SECRET, HTTPS, secure cookies, exact CORS origins, and appropriately scoped credentials. Keep GitHub tokens on the backend.

Without GitHub credentials, the sample graph and many read-only views remain available, but private repository access and GitHub actions are unavailable. Without an LLM key, graph-backed pages and tools remain usable, but Ask cannot generate model answers.

GitHub integration and human approval

A fine-grained GitHub token enables private repository access, GitHub history and pull request metadata, and approved repository actions. Grant only the permissions needed for the target repository, configure the project’s repository in Settings, and verify the target shown on the Approvals screen.

Warden does not automatically merge pull requests. Plans and PR analyses wait for human approval before GitHub writes. Use a fork or dedicated test repository when trying write actions.

Data, privacy, and limitations

The shared sample project uses Google’s Online Boutique repository.
Vulnerability data comes from OSV, CISA KEV, and FIRST EPSS; optional NVD lookups can be enabled. Feed data is cached locally.
Sample ownership, incidents, policies, and data sensitivity are curated demo context, not facts about an actual company.
Repository clones and feed caches are runtime data stored under backend/data/raw/ and ignored by Git.
LLM prompts include the user’s question and the tool data needed to answer it. Check your model provider’s data-handling terms before using private repository data.
Service calls can be inferred from manifests, environment variables, or Compose files. The interface labels inferred and curated evidence.
EPSS and KEV data are time-sensitive and should be refreshed for operational decisions.
A graph path is not proof of exploitability, and a fix-plan rehearsal is not a replacement for application tests.
Repository discovery supports common formats and layouts, not every possible repository.

Testing and production deployment

Run the backend tests from backend/:

python -m pytest -q tests

Build and type-check the frontend from frontend/:

npm run build

For production, deploy the API, FalkorDB, and Caddy on a server with HTTPS, then deploy the frontend/ directory to Vercel as a static site. Set VITE_API_URL to the API’s HTTPS origin in Vercel. Configure the backend’s WARDEN_URL and CORS_ORIGINS to match the frontend origin. Store secrets in the hosting provider, not in committed files. Redeploy the frontend after changing VITE_API_URL.

Credits

Warden is built with FastAPI, React, Vite, TypeScript, Cytoscape.js, FalkorDB, PostgreSQL, and MCP. It uses public vulnerability information from OSV, CISA KEV, and FIRST EPSS. The sample service repository is Google Online demo.

DEV Community: Ayush Khandelwal