LLM-Powered-Monitoring-Agent/README.md

# 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:
    ```bash
    git clone <repository_url>
    cd LLM-Powered-Monitoring-Agent
    ```
2.  Install Python dependencies:
    ```bash
    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:

```bash
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`.