ShieldGraph 🛡️

Software Supply Chain & Vulnerability Blast Radius Graph Application

Powered by CognoDB Cloud (openCypher / Bolt), FastAPI (Python), and React.

---

1. 📖 Use Case & Overview

Modern software architectures rely on dozens of microservices, each pulling in direct third-party dependencies which in turn pull in deep transitive packages. When a critical zero-day vulnerability (such as Log4Shell, Spring4Shell, or the XZ Utils Backdoor) is disclosed, security and platform engineering teams face a critical challenge:

"Which of our customer-facing microservices and production environments are secretly exposed through a 3rd or 4th-degree transitive library dependency?"

ShieldGraph models microservices, package dependencies, environments, and CVEs as an interconnected property graph. It allows engineers to:

1. Trace arbitrary-depth dependency chains (multi-hop traversal).
2. Calculate the exact Blast Radius of any CVE across production infrastructure.
3. Compute the shortest impact/remediation path.
4. Simulate upstream patch upgrades to immediately quantify risk reduction.

---

2. ⚡ Why a Graph Database? (Graph vs Relational Comparison)

Relational (SQL) databases organize data into rigid tabular rows and columns. In software supply chain security, the central questions are not about isolated rows—they are about dynamic, variable-length paths and topological connections.

Capability	Graph Database (CognoDB / openCypher)	Relational Database (SQL)
Transitive Dependencies (Multi-Hop)	Index-Free Adjacency: Follows direct memory pointers in constant time per hop [:DEPENDS_ON*1..5].	Expensive Recursive CTEs: Requires WITH RECURSIVE with exponential join overhead and memory spikes.
Query Ergonomics	Concise, visual pattern matching (MATCH (s)-[:DEPENDS_ON*]->(p)-[:HAS_VULN]->(v)).	4+ nested joins across Services, DirectDeps, TransitiveDeps, Packages, and CVEs.
Arbitrary Depth Traversal	Native variable-length syntax *1..N. Query engine handles cycles and depth naturally.	Must pre-define fixed join levels or risk infinite loops without complex CTE cycle detection.
Shortest Path Analysis	Built-in shortestPath() graph algorithm executed directly in the database engine.	Impossible in standard SQL without custom Dijkstra algorithms implemented in external application code.

---

3. 📐 Graph Data Model

The graph data model consists of labeled nodes, typed directed relationships, and rich properties:

graph LR
    subgraph Microservice Layer
        S1[Service: CheckoutGateway]
        S2[Service: AuthenticationService]
    end

    subgraph Package Dependency Layer
        P1[Package: spring-boot-starter-web]
        P2[Package: spring-core]
        P3[Package: log4j-core]
        P4[Package: express]
        P5[Package: lodash]
    end

    subgraph Vulnerability Layer
        V1["Vulnerability: CVE-2021-44228 (Log4Shell - CRITICAL)"]
        V2["Vulnerability: CVE-2021-23337 (Lodash Injection - HIGH)"]
    end

    subgraph Infrastructure
        E1[Environment: Production-US-East]
    end

    S1 -->|"DEPENDS_ON {isDirect: true}"| P1
    P1 -->|"DEPENDS_ON {isTransitive: true}"| P2
    P2 -->|"DEPENDS_ON {isTransitive: true}"| P3
    P3 -->|HAS_VULNERABILITY| V1

    S2 -->|"DEPENDS_ON {isDirect: true}"| P4
    P4 -->|"DEPENDS_ON {isTransitive: true}"| P5
    P5 -->|HAS_VULNERABILITY| V2

    S1 -->|DEPLOYED_IN| E1
    S2 -->|DEPLOYED_IN| E1

    style S1 fill:#0284c7,stroke:#38bdf8,color:#fff
    style S2 fill:#0284c7,stroke:#38bdf8,color:#fff
    style P1 fill:#7c3aed,stroke:#c084fc,color:#fff
    style P2 fill:#7c3aed,stroke:#c084fc,color:#fff
    style P3 fill:#7c3aed,stroke:#c084fc,color:#fff
    style P4 fill:#7c3aed,stroke:#c084fc,color:#fff
    style P5 fill:#7c3aed,stroke:#c084fc,color:#fff
    style V1 fill:#dc2626,stroke:#f87171,color:#fff
    style V2 fill:#ea580c,stroke:#fb923c,color:#fff
    style E1 fill:#059669,stroke:#34d399,color:#fff

Loading

Node Labels & Properties

• (:Service): id, name, tier, team, env, status
• (:Package): id, name, version, ecosystem, license
• (:Vulnerability): id, cveId, title, severity, cvssScore, summary, fixVersion, remediation
• (:Environment): id, name, cloud, region

Relationship Types

• (:Service)-[:DEPENDS_ON {isDirect: true/false, scope: 'runtime'}]->(:Package)
• (:Package)-[:DEPENDS_ON {isTransitive: true}]->(:Package)
• (:Package)-[:HAS_VULNERABILITY]->(:Vulnerability)
• (:Service)-[:DEPLOYED_IN]->(:Environment)

---

4. 🔍 Main Cypher Queries Explained

All queries use the official Neo4j Python driver (neo4j) and use strict parameterization without string concatenation.

Query 1: Multi-Hop Transitive Blast Radius (2 to 5 Hops)

Finds all upstream services compromised by a specific CVE across variable dependency depth.

MATCH path = (s:Service)-[:DEPENDS_ON*1..5]->(p:Package)-[:HAS_VULNERABILITY]->(v:Vulnerability {cveId: $cveId})
OPTIONAL MATCH (s)-[:DEPLOYED_IN]->(e:Environment)
RETURN 
    s.id AS serviceId,
    s.name AS serviceName,
    s.tier AS tier,
    e.name AS environment,
    p.name AS vulnerablePackage,
    p.version AS packageVersion,
    v.cveId AS cveId,
    v.severity AS severity,
    v.cvssScore AS cvssScore,
    [node in nodes(path) | {id: coalesce(node.id, node.cveId), name: coalesce(node.name, node.cveId), label: labels(node)[0]}] AS pathNodes,
    length(path) AS depthHops
ORDER BY depthHops ASC;

Query 2: Service Exposure Risk Matrix (Awkward in Relational SQL)

Ranks all microservices by their total count of transitive critical and high vulnerabilities.

MATCH (s:Service)
OPTIONAL MATCH (s)-[:DEPENDS_ON*1..5]->(p:Package)-[:HAS_VULNERABILITY]->(v:Vulnerability)
RETURN 
    s.id AS serviceId,
    s.name AS serviceName,
    s.tier AS tier,
    s.team AS team,
    count(DISTINCT v) AS totalCVEs,
    count(DISTINCT CASE WHEN v.severity = 'CRITICAL' THEN v END) AS criticalCVEs,
    count(DISTINCT CASE WHEN v.severity = 'HIGH' THEN v END) AS highCVEs,
    collect(DISTINCT v.cveId) AS cveList
ORDER BY criticalCVEs DESC, totalCVEs DESC;

Query 3: Shortest Impact & Remediation Path

Calculates the exact shortest sequence of dependencies linking a service to a CVE.

MATCH (s:Service {name: $serviceName}), (v:Vulnerability {cveId: $cveId})
MATCH path = shortestPath((s)-[:DEPENDS_ON|HAS_VULNERABILITY*]->(v))
RETURN 
    [node in nodes(path) | coalesce(node.name, node.cveId)] AS pathNodes,
    length(path) AS hopCount;

---

5. 🚀 Getting Started & Setup Instructions

Prerequisites

• Python 3.9+
• Node.js 18+ & npm
• A free CognoDB Cloud instance (from https://console.cognodb.com)

---

Step 1: Clone and Configure Environment Variables

git clone https://github.com/<your-username>/shield-graph.git
cd shield-graph

# Copy backend environment template
cp backend/.env.example backend/.env

Edit backend/.env with your CognoDB instance credentials:

COGNODB_URI=bolt+s://<your-instance-id>.databases.cognodb.cloud
COGNODB_USER=cognodb
COGNODB_PASSWORD=<your-generated-password>

Note on Graceful Fallback: If CognoDB credentials are not provided or the database is offline, ShieldGraph automatically activates its rich local standby dataset so you can explore the full UI without interruption.

---

Step 2: Seed the Graph Database

Run the seed script to clear and populate CognoDB with realistic microservice supply chains:

cd backend
pip install -r requirements.txt
python seed.py

---

Step 3: Run the Application Locally

Terminal 1 — Start FastAPI Backend:

cd backend
uvicorn main:app --reload --port 8000

API docs available at: http://localhost:8000/docs

Terminal 2 — Start React Frontend:

cd frontend
npm install
npm run dev

Open your browser at http://localhost:5173.

---

6. 🌐 Live Hosted Demo & Deployment

• Live Hosted Application: https://shield-graph.vercel.app
• Screen Recording Walkthrough: Watch Demo on Loom
• GitHub Repository: https://github.com/srikrishna0603/shield-graph

---

7. 🛡️ Project Structure

shield-graph/
├── backend/
│   ├── main.py            # FastAPI REST API
│   ├── db.py              # CognoDB Neo4j driver connection pool & health checks
│   ├── queries.py         # Parameterized openCypher queries
│   ├── mock_data.py       # Seed dataset & offline fallback data
│   ├── seed.py            # CLI database seeding script
│   ├── requirements.txt   # Python dependencies
│   └── .env.example       # Environment variable template
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── GraphCanvas.jsx          # Interactive Force-Directed Canvas
│   │   │   ├── StatsOverview.jsx        # Top-level SOC metrics
│   │   │   ├── BlastRadiusModal.jsx     # Transitive ripple simulator
│   │   │   ├── CveExplorer.jsx          # Filterable CVE cards & patch simulator
│   │   │   ├── ServiceList.jsx          # Microservices risk exposure table
│   │   │   └── QueryExplainerModal.jsx  # Live Cypher vs SQL comparison modal
│   │   ├── api.js         # API client
│   │   ├── App.jsx        # Dashboard layout
│   │   └── index.css      # Dark Cyber SOC design tokens
│   ├── package.json
│   └── vite.config.js
├── INTERVIEW_CHEATSHEET.md# Comprehensive interview guide & plain-English code explanations
├── vercel.json            # Vercel deployment configuration
└── README.md