🔭 LINSCOPE

Real-time behavioral observability platform for Linux

See what's happening inside your Linux system as a living security graph

✨ What is linscope?

linscope transforms Linux kernel activity into a live visual behavioral system.

Instead of drowning in logs, you see:

🔴 Live process graphs — who spawned what, when, and why
🌐 Network flow maps — real-time connection visualization
⚡ Behavioral anomaly detection — not signature-based
🎬 Attack replay — reconstruct incidents step by step
🤖 AI-powered analysis — local LLM for incident explanation

Built for SOC analysts, pentesters, and security researchers.

🏗️ Architecture

eBPF Collector  →  FastAPI Backend  →  WebSocket  →  React Frontend
      ↓                 ↓                 ↓                ↓
Kernel Event      Real-time          Live Graph      Visualization
   Stream         Processing           Updates
      ↓
Detection Engine  →  Replay Engine  → AI Assistant

📦 Install from Debian package

If you have the packaged installer linscope_v1_amd64.deb, install it with:

sudo dpkg -i linscope_v1_amd64.deb
sudo apt-get install -f

After the package installs, run the application using the installed binary or service. For example:

linscope

If the command is not available, follow the regular source-based startup instructions in the Quick Start section below.

🚀 Quick Start

Prerequisites

Linux (Ubuntu 22.04+, Mint 21+)
Python 3.10+
Node.js 18+
Root access for the collector
eBPF dependencies: bpfcc-tools, python3-bpfcc, linux-headers-$(uname -r), bpftrace
Optional: local Ollama for AI analysis

Install required packages

cd linscope
sudo apt update
sudo apt install -y bpfcc-tools python3-bpfcc linux-headers-$(uname -r) bpftrace
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

npm install is independent of the Python virtual environment.

cd linscope/frontend
npm install

Optional: install Ollama for local AI

If you want the AI Analyst and incident analysis features to work locally, install Ollama and start its local server.

# Follow Ollama install instructions from https://ollama.com/docs/installation
curl -fsSL https://ollama.com/install.sh | sudo bash

Then start the Ollama API server:

ollama serve --port 11434

By default, linscope will use http://localhost:11434 for Ollama. You can override this with OLLAMA_URL=http://localhost:11434 in your environment.

Optional: VirusTotal integration

If you want VirusTotal IOC lookups, run:

bash setup-virustotal.sh

Then set your VIRUSTOTAL_API_KEY in .env.example or a local .env file.

Running linscope

Terminal 1 — Backend

cd linscope/backend
python3 -m uvicorn main:app --reload --port 8000

Terminal 2 — Collector

cd linscope/collector
sudo PYTHONPATH=/usr/lib/python3/dist-packages python3 main.py

Terminal 3 — Frontend

cd linscope/frontend
npm run dev

Open http://localhost:3000 🔭

🎯 Features

Feature	Status	Description
Process Monitoring	✅	eBPF process exec/fork/exit events
Network Monitoring	✅	`NetworkMonitorV2` with `/proc/net/tcp` fallback
File Syscall Monitoring	✅	Experimental open/unlink tracking
Live Graph	✅	Real-time behavioral graph rendering
Timeline View	✅	Zoom, search, PID filter
Replay Engine	✅	Speed control and seek
Detection Engine	✅	Rule-based MITRE-style detection
Alerts Panel	✅	Real-time alert streaming
AI Analyst	✅	Local Ollama + Groq support
Virtual Scrolling	✅	O(1) DOM rendering

📊 Performance (v1.0.0)

Metric	Before	After	Improvement
Max Events/sec	500	2000+	4x
FPS	15-20	45-100	3x
Memory usage	250-300MB	45-100MB	3x
DOM nodes	1000+	50-150	10x

🔌 API Endpoints

Method	Endpoint	Description
GET	/	Health check
POST	/api/events/batch	Ingest event batches from collector
GET	/api/events	Fetch stored events
GET	/api/alerts	Fetch alert history
POST	/api/alerts/feedback	Submit alert feedback
POST	/api/ai/chat	AI chat streaming
POST	/api/ai/analyze-incident	Incident analysis
WebSocket	/ws	Real-time event stream
WebSocket	/ws/alerts	Alert stream

📁 Project Structure

linscope/
|
├── README.md                     # Project overview, installation, usage, and features
├── LICENSE                       # Apache 2.0 license file
├── .gitignore                    # Files/folders ignored by Git
├── .env.example                  # Example environment variables for local config
├── setup-virustotal.sh           # Helper script to configure VirusTotal integration  
├── requirements.txt   
|
├── backend/                      # FastAPI backend and AI integration
|   |
│   ├── main.py                        # Backend application entrypoint
│   ├── detection_engine.py            # Detection rules and alert generation
│   ├── ai_service.py                  # Ollama/Groq AI service integration
│   ├── virustotal.py                  # VirusTotal IOC lookup router
│   ├── backend.log                    # Backend runtime log file
│   ├── linscope.db                    # Local SQLite event store
│   ├── api/                           # Backend API package
│   │   └── __init__.py                # API package initializer
|   |
|   |
│   └── src/                           # Backend utilities and shared helpers
│       └── __init__.py 
|   
|
|
├── collector/                    # eBPF collector and event emitter
|   |
│   ├── main.py                        # Collector entrypoint, starts process/network monitors
│   ├── mock_collector.py              # Synthetic event generator for testing
│   ├── __pycache__/                   # Compiled Python bytecode cache
|   |
|   |
│   └── src/
│       ├── event_emitter.py            # Sends event batches to backend
│       ├── network_monitor_v2.py       # Network monitor with fallback logic
│       ├── process_monitor.py          # Process tracking via eBPF
│       └── file_monitor.py             # Experimental file syscall tracking
|   
|
├── frontend/                     # React frontend app
|   |
│   ├── package.json                   # Frontend npm package manifest
│   ├── package-lock.json              # Locked frontend dependency versions
│   ├── tsconfig.json                  # TypeScript compiler config
│   ├── vite.config.ts                 # Frontend build and dev server config
│   ├── index.html                     # Browser app shell
│   ├── metadata.json                  # App metadata and settings
│   ├── README.md                      # Frontend-specific README
│   ├── .gitignore                     # Frontend ignored files
│   ├── dist/                          # Built frontend assets
│   ├── frontend.log                   # Frontend runtime log file
│   ├── icons/                         # UI icon assets
│   ├── node_modules/                  # Installed npm packages
|   |
│   └── src/
│       ├── App.tsx                       # Main React app component
│       ├── main.tsx                      # React entrypoint rendering App
│       ├── index.css                     # Global frontend styles
│       ├── types.ts                      # Shared TypeScript types
│       ├── vite-env.d.ts                 # Vite environment type defs
│       ├── lib/                          # Utility modules and helpers
│       │   └── utils.ts
|       |
|       |
│       ├── workers/                      # Web Workers for performance offload
│       │   └── anomalyDetection.ts
|       |
|       |
│       ├── components/                   # UI components and panels
│       │   ├── AIChat.tsx
│       │   ├── AlertsPanel.tsx
│       │   ├── AppLayout.tsx
│       │   ├── LiveGraph.tsx
│       │   ├── ReplayView.tsx
│       │   ├── RightPanel.tsx
│       │   ├── SettingsPanel.tsx
│       │   ├── Sidebar.tsx
│       │   ├── TimelineView.tsx
│       │   └── VirtualEventFeed.tsx
|       |
│       └── hooks/                       # React hooks for state and data
│           ├── useAlerts.ts
│           ├── usePanelState.ts
│           ├── useVirusTotal.ts
│           └── useWebSocketAdaptive.ts
| 
├── docs/                         # Documentation and contribution guides
└── venv/                         # Python virtual environment

🖼️ Screenshots

🌐 Notes

collector/main.py requires root and uses PYTHONPATH=/usr/lib/python3/dist-packages for compatibility.
The AI features work best with a running local Ollama server.
Use .env.example to configure optional API keys for Ollama, Groq, Gemini, and VirusTotal.

🤝 Contributing

Contributions welcome! See docs/CONTRIBUTING.md.

📝 License

Apache 2.0 – see LICENSE.

🙏 Acknowledgments

eBPF & BCC communities
FastAPI & React ecosystems

_{Built with ❤️ for the blue team}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🔭 LINSCOPE

✨ What is linscope?

🏗️ Architecture

📦 Install from Debian package

🚀 Quick Start

Prerequisites

Install required packages

Optional: install Ollama for local AI

Optional: VirusTotal integration

Running linscope

🎯 Features

📊 Performance (v1.0.0)

🔌 API Endpoints

📁 Project Structure

🖼️ Screenshots

🌐 Notes

🤝 Contributing

📝 License

🙏 Acknowledgments

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github		.github
backend		backend
collector		collector
docs		docs
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
linscope_v1_amd64.deb		linscope_v1_amd64.deb
requirements.txt		requirements.txt
setup-virustotal.sh		setup-virustotal.sh

Folders and files

Latest commit

History

Repository files navigation

🔭 LINSCOPE

✨ What is linscope?

🏗️ Architecture

📦 Install from Debian package

🚀 Quick Start

Prerequisites

Install required packages

Optional: install Ollama for local AI

Optional: VirusTotal integration

Running linscope

🎯 Features

📊 Performance (v1.0.0)

🔌 API Endpoints

📁 Project Structure

🖼️ Screenshots

🌐 Notes

🤝 Contributing

📝 License

🙏 Acknowledgments

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages