Network Vulnerability Analysis System

A system for creating network topologies, running simulations, and viewing live events.

Architecture Overview

System Components

1. Frontend (frontend/):

   • A Next.js application providing the user interface.
   • Uses React Flow for the TopologyEditor.
   • Displays RunHistory and EventLog using real-time subscriptions to Supabase.
   • Communicates with the Backend API to submit topologies.

2. Backend (backend/):

   • A FastAPI application acting as the service layer.
   • Receives topology submissions (/simulation/topology), creates run records in Supabase, and triggers the simulation process.
   • Receives simulation events (/simulation/event) from the simulation listener and stores them in Supabase, updating run statuses.

3. Simulation (simulation/):

   • Python scripts designed to run network simulations (e.g., using Mininet).
   • main.py: Core simulation logic, configured with a run_id.
   • core/: Contains modules like EventSender to structure event data.
   • api_listener.py: A Flask listener (or similar) that receives events from the simulation process (stdout/stderr or direct calls) and forwards them to the Backend API's /simulation/event endpoint.

4. Database (Supabase):

   • Cloud-based PostgreSQL database with real-time capabilities.
   • simulation_runs table: Stores metadata for each simulation run (ID, status, timestamps).
   • simulation_events table: Stores events generated during each simulation run, linked by simulation_run_id.

Installation

Prerequisites:

• Node.js (v18 or later recommended)
• Python (v3.9 or later recommended)
• pip (Python package installer)
• A Supabase account and project.
• VirtualBox (or another VM provider)
• Mininet VM Image (Download the recommended VirtualBox image)
• SSH client (usually built-in on macOS/Linux, available on Windows)

Steps:

1. Clone the repository:

   git clone https://github.com/CubeStar1/network-vulnerability-analysis.git
   cd network-vulnerability-analysis

2. Set up the Supabase Database:

   • Create a new project in Supabase.
   • Open the SQL editor and run scripts from frontend/lib/supabase/schema.sql to create the necessary tables.

3. Setup Frontend:

   • Navigate to the frontend directory: cd frontend
   • Create a .env.local file by copying .env.example (if provided) or creating it manually.
   • Add your Supabase project URL and Anon Key:

     NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
     NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
     NEXT_PUBLIC_BACKEND_URL=http://localhost:8000 # Or the IP/port where your backend runs

   • Install dependencies: npm install

4. Setup Backend:

   • Navigate to the backend directory: cd ../backend
   • Create a Python virtual environment (recommended):

     python -m venv venv
     source venv/bin/activate # Linux/macOS
     # .\venv\Scripts\activate # Windows

   • Create a .env file.
   • Add your Supabase project URL and Service Role Key:

     SUPABASE_URL=YOUR_SUPABASE_URL
     SUPABASE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY 
     MININET_VM_IP=YOUR_MININET_VM_IP # IP address of your Mininet VM from step 4

   • Install dependencies: pip install -r requirements.txt

5. Setup Mininet VM:

   • Import the downloaded Mininet VM image into VirtualBox.
   • Configure Networking:
     • Go to the VM's Settings -> Network.
     • For Adapter 1, ensure it's Enabled and set "Attached to:" to Bridged Adapter.
     • Select the Name of your host machine's active network interface (e.g., Wi-Fi or Ethernet adapter).
     • (Optional) You might want to configure a second adapter as NAT for easier internet access from within the VM if needed.
   • Start the Mininet VM. Login credentials are typically mininet/mininet.
   • Find the VM's IP address on your local network (using the ip addr command in the VM's terminal, look for the address associated with the bridged interface, likely eth0 or similar).
   • IMPORTANT: Update the MININET_VM_IP environment variable in the backend .env file with the VM's IP address.

6. Setup Simulation Code (inside the VM):

   • Access the VM: It's highly recommended to use SSH to access the VM for easier file management and command execution. You can use VS Code's Remote - SSH extension.

     ssh mininet@<VM_IP_ADDRESS>
     # Default password is 'mininet'

   • Clone the repository inside the VM (if you haven't mounted a shared folder):

     git clone https://github.com/CubeStar1/network-vulnerability-analysis.git
     cd network-vulnerability-analysis/simulation

   • (Optional) Setup Virtual Environment:

     # sudo apt update && sudo apt install python3-venv -y # If venv isn't installed
     python3 -m venv venv
     source venv/bin/activate

   • Install dependencies:

     pip install -r requirements.txt

   • Configure Backend Endpoint:
     • Edit the configuration file: nano core/config.py (or use vim, or edit via VS Code SSH).
     • Update FASTAPI_ENDPOINT to point to the IP address and port where your Backend (FastAPI) service is running. For example, if your backend is running on your host machine at 192.168.1.100:8000, set:

     FASTAPI_ENDPOINT = "http://192.168.1.100:8000"

     • Save the file (Ctrl+X, then Y, then Enter in nano).

Running the System

1. Start the Backend (on your host machine or server):

   • Navigate to the backend directory.
   • Activate the virtual environment.
   • cd ..
   • Run: uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

2. Start the Frontend (on your host machine):

   • Navigate to the frontend directory.
   • Run: npm run dev
   • Access http://localhost:3000 (or your configured port).

3. Start the Simulation Listener (inside the Mininet VM via SSH):

   • Navigate to the simulation directory within the project folder.
   • Activate the virtual environment (if used).
   • Run: python api_listener.py
   • Keep this SSH session open.

Workflow:

1. Open the frontend (http://localhost:3000).
2. Go to the Topology Editor page.
3. Design a network topology.
4. Click "Submit Topology".
5. The frontend sends the topology to the backend.
6. The backend creates a simulation_runs record in Supabase and triggers the simulation via the api_listener.py running in the VM.
7. The api_listener.py starts main.py with the assigned run_id.
8. main.py runs the Mininet simulation, generating events.
9. Events are captured/sent by EventSender back to api_listener.py.
10. api_listener.py POSTs events to the backend's /simulation/{run_id}/event endpoint.
11. The backend saves events to the simulation_events table in Supabase and updates the run status.
12. The frontend's RunHistory and EventLog components update in real-time based on Supabase changes.