A unified security operations toolkit for threat analysis, incident response, and security investigations.
vlair brings 12 specialized security tools under a single vlair command with smart auto-detection, pre-built investigation workflows, actionable output, and a web dashboard with Claude-powered AI threat summaries.
git clone https://github.com/Vligai/vlair.git
cd vlair
pip install -e .Or with optional dependencies:
pip install -e ".[all]" # All features (YARA, PCAP, Redis, AI, etc.)
pip install -e ".[ai]" # Claude-powered AI threat summaries
pip install -e ".[dev]" # Development tools (pytest, black, etc.)Optional: configure API keys for threat intelligence lookups.
cp .env.example .env
# Edit .env with your API keys (see Configuration below)Start a persistent prompt so you don't have to retype vlair for every command.
vlair shell ██╗ ██╗██╗ █████╗ ██╗██████╗
...
Security Operations Toolkit — interactive shell
Type help for commands, exit to quit.
vlair> analyze suspicious.eml
vlair> check hash 44d88612fea8a8f36de82e1278abb02f
vlair> workflow phishing-email report.eml --verbose
vlair> exit
The shell supports command history (Up/Down arrows), per-command help, and all the same commands as the CLI — just without the leading vlair.
The primary command. Automatically identifies what you're analyzing and runs the appropriate tools.
vlair analyze suspicious.eml # Email
vlair analyze 44d88612fea8a8f36de82e1278abb02f # Hash
vlair analyze malicious.com # Domain
vlair analyze 192.168.1.1 # IP
vlair analyze http://evil.com/payload # URL
vlair analyze capture.pcap # Network capture
vlair analyze access.log # Log file
vlair analyze malware.js # ScriptOutput includes a risk score (0-100), verdict (Clean/Suspicious/Malicious), key findings, and recommended actions.
Flags:
--verbose/-v-- detailed output--json/-j-- machine-readable JSON--quiet/-q-- just verdict and score (for scripting)
Pre-built investigation patterns that chain multiple tools together.
vlair workflow phishing-email suspicious.eml # 7-step phishing investigation
vlair workflow malware-triage sample.exe # 7-step malware analysis
vlair workflow ioc-hunt iocs.txt # 6-step bulk IOC hunting
vlair workflow network-forensics capture.pcap # 7-step PCAP forensics
vlair workflow log-investigation access.log # 7-step log analysisInteractive Q&A that walks you through an investigation when you're unsure which tool to use.
vlair investigateRun any individual tool through the unified interface.
vlair eml suspicious.eml --vt
vlair ioc report.txt --format csv
vlair hash 44d88612fea8a8f36de82e1278abb02f
vlair intel malicious.com
vlair log analyze access.log --sigma builtin # Sigma rule detection
vlair pcap capture.pcap
vlair url "http://suspicious.com"
vlair yara scan /samples/ --rules ./rules/
vlair cert https://example.com
vlair deobfuscate malware.js --extract-iocs
vlair feeds update
vlair carve --image disk.dd --output /carved/vlair shell # Interactive REPL shell
vlair list # List all tools with status
vlair info <tool> # Detailed tool documentation
vlair search <keyword> # Find tools by keyword
vlair status # API keys, cache stats, recent history| Tool | Command | Purpose |
|---|---|---|
| EML Parser | eml |
Email header analysis, SPF/DKIM/DMARC, attachment hashing |
| IOC Extractor | ioc |
Extract IPs, domains, URLs, hashes, CVEs from text |
| Hash Lookup | hash |
Query VirusTotal and MalwareBazaar for file hashes |
| Domain/IP Intel | intel |
DNS, reputation, and threat intelligence for domains/IPs |
| Log Analyzer | log |
Detect SQL injection, XSS, brute-force in Apache/Nginx/syslog |
| PCAP Analyzer | pcap |
Network traffic analysis, port scan and DGA detection |
| URL Analyzer | url |
URL reputation checks, suspicious pattern detection |
| YARA Scanner | yara |
Malware detection with YARA rules |
| Cert Analyzer | cert |
SSL/TLS certificate security and phishing checks |
| Deobfuscator | deobfuscate |
Decode obfuscated JS, PowerShell, VBScript, Batch |
| Threat Feeds | feeds |
Aggregate IOCs from ThreatFox and URLhaus |
| File Carver | carve |
Extract embedded files from disk images and memory dumps |
Create a .env file in the project root:
# VirusTotal (free tier: 4 req/min)
# Used by: eml, hash, intel, url
VT_API_KEY=your_key
# AbuseIPDB (free tier available)
# Used by: intel
ABUSEIPDB_KEY=your_key
# Redis (optional, falls back to in-memory cache)
REDIS_URL=redis://localhost:6379/0
# Anthropic (optional — enables AI Analysis in web dashboard)
ANTHROPIC_API_KEY=sk-ant-your_keyAll tools work without API keys but provide limited results.
All commands support multiple output formats:
vlair analyze input.eml # Console (human-readable)
vlair analyze input.eml --json # JSON (machine-readable)
vlair analyze input.eml --quiet # Minimal (verdict + score)
vlair analyze input.eml --report html # HTML report file
vlair analyze input.eml --report md # Markdown report fileExit codes for automation: 0 = Clean, 1 = Suspicious, 2 = Malicious, 3 = Error.
docker build -t vlair .
docker run --rm --env-file .env -v $(pwd)/data:/data vlair analyze /data/suspicious.emlOr with Docker Compose (includes Redis cache):
docker-compose up -d
docker-compose run --rm vlair analyze /data/suspicious.emlA Flask-based web UI with a Vue 3 SPA frontend, JWT auth, TOTP MFA, RBAC, and Claude-powered AI threat summaries.
pip install -r requirements-webapp.txt
pip install "anthropic>=0.34.0" # optional — enables AI Analysis button
export VLAIR_SECRET_KEY=your-secret
export ANTHROPIC_API_KEY=sk-ant-… # optional
flask --app src/vlair/webapp/app.py run
# Visit http://localhost:5000Features:
- All 12 tools accessible via browser with structured result views and charts
- JWT authentication with optional TOTP MFA
- RBAC (viewer / analyst / senior analyst / admin)
- AI Analysis — click "AI Analysis" on any result to get a Claude-generated threat assessment: verdict, severity, MITRE ATT&CK mapping, key findings, and recommended actions
- Audit log and user management (admin)
ModuleNotFoundError -- Install dependencies: pip install -r requirements.txt
API rate limits -- VirusTotal free tier is 4 req/min. Use --rate-limit 4 for batch operations.
YARA not found -- Install: pip install yara-python>=4.3.0
PCAP permission denied -- May need elevated privileges for raw packet access.
Check tool/API status -- Run vlair status to verify configuration.
Contributions welcome. See docs/CONTRIBUTING.md for guidelines and CLAUDE.md for architecture details.
MIT -- See LICENSE for details.