An air-gapped, USB-portable AI Security Operations Center for incident response.
Runs Google's Gemma 2 2B model locally via llama-cpp-python — zero installation, zero cloud, zero host footprint.
Designed for SOC analysts, incident responders, and cybersecurity professionals
who need fast, private threat analysis on compromised or isolated machines.
Gemma AI Security Suite is being transformed into a fully portable, enterprise-ready USB incident response toolkit. It bundles AI-powered cybersecurity tools, offline threat intelligence, and forensic capabilities into a single application that runs directly from a USB drive — leaving zero traces on the host machine.
The application runs Google's Gemma 2 2B entirely on the target machine's hardware with automatic CUDA/CPU detection. Your data never leaves the device. No installation. No internet. No API keys.
| Tool | Description |
|---|---|
| 💬 IT Support Co-Pilot | Interactive chat assistant for real-time IT troubleshooting. Maintains full conversation context with a technical, no-fluff persona. |
| 📊 Log Analyzer | Parses Windows Event Log CSVs, extracts Error/Critical events, and uses AI to summarize root causes with suggested remediation steps. |
| 📜 Script Auditor | Paste any PowerShell or Bash script — the AI identifies security risks, malicious patterns, and explains each code block. |
| ⚡ Regex Wizard | Translates plain English to Regular Expressions, or breaks down complex Regex strings into human-readable explanations. |
| 🎣 Phishing Analyzer | Analyzes raw email headers and body text for phishing indicators, SPF/DKIM failures, and social engineering tactics. |
| Tool | Description |
|---|---|
| 🔐 File Hash Verifier | Calculates MD5 and SHA-256 hashes for any file using memory-safe chunked reading. Useful for verifying file integrity. |
| 🌐 Network Diagnostics | Runs ICMP ping tests and TCP port scans (HTTP, HTTPS, SSH, RDP, etc.) against any host or IP address. |
| 🌍 IP Reputation Lookup | Fully offline IP geolocation and ASN lookup via bundled IP2Location LITE database — no network calls required. |
| Tool | Description |
|---|---|
| 📋 Chain of Custody Logger | Append-only JSONL audit trail with SHA-256 integrity verification. Every toolkit action is logged for forensic defensibility. |
| 🔍 Environment Fingerprint | Captures OS, running processes, network interfaces, ARP table, TCP connections, and Windows Event Log entries in a single snapshot. |
| Pre-scans scripts against malware signatures before AI analysis. Bundled rules detect credential theft, persistence mechanisms, PowerShell cradles, and more. | |
| 🔒 Evidence Vault | AES-256-GCM encrypted storage for suspicious files. PBKDF2 key derivation (600k iterations), SHA-256 integrity verification, append-only manifest. |
| 📡 PCAP Analyzer | Offline parsing of network traffic (.pcap) extracting DNS queries, HTTP cleartext, TLS SNI hostnames, and detecting periodic C2 beaconing. |
| 📄 Incident Report Generator | Exports all session findings (fingerprint, YARA, AI analyses, chat, vault, custody chain, PCAP) as a professional self-contained HTML report. |
| Feature | Description |
|---|---|
| 📁 Zero-Footprint Runtime | All paths resolve relative to the toolkit root. No writes to %APPDATA%, registry, or host temp directories. |
| ⚡ Hardware Auto-Profiling | Automatically detects CUDA GPUs, CPU cores, and available RAM at startup. Configures the LLM for optimal performance without manual tuning. |
| 🌐 100% Offline Operation | IP lookups use a local database. The AI model runs locally. No external API calls of any kind. |
| ⚙️ Portable Configuration | Optional config.ini on the USB root allows overriding data paths for custom deployments. |
┌──────────────────────────────────────────────────────────────────┐
│ main.py │
│ (Application Orchestrator) │
│ config.ensure_dirs() → HW Detect → GUI ↔ Backends → AI │
├──────────┬────────────────────────────────────┬──────────────────┤
│ │ │ │
│ gui_manager.py ai_inference.py │
│ (CustomTkinter UI) (Gemma 2 via llama.cpp) │
│ • 10 stacked frames • Lazy model loading │
│ • Animated dashboard • Auto HW profiling │
│ • Responsive layout • 8192-token context │
│ │ │ │
│ config.py ──────────────────── hardware_profiler.py │
│ (Portable path resolver) (CUDA/CPU/RAM detection) │
│ • Relative paths only • nvidia-smi parsing │
│ • config.ini overrides • Optimal Llama() kwargs │
│ • PyInstaller aware • psutil integration │
│ │ │ │
├──────────┴────────────┬───────────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ log_parser │ │ hash_checker │ │ network_scanner │ │
│ │ (.csv/.evtx) │ │ (MD5/SHA256) │ │ (ping/port scan) │ │
│ └──────────────┘ └──────────────┘ └───────────────────┘ │
│ ┌──────────────┐ ┌─────────────────────────────────────┐ │
│ │ ip_lookup │ │ downloader.py │ │
│ │ (IP2Location) │ │ (Threaded HuggingFace download) │ │
│ │ 100% offline │ │ Portable model storage │ │
│ └──────────────┘ └─────────────────────────────────────┘ │
│ │
│ ┌─────────────────── Forensic Layer ──────────────────────┐ │
│ │ custody_logger.py │ env_fingerprint.py │ yara_scanner │ │
│ │ (JSONL + SHA-256) │ (OS/Net snapshot) │ (.yar rules) │ │
│ ├────────────────────┼────────────────────┼────────────────┤ │
│ │ evidence_vault.py │ report_generator │ │ │
│ │ (AES-256-GCM) │ (HTML/PDF export) │ │ │
│ └────────────────────┴────────────────────┴────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
- Zero Host Footprint — All file paths resolve relative to the toolkit root via
config.py. The suite never writes to%APPDATA%, the Windows registry, or any host directory. Designed for forensic use on compromised machines. - Clean Separation of Concerns — The GUI (
gui_manager.py) contains zero business logic. All AI and tool callbacks are wired inmain.py, making the codebase testable and modular. - Thread Safety — All file I/O and AI inference operations run on background threads. GUI updates are safely marshalled to the main thread via
app.after(). - Hardware Auto-Profiling — On first model load,
hardware_profiler.pydetects CUDA GPUs, CPU cores, and available RAM, then auto-configuresllama-cpp-pythonfor optimal performance (GPU offload, thread count, batch size). - Graceful Degradation — Binary
.evtxfiles are detected early with a helpful error. Missing databases show clear download instructions. The suite works on CPU-only machines with reduced performance.
Deploy to a USB drive for portable, zero-installation use on target machines.
- Clone and install dependencies on your build machine:
git clone https://github.com/K31C0/GemmaSecuritySuite.git cd GemmaSecuritySuite pip install -r requirements.txt - Copy the entire project directory to a USB drive.
- Download the Gemma 2 2B IT model (~1.6 GB) and place it in
data/models/:USB:\GemmaSecuritySuite\data\models\gemma-2-2b-it.gguf - (Optional) Download IP2Location LITE databases and place in
data/databases/:USB:\GemmaSecuritySuite\data\databases\IP2LOCATION-LITE-DB11.BIN USB:\GemmaSecuritySuite\data\databases\IP2LOCATION-LITE-ASN.BIN - On the target machine, simply double-click the launcher script:
The launcher will automatically verify the environment, ensure Python/dependencies are available, and boot the application.
Launch.bat
# Clone the repository
git clone https://github.com/K31C0/GemmaSecuritySuite.git
cd GemmaSecuritySuite
# Install dependencies
pip install customtkinter llama-cpp-python psutil IP2Location
# Launch the application
python main.pyOn first launch, the app will:
- Auto-detect your hardware (CUDA GPU, CPU cores, RAM)
- Download the Gemma 2 2B IT model (~1.6 GB) to
data/models/if not already present - Display the dashboard
- Python 3.12+
- Windows 10/11 (some utilities use Windows-specific subprocess flags)
- ~2 GB disk space for the Gemma 2 2B GGUF model
- (Optional) NVIDIA GPU with CUDA drivers for accelerated inference
GemmaSecuritySuite/
├── main.py # Entry point — orchestrates all tool wiring
├── config.py # Portable path resolver (zero host footprint)
├── gui_manager.py # Full UI: 14 frames, animated dashboard, responsive grid
├── ai_inference.py # LocalAI wrapper — Gemma 2 via llama-cpp-python
├── hardware_profiler.py # Auto-detects CUDA/CPU/RAM, configures LLM
├── downloader.py # Threaded model downloader with progress callbacks
├── log_parser.py # Windows Event Log CSV parser with .evtx detection
├── hash_checker.py # MD5/SHA-256 file hashing (chunked, memory-safe)
├── network_scanner.py # ICMP ping + TCP port scan diagnostics
├── ip_lookup.py # Offline IP geolocation via IP2Location LITE
├── custody_logger.py # Forensic chain of custody (JSONL + SHA-256 sidecar)
├── env_fingerprint.py # Environment snapshot (OS/procs/network/ARP/events)
├── yara_scanner.py # YARA rule engine with graceful fallback
├── evidence_vault.py # AES-256-GCM encrypted evidence storage
├── report_generator.py # Automated incident report (HTML/PDF) generation
├── GemmaSecuritySuite.spec # PyInstaller build configuration
├── requirements.txt # Python package dependencies
└── data/ # Portable data directory (on USB drive)
├── models/ # GGUF model files
├── databases/ # IP2Location BIN files
├── logs/ # Chain of custody logs + env fingerprints
├── evidence/ # Encrypted .vault files + manifest
├── exports/ # Generated HTML/PDF reports
├── playbooks/ # RAG source PDFs (Phase 3)
└── yara_rules/ # YARA signature files
├── community/ # Bundled rules (ir_essentials.yar)
└── custom/ # Analyst's own rules
An optional config.ini in the toolkit root lets you redirect data paths — useful when evidence or logs should be written to a separate partition:
[paths]
models_dir = E:\CustomModels
databases_dir = E:\GeoDBs
logs_dir = E:\IR_Logs
evidence_dir = E:\Evidence
exports_dir = E:\ReportsAny key omitted from the file keeps its default (data/ subdirectory). Relative paths are resolved against the toolkit root.
The interface features a custom "Gemma AI" dark theme with:
- Color Palette: Deep navy background (
#070914), cyan accents (#00E5FF), purple highlights (#B388FF) - Animated Dashboard: Canvas-rendered horizontal "data stream" lines sweeping across the home screen
- Responsive Grid: 4×2 tool card layout with a featured Co-Pilot button spanning the full width
- Context Guidance: Every tool includes an info banner explaining its purpose
- Chat Interface: Full conversation history with visual separators and formatted message blocks
- 100% Offline — The Gemma model runs entirely on local hardware (CPU or CUDA GPU). No data is sent to external AI services.
- Zero Host Footprint — All data is stored on the USB drive. No writes to
%APPDATA%, temp directories, or the Windows registry. - No Telemetry — The application does not collect, store, or transmit any usage data.
- No External API Calls — IP geolocation uses a locally-bundled database. No network calls are made by any tool.
- Open Source — Every line of code is auditable.
The suite is being transformed into a comprehensive Air-Gapped USB Incident Response Toolkit across three phases:
- Zero-Footprint Runtime — Portable path resolution via
config.py,config.inioverrides - Offline Threat Intel — IP2Location LITE replaces
ip-api.comfor 100% offline IP/ASN lookups - Hardware Auto-Profiling — Auto-detect CUDA/CPU/RAM, configure LLM for optimal performance
- Standalone Binary — PyInstaller
.execompilation (deferred to end of project)
- Immutable Chain of Custody Logging — Append-only JSONL audit trail with SHA-256 sidecar integrity verification
- Automated Environment Fingerprinting — Snapshot host OS, processes, network state, ARP table, TCP connections, Windows Event Log
- YARA Rule Engine — Pre-scan scripts against malware signatures; bundled rules for credential theft, PowerShell cradles, persistence, network recon
- Encrypted Evidence Vault — AES-256-GCM encrypted storage with PBKDF2 (600k iter), SHA-256 verification, append-only manifest
- PCAP Traffic Analysis — Offline
.pcapparsing for DNS, HTTP, beaconing, TLS analysis - Automated Incident Reporting — Export all session data as professional self-contained HTML reports
- Dynamic Context Window Management — Auto-summarize old chat history to prevent context overflow
- Multi-Model Fallback — Gracefully swap to smaller models (Phi-3, Qwen2) on low-RAM machines
- RAG Playbooks — Local FAISS vector search over bundled IR playbooks and NIST frameworks
- Live Resource Telemetry — Real-time CPU/RAM/VRAM dashboard widget
- Panic Button / Kill Switch — Instant graceful termination leaving no trace
- Process Tree Visualization — Visual parent-child process mapping for suspicious activity
- Colorblind & High-Contrast Modes — Enterprise accessibility compliance
- Zero-Friction USB Launcher — Single-click
Launch.batandbootstrap.pypreflight checks verify environment dependencies before boot. - Module Health Checks & Auto-Recovery — Centralized watchdog monitors all backend engines. Automatically reloads models, rules, and rotates logs upon failure.
- Session Auto-Save & Restoration — Prevents data loss during host reboots/crashes by periodically saving UI state and chat history.
- Graceful Degradation — If a dependency is missing on an isolated machine, the specific tool disables itself (with a helpful UI hint) rather than crashing the application.
- UI Polish — Toast notifications, degraded-state UI cards, AI output streaming, contextual right-click menus, and keyboard shortcuts.
| Layer | Technology |
|---|---|
| Language | Python 3.12+ |
| GUI Framework | CustomTkinter (Tkinter wrapper) |
| AI Runtime | llama-cpp-python (GGML/GGUF) |
| AI Model | Google Gemma 2 2B Instruct (Q4_K_M) |
| IP Geolocation | IP2Location LITE (offline BIN database) |
| Hardware Detection | psutil + nvidia-smi |
| Hashing | Standard library (hashlib) |
| Networking | Standard library (socket, subprocess) |
| Concurrency | threading (daemon workers + app.after() marshalling) |
| Package | Purpose |
|---|---|
customtkinter |
Modern dark-themed GUI framework |
llama-cpp-python |
Local GGUF model inference engine |
psutil |
Hardware detection, process/network enumeration |
IP2Location |
Offline IP geolocation database reader |
yara-python |
YARA rule compilation and scanning engine |
cryptography |
AES-256-GCM encryption for evidence vault |
dpkt |
Pure-Python PCAP parsing and network protocol decoding |
All other modules use the Python standard library: threading, hashlib, subprocess, socket, csv, os, sys, configparser, tkinter.
This project is licensed under the MIT License — see the LICENSE file for details.
IP geolocation data provided by IP2Location LITE.
Built for incident responders. Powered by local AI.
No cloud. No APIs. No installation. No trace.