A macOS-first (also Linux & Windows) persistence mechanism scanner with a beautiful web UI, AI-powered triage, and automated investigation.
Created by @iampopg
For authorized security assessments only. Only use on systems you own or have explicit written permission to scan. The authors assume no liability for misuse.
- Scans your system for all known persistence mechanisms (22 on macOS, 15 on Linux, 20 on Windows)
- AI triage during scan — sends each category to your local or cloud AI to filter out false positives in real time
- Web UI — full browser-based interface, no CLI needed
- AI Analysis tab — post-scan deep analysis, identifies real threats vs false positives
- AI Investigation — click Investigate on any threat, AI runs read-only commands autonomously and gives a verdict (Malicious / Suspicious / Clean)
- Report — view a full HTML report in a new tab with all findings and AI-identified threats
git clone https://github.com/iampopg/persistence-finder.git
cd persistence-finder
pip install -r requirements.txt
# Copy the settings template
cp ai_settings.example.json ai_settings.json
# Start the web UI
python3 web/app.pyOpen http://localhost:5001 in your browser.
Configure AI in the ⚙ Settings tab of the web UI. Two providers supported:
# Install Ollama: https://ollama.ai
ollama pull deepseek-r1Set URL to http://localhost:11434, click Detect, select model, Save.
Get a free API key at console.groq.com.
Best free model: llama-4-scout-17b (30K TPM, 500K TPD).
| # | Technique | Risk |
|---|---|---|
| 1 | LaunchAgents (user + system) | High |
| 2 | LaunchDaemons | High |
| 3 | Login Items (BTM database) | Medium |
| 4 | Cron Jobs | High |
| 5 | Shell Profile Files (.zshrc, .bashrc…) | High |
| 6 | Startup Items (legacy) | Medium |
| 7 | Kernel Extensions (.kext) | Critical |
| 8 | System Extensions (DriverKit) | High |
| 9 | SSH Authorized Keys | Critical |
| 10 | At Jobs | Low |
| 11 | Periodic Scripts (daily/weekly/monthly) | Medium |
| 12 | Config Profiles (MDM) | High |
| 13 | Emond Rules | High |
| 14 | XPC Services | Medium |
| 15 | Login/Logout Hooks (legacy) | High |
| 16 | Dylib Hijacking (DYLD_INSERT_LIBRARIES) | Critical |
| 17 | Dock Items | Low |
| 18 | Spotlight Importers (.mdimporter) | Medium |
| 19 | Browser Extensions (Chrome/Safari/Firefox) | Medium |
| 20 | Sudoers | High |
| 21 | Unsigned Applications | Medium |
| 22 | Quarantine Database | Low |
Cron Jobs, Systemd Services/Timers, RC Scripts, Shell Profiles, SSH Keys, Kernel Modules (LKM), eBPF, LD_PRELOAD, Udev Rules, PAM Modules, At Jobs, XDG Autostart, MOTD Scripts, Systemd Unit Files, Profile.d Scripts
Registry Run Keys, Startup Folders, Scheduled Tasks, Services, Winlogon DLL, Accessibility Features, AppInit DLLs, WMI Subscriptions, LSASS/SSP, IFEO, Netsh Helpers, Port Monitors, Auth Packages, Time Providers, Active Setup, COR_PROFILER, SilentProcessExit, BITS Jobs, Startup Approved, Boot Execute
| Tab | What it does |
|---|---|
| Findings | All scan results, collapsible by category, search, 🔬 Investigate button on each item |
| 🤖 AI Analysis | Sends all findings to AI, renders threat cards with severity + why + MITRE technique |
| Raw JSON | Full scan data, download as JSON |
| ❓ Help | How it works, technique descriptions, AI setup guide |
| ⚙ Settings | AI provider (Ollama/Groq), API key, model selection, test connection |
Click 🔬 Investigate on any threat card. The AI:
- Decides which read-only command to run (e.g.
codesign -dvvv /path,sudo cat /etc/sudoers) - We run it — only safe commands allowed (no modifications, no network)
- AI reads the output and decides: next command, or final verdict
- Up to 6 rounds, streamed live in the modal
- Final verdict: 🚨 MALICIOUS / ⚠ SUSPICIOUS / ✅ CLEAN
Click ⏹ Stop to cancel at any time.
persistence-finder/
├── core/ # Shared helpers (system_info, utils, forensic_helpers)
├── docs/ # Documentation + README
├── scanners/
│ ├── macos_scanner.py # 22 macOS persistence techniques
│ ├── linux_scanner.py # 15 Linux techniques
│ └── windows_scanner.py # 20 Windows techniques
├── web/
│ ├── app.py # Flask backend (scan, AI, investigate, report)
│ ├── static/
│ │ ├── style.css # Dark cybersecurity theme
│ │ └── app.js # Frontend logic
│ └── templates/
│ └── index.html # Single-page app
├── scans/ # Scan results (gitignored)
├── ai_settings.json # Your AI config (gitignored — contains API key)
├── ai_settings.example.json # Empty template (safe to commit)
├── main.py # CLI entry point
└── requirements.txt
- Read-only — the tool never modifies, deletes, or executes anything on your system
- Local AI — with Ollama, no data leaves your machine
- Safe commands only — the investigation feature uses a strict whitelist;
rm,curl,chmodetc. are blocked - API key safety —
ai_settings.jsonis gitignored; only the empty example is committed
- Python 3.8+
pip install -r requirements.txt(Flask, requests, colorama, pyfiglet)- Admin/root for complete scanning (some techniques require elevated privileges)
- Fork the repo
- Create a branch:
git checkout -b feature/my-feature - Commit:
git commit -m 'Add my feature' - Push:
git push origin feature/my-feature - Open a Pull Request
MIT License — Copyright (c) 2025 @iampopg
If you use or modify this code, please credit @iampopg and link back to this repository.
Made with ❤️ by @iampopg — for authorized security testing only.