🛡️ mac-sentinel

AI-powered macOS security monitor — detect threats, anomalies, and suspicious activity using Claude

Features • Install • Usage • How it Works • Contributing

---

mac-sentinel is a command-line security monitor for macOS that uses Claude AI to analyze running processes, network connections, and startup items — and tell you in plain English if something looks suspicious.

$ mac-sentinel scan

╭──────────────────── Security Analysis ─────────────────────╮
│                                                              │
│ ## 🚨 Threat Level: LOW                                      │
│                                                              │
│ ## Security Findings                                         │
│ No overtly malicious processes detected. All running         │
│ processes appear to be standard macOS system services        │
│ and common developer tools.                                  │
│                                                              │
│ ## Network Analysis                                          │
│ 3 listening ports observed: 22 (SSH), 5432 (Postgres),      │
│ 8080 (dev server). Port 22 is open — ensure SSH is          │
│ intentionally enabled.                                       │
│                                                              │
│ ## Recommended Actions                                       │
│ 1. Disable SSH if not needed: sudo systemsetup              │
│    -setremotelogin off                                       │
│ 2. Verify the process on port 8080 is your own dev server   │
│                                                              │
│ ## Summary                                                   │
│ System appears clean. Low risk posture with standard         │
│ developer tooling. No signs of compromise.                   │
╰──────────────────────────────────────────────────────────────╯

---

✨ Features

• AI Security Analysis — Claude reads your system state and explains threats in plain English
• Process Intelligence — Explain any process: is it safe? What is it doing?
• Network Monitoring — See all connections and get AI commentary on suspicious ones
• Startup Item Audit — Review LaunchAgents and LaunchDaemons for persistence mechanisms
• Continuous Watch Mode — Poll your system at set intervals for real-time alerting
• Built-in Heuristics — Flags known suspicious process names and dangerous ports (4444, 1337, etc.)
• macOS Native — Uses psutil and macOS system APIs for accurate data
• Fast Triage — --quick mode for rapid threat assessment

---

📦 Installation

pip install mac-sentinel

Or from source:

git clone https://github.com/mimonimo/mac-sentinel
cd mac-sentinel
pip install -e .

Requirements:

• Python 3.10+
• macOS 12+ (Monterey or later recommended)
• Anthropic API key

export ANTHROPIC_API_KEY="your-key-here"

---

🚀 Usage

Full Security Scan

# Complete AI-powered security analysis
mac-sentinel scan

# Quick triage (faster, less detailed)
mac-sentinel scan --quick

# Save report to file
mac-sentinel scan -o security-report.md

# Raw data only, no AI
mac-sentinel scan --no-ai

Process Analysis

# Show top 20 processes
mac-sentinel processes

# Show top 50 processes
mac-sentinel processes -n 50

# Ask Claude about a specific process
mac-sentinel processes --explain Python
mac-sentinel processes --explain node

Network Monitoring

# All active connections
mac-sentinel network

# Only listening ports
mac-sentinel network --listening

Continuous Monitoring

# Watch every 30 seconds (default)
mac-sentinel watch

# Custom interval
mac-sentinel watch --interval 60

# Full analysis each check
mac-sentinel watch --full

---

🔍 What It Detects

Category	Examples
Suspicious processes	netcat, nmap, metasploit, mimikatz
Dangerous ports	4444 (Metasploit), 1337, 31337, 5555
Unusual outbound connections	Beaconing patterns, unusual IPs
Persistence mechanisms	Unknown LaunchAgents/Daemons
Resource anomalies	Unexpected CPU/memory spikes
Account anomalies	Unexpected logged-in users

---

🤔 How It Works

1. Collect — Gathers process list, network connections, startup items, disk usage, and logged-in users using psutil and macOS utilities
2. Flag — Built-in heuristics check for known suspicious process names and dangerous ports
3. Analyze — Formats all data into a structured prompt and sends to Claude (Haiku for speed/cost)
4. Report — Claude responds with threat level, specific findings, and recommended actions

Privacy: All analysis happens via the Anthropic API. No data is stored locally beyond what you explicitly save with -o.

---

⚙️ Configuration

Variable	Description	Required
ANTHROPIC_API_KEY	Anthropic API key	Yes

---

🏗️ Architecture

mac-sentinel/
├── src/mac_sentinel/
│   ├── collectors.py    # psutil-based system data collection
│   ├── analyzer.py      # Claude API integration
│   └── cli.py           # Typer CLI commands

The tool uses Claude Haiku (the fastest, cheapest Claude model) by default for monitoring use cases where speed matters. The AI never sees your file contents — only metadata about running processes and network connections.

---

🤝 Contributing

Contributions welcome! Ideas:

• VirusTotal integration for process hashes
• macOS System Extensions monitoring
• Slack/Discord alerting for watch mode
• Historical baseline comparison
• Homebrew formula

git clone https://github.com/mimonimo/mac-sentinel
pip install -e ".[dev]"

---

⚠️ Disclaimer

mac-sentinel is a monitoring aid, not a replacement for dedicated security software like Malwarebytes, CrowdStrike, or SentinelOne. Always use multiple layers of security.

---

📝 License

MIT © mimonimo

---

If mac-sentinel helped secure your Mac, give it a ⭐

Built with Claude by mimonimo