Backend: Server Discovery Engine
Relevant source files
The following files were used as context for generating this wiki page:Introduction
The Server Discovery Engine is the backend component of the LLaMa Leaks project. Its primary purpose is to passively identify and monitor publicly exposed Ollama AI servers on the internet. The engine operates on the principle of observation without intrusion; it does not hack or exploit systems but simply listens for and records information from servers that are already publicly accessible.
The core output of this engine is a static JSON file, live_servers.json, which serves as the data source for the entire frontend application. This decoupled architecture allows the frontend to display near real-time data on exposed servers for educational and security awareness purposes, highlighting the risks of unsecured AI infrastructure. The ultimate goal is to help developers discover and secure their infrastructure before it can be abused by malicious actors.
Sources: README.md, frontend/src/pages/About.tsx:45-51, frontend/src/components/LocationInfo.tsx:43-46
System Architecture
Based on the frontend's data consumption pattern, the backend operates as a data-gathering pipeline that is decoupled from the client-facing application. The engine's process is inferred to run periodically, scanning for servers, enriching the collected data, and writing the results to a static file. The frontend then fetches this file to display the information.
This diagram illustrates the high-level data flow from discovery to presentation.
Data Schema: live_servers.json
The contract between the backend engine and the frontend is the live_servers.json file. The structure of this file is an object where each key is a server identifier and the value is a ServerData object. The ServerData and nested ServerModel structures are defined within the frontend components.
Sources: frontend/src/components/Hero.tsx:11-29, frontend/src/components/LocationInfo.tsx:9-27
ServerData Object
This is the main object representing a single discovered server.
| Field | Type | Description | Source File |
|---|---|---|---|
ip | string | The masked IP address of the exposed server. | frontend/src/components/LocationInfo.tsx:14 |
port | number | The port number the Ollama service is running on. | frontend/src/components/LocationInfo.tsx:15 |
version | string | The version of the Ollama instance. | frontend/src/components/LocationInfo.tsx:16 |
city | string | The city where the server is located. | frontend/src/components/LocationInfo.tsx:17 |
country | string | The 2-letter country code (e.g., 'US'). | frontend/src/components/LocationInfo.tsx:18 |
country_name | string | The full country name (e.g., 'United States'). | frontend/src/components/LocationInfo.tsx:19 |
region | string | The region or state where the server is located. | frontend/src/components/LocationInfo.tsx:20 |
latitude | string | The geographical latitude of the server's location. | frontend/src/components/LocationInfo.tsx:21 |
longitude | string | The geographical longitude of the server's location. | frontend/src/components/LocationInfo.tsx:22 |
local | ServerModel[] | An array of AI models available locally on the server. | frontend/src/components/LocationInfo.tsx:23 |
running | ServerModel[] | An array of AI models currently running in memory on the server. | frontend/src/components/LocationInfo.tsx:24 |
first_seen_online | string | An ISO 8601 timestamp of when the server was first discovered. | frontend/src/components/LocationInfo.tsx:25 |
age | string | A human-readable string representing how long the server has been observed. | frontend/src/components/LocationInfo.tsx:26 |
status | string | The current status of the server (e.g., 'live'). | frontend/src/components/LocationInfo.tsx:27 |
ServerModel Object
This object represents a single AI model found on a discovered server.
| Field | Type | Description | Source File |
|---|---|---|---|
name | string | The name of the model (e.g., 'llama3:8b'). | frontend/src/components/LocationInfo.tsx:10 |
model | string | The base model identifier. | frontend/src/components/LocationInfo.tsx:11 |
size | number | The size of the model in bytes. | frontend/src/components/LocationInfo.tsx:12 |
Schema Relationship Diagram
This ER diagram shows that a Server can have multiple Local Models and multiple Running Models.
Core Functionality (Inferred)
While the backend source code is not available, its functionality can be inferred from the project's documentation and the data it produces.
1. Passive Discovery
The engine's primary task is to find exposed Ollama servers. The project emphasizes a passive, non-intrusive approach, suggesting it relies on public internet scan data or very basic, non-invasive checks rather than aggressive probing or vulnerability scanning.
Sources: README.md:9-12, frontend/src/pages/About.tsx:46-48
2. Data Enrichment and Consumption
Once a server is identified, the engine enriches the basic IP information with:
- Geolocation: Latitude, longitude, city, and country data are added, likely via an IP-to-geolocation API.
- Ollama-Specific Data: It queries the server for its version, local models, and running models.
The frontend consumes this data via a simple fetch request to the static JSON file, as shown in the sequence diagram below.
This diagram shows the frontend fetching and displaying the backend-generated data.
3. Data Output
The final step of the backend process is to serialize the collected and enriched data into the live_servers.json format. This file is then placed in a publicly accessible directory (/data/) for the frontend to consume. This approach simplifies the architecture, as the frontend does not need a live connection to a dynamic backend API.
Sources: frontend/src/components/Hero.tsx:51, frontend/src/components/LocationInfo.tsx:46