LLM-Powered Monitoring Agent

This project implements an LLM-powered monitoring agent designed to continuously collect system and network data, analyze it against historical baselines, and alert on anomalies. The agent leverages a local Large Language Model (LLM) for intelligent anomaly detection and integrates with Discord and Google Home for notifications.

Features

• System Log Monitoring: Tracks new entries in /var/log/syslog and /var/log/auth.log (for login attempts).
• Network Metrics: Gathers network performance data by pinging a public IP (e.g., 8.8.8.8).
• Hardware Monitoring: Collects CPU and GPU temperature data.
• Nmap Scanning: Periodically performs network scans to discover hosts and open ports.
• Historical Baseline Analysis: Compares current data against a 24-hour rolling baseline to identify deviations.
• LLM-Powered Anomaly Detection: Utilizes a local LLM (Ollama with Llama3.1) to analyze combined system data, baselines, and Nmap changes for anomalies.
• Alerting: Sends high-severity anomaly alerts to Discord and Google Home speakers (via Home Assistant).
• Daily Recap: Provides a daily summary of detected events.

Recent Improvements

• Enhanced Nmap Data Logging: The Nmap scan results are now processed and stored in a more structured format, including:
  • Discovered IP addresses.
  • Status of each host.
  • Detailed list of open ports for each host, including service, product, and version information. This significantly improves the clarity and utility of Nmap data for anomaly detection.
• Code Refactoring (monitor_agent.py):
  • Optimized Sensor Data Collection: CPU and GPU temperature data are now collected with a single call to the sensors command, improving efficiency.
  • Efficient Login Attempt Logging: The agent now tracks its position in /var/log/auth.log, preventing redundant reads of the entire file and improving performance for large log files.
  • Modular Main Loop: The core monitoring logic has been broken down into smaller, more manageable functions, enhancing readability and maintainability.
  • Separated LLM Prompt Building: The complex LLM prompt construction logic has been moved into a dedicated function, making analyze_data_with_llm more focused.
• Code Refactoring (data_storage.py):
  • Streamlined Baseline Calculations: Helper functions have been introduced to reduce code duplication and improve clarity in the calculation of average metrics for baselines.

Setup and Installation

Prerequisites

• Python 3.x
• ollama installed and running with the llama3.1:8b model pulled (ollama pull llama3.1:8b)
• nmap installed
• lm-sensors installed (for CPU/GPU temperature monitoring)
• Discord webhook URL
• (Optional) Home Assistant instance with a long-lived access token and a Google Home speaker configured.

Installation

1. Clone the repository:

   git clone <repository_url>
   cd LLM-Powered-Monitoring-Agent
   

2. Install Python dependencies:

   pip install -r requirements.txt
   

3. Configure the agent:
   • Open config.py and update the following variables:
     • DISCORD_WEBHOOK_URL
     • HOME_ASSISTANT_URL (if using Google Home alerts)
     • HOME_ASSISTANT_TOKEN (if using Google Home alerts)
     • GOOGLE_HOME_SPEAKER_ID (if using Google Home alerts)
     • NMAP_TARGETS (e.g., "192.168.1.0/24" or "192.168.1.100")
     • NMAP_SCAN_OPTIONS (default is "-sS -T4")
     • DAILY_RECAP_TIME (e.g., "20:00" for 8 PM)
     • TEST_MODE (set to True for a single run, False for continuous operation)

Usage

To run the monitoring agent:

python monitor_agent.py

Test Mode

Set TEST_MODE = True in config.py to run the agent once and exit. This is useful for testing configurations and initial setup.

Extending and Customizing

• Adding New Metrics: You can add new data collection functions in monitor_agent.py and include their results in the combined_data dictionary.
• Customizing LLM Analysis: Modify the CONSTRAINTS.md file to provide specific instructions or constraints to the LLM for anomaly detection.
• Known Issues: Update known_issues.json with any known or expected system behaviors to prevent the LLM from flagging them as anomalies.
• Alerting Mechanisms: Implement additional alerting functions (e.g., email, SMS) in monitor_agent.py and integrate them into the anomaly detection logic.

Project Structure

• monitor_agent.py: Main script for data collection, LLM interaction, and alerting.
• data_storage.py: Handles loading, storing, and calculating baselines from historical data.
• config.py: Stores configurable parameters for the agent.
• requirements.txt: Lists Python dependencies.
• CONSTRAINTS.md: Defines constraints and guidelines for the LLM's analysis.
• known_issues.json: A JSON file containing a list of known issues to be considered by the LLM.
• monitoring_data.json: (Generated) Stores historical monitoring data.
• log_position.txt: (Generated) Stores the last read position for /var/log/syslog.
• auth_log_position.txt: (Generated) Stores the last read position for /var/log/auth.log.