Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:Introduction
LLaMa Leaks is a public security awareness project designed to highlight the risks of unintentionally exposing Ollama AI servers to the internet. The project's goal is to educate developers and encourage better security practices in AI deployment. It passively monitors and displays information about publicly exposed servers in an educational and redacted format, without any hacking or exploitation.
Contributions are welcome and should align with the project's core mission of promoting cybersecurity awareness. This guide provides the necessary information to understand the project's architecture, development process, and contribution guidelines. Whether you are looking to contribute code, improve documentation, or help spread the message, this guide will help you get started.
Sources: README.md, frontend/src/pages/About.tsx:43-50
Project Philosophy
The fundamental principle of LLaMa Leaks is to be an educational tool, not a "burn board." It operates under responsible disclosure principles and aims to help, not harm.
- Passive Monitoring: The project does not actively hack, probe, or exploit systems. It only observes and reports on what is already publicly accessible.
- Educational Purpose: The primary goal is to show the unintended consequences of insecure AI deployment and spark conversations about cybersecurity in the AI space.
- Data Handling: All displayed data is masked and sanitized. IP addresses are masked, and geographical information is generalized to protect privacy. The project does not access the AI models or their data.
Sources: README.md:19-25, frontend/src/pages/About.tsx:222-231
How to Contribute
There are several ways to contribute to the LLaMa Leaks project, ranging from code to community engagement.
The general contribution workflow is as follows:
This diagram illustrates the standard process for contributing code to the project.
Sources: README.md:31-36, frontend/src/pages/About.tsx:82-120
Code Contributions
You can contribute by opening an issue to suggest features or report bugs, or by submitting a pull request with improvements.
Sources: README.md:35
Security Awareness and Education
- Share the Project: Spread the word about LLaMa Leaks with other AI developers and teams to raise awareness.
- Create Educational Content: Write tutorials, articles, or create videos about AI security best practices.
Sources: README.md:34, frontend/src/pages/About.tsx:92-95, 104-107
Responsible Disclosure and Tooling
- Report Responsibly: If you find a vulnerability, reach out privately before publicizing it.
- Build Security Tools: Help the community by developing security-first deployment frameworks or other related tools.
Sources: frontend/src/pages/About.tsx:98-101, 110-113
Frontend Tech Stack
The frontend is a modern web application built with Vite, React, and TypeScript. It uses Tailwind CSS for styling and shadcn/ui for the component library.
Key Dependencies
| Library | Purpose |
|---|---|
react | Core UI library |
vite | Build tool and development server |
typescript | Static typing for JavaScript |
tailwindcss | Utility-first CSS framework |
@radix-ui/* | Primitives for building accessible UI components |
lucide-react | Icon library |
@tanstack/react-query | Data fetching and state management |
recharts | Composable charting library |
react-router-dom | Client-side routing |
mapbox-gl | Interactive maps |
Sources: frontend/package.json:12-61
Available Scripts
These scripts are used for development, building, and linting the frontend application.
| Script | Command | Description |
|---|---|---|
dev | vite | Starts the development server. |
build | vite build | Builds the app for production. |
lint | eslint . | Lints the codebase for errors. |
preview | vite preview | Serves the production build locally. |
Sources: frontend/package.json:6-10
Core Application Logic
Data Fetching and Display
The "Live Evidence" section of the application displays data for a randomly selected exposed server. This logic is encapsulated within the LocationInfo.tsx component.
The data fetching process is as follows:
- The
fetchRandomServerfunction is called when the component mounts. - It sends a
fetchrequest to a static JSON file located at/data/live_servers.json. - The JSON response, which is an object of server data, is converted into an array.
- A random server is selected from the array.
- The component's state is updated with the data of the random server, triggering a re-render to display the information.
The following sequence diagram illustrates this flow:
Server Data Structure
The data for each server is structured according to the ServerData interface. Understanding this structure is key to working with the application's core data.
| Field | Type | Description |
|---|---|---|
ip | string | Masked IP address of the server. |
port | number | Port number the service is running on. |
version | string | Ollama version string. |
city | string | City where the server is located. |
country | string | Two-letter country code (e.g., 'US'). |
country_name | string | Full country name (e.g., 'United States'). |
region | string | State or region. |
latitude | string | Latitude coordinate. |
longitude | string | Longitude coordinate. |
local | ServerModel[] | Array of locally available models on the server. |
running | ServerModel[] | Array of currently running models on the server. |
first_seen_online | string | ISO timestamp of when the server was first detected. |
age | string | Human-readable age of the record (e.g., "2 hours ago"). |
status | string | Current status, e.g., 'live'. |
Sources: frontend/src/components/LocationInfo.tsx:14-30
Style and Component Conventions
The project uses a consistent design system defined in frontend/src/index.css and implemented with Tailwind CSS.
Color Palette
The UI colors are defined using CSS variables for easy theming (light and dark modes). When adding new components, please use these variables.
| Variable | Light Mode Value | Dark Mode Value |
|---|---|---|
--background | 210 50% 96% | 210 13% 9% |
--foreground | 210 20% 12% | 210 40% 98% |
--primary | 210 100% 47% | 210 100% 56% |
--destructive | 0 84.2% 60.2% | 0 62.8% 30.6% |
--card | 210 40% 98% | 210 13% 9% |
--border | 210 25% 88% | 210 13% 15% |
Sources: frontend/src/index.css:8-71
Component Usage
The project heavily relies on pre-built and styled components from the frontend/src/components/ui/ directory, which are based on shadcn/ui. When creating new UI elements, prefer reusing these existing components (Button, Card, Badge, etc.) to maintain visual consistency. Icons are provided by the lucide-react library.
Sources: frontend/src/pages/About.tsx:4-8, frontend/package.json:12-40
Summary
Contributing to LLaMa Leaks is an opportunity to help improve the security posture of the open-source AI community. By providing code, raising awareness, or developing new tools, you can be part of a project that aims to make the internet more secure, one server at a time. All contributions, big or small, are valued and help further the educational mission of the project.
Sources: frontend/src/pages/About.tsx:23-25