Skip to content

ahakim1987/patch-monitor

BranchesTags

Repository files navigation

Linux Patch Management Monitoring Tool

A lightweight, read-only patch management monitoring tool designed to provide SecOps teams with real-time visibility into the patching status of Linux hosts across their network infrastructure.

🎯 What This Tool Does

This tool solves the critical problem of patch management visibility in enterprise Linux environments. It provides:

Core Problem Solved

  • Patch Status Blindness: No centralized view of which hosts need updates
  • Security Risk Management: Identify hosts with critical vulnerabilities
  • Compliance Tracking: Monitor patch compliance across your infrastructure
  • Operational Efficiency: Reduce manual patch checking and reporting

Key Capabilities

  • Real-time Monitoring: Live status of all Linux hosts in your network
  • Vulnerability Assessment: CVE mapping and security update prioritization
  • Compliance Reporting: Automated reports for audit and compliance needs
  • Alert Management: Proactive notifications for critical patch gaps
  • Multi-Environment Support: Works across development, staging, and production

🚀 Features

  • Multi-Distribution Support: Ubuntu, Debian, RHEL, CentOS, Rocky Linux, AlmaLinux, Fedora
  • Real-time Dashboard: Color-coded status indicators and comprehensive host overview
  • Host Profiler: Detailed view of individual host patch status and history
  • CVE Mapping: Cross-reference pending patches with vulnerability databases
  • Alerting: Configurable alerts for critical patch gaps and system issues
  • Reporting: Compliance reports and vulnerability assessments
  • API: RESTful API for integration with existing tools
  • Agent-based Monitoring: Lightweight Python agents for data collection

🏗️ Architecture

  • Backend: FastAPI with PostgreSQL + TimescaleDB
  • Frontend: React 18 with TypeScript and Tailwind CSS
  • Agent: Lightweight Python agent for data collection
  • Deployment: Docker + Docker Compose

🤖 Agent Overview

The agent is a lightweight Python application that runs on each Linux host you want to monitor. It's responsible for:

Data Collection

  • System information: OS, kernel version, architecture, IP addresses
  • Package updates: Pending updates from apt, dnf, yum, zypper, pacman
  • Security updates: Identifies which updates are security-related
  • Patch history: Last patch time and reboot status
  • CVE mapping: Links packages to known vulnerabilities

Multi-Distribution Support

  • Ubuntu, Debian, RHEL, CentOS, Rocky Linux, AlmaLinux, Fedora
  • Automatic detection of package manager (apt, dnf, yum, zypper, pacman)
  • OS-specific commands for data collection

Lightweight Design

  • Minimal resource usage: < 50MB RAM, < 1% CPU
  • Minimal dependencies: Only 3 Python packages (requests, psutil, distro)
  • Secure: Runs as non-root user with limited permissions

Agent Installation

Automated Installation (Recommended)

sudo ./agent/install.sh --server-url http://your-server.com --token your-agent-token

Manual Installation

# Install dependencies
sudo apt-get install python3 python3-pip python3-venv

# Create agent user
sudo useradd --system --no-create-home --shell /bin/false patchmonitor

# Download and install agent
sudo mkdir -p /opt/patchmonitor-agent
sudo cp agent/main.py /opt/patchmonitor-agent/
sudo cp agent/requirements.txt /opt/patchmonitor-agent/

# Install Python dependencies
sudo -u patchmonitor python3 -m venv /opt/patchmonitor-agent/venv
sudo -u patchmonitor /opt/patchmonitor-agent/venv/bin/pip install -r requirements.txt

# Create systemd service
sudo systemctl enable patchmonitor-agent
sudo systemctl start patchmonitor-agent

Agent Service Management

# Check status
sudo systemctl status patchmonitor-agent

# View logs
sudo journalctl -u patchmonitor-agent -f

# Restart
sudo systemctl restart patchmonitor-agent

# Stop
sudo systemctl stop patchmonitor-agent

📋 Prerequisites

System Requirements

  • CPU: 2+ cores (4+ recommended for production)
  • RAM: 4GB minimum (8GB+ recommended)
  • Storage: 20GB+ available space
  • Network: Internet access for CVE database updates

Software Requirements

  • Docker: 20.10+ and Docker Compose 2.0+
  • Node.js: 18+ (for development)
  • Python: 3.11+ (for development)
  • PostgreSQL: 13+ (if not using Docker)

Supported Operating Systems

  • Server: Linux (Ubuntu 20.04+, CentOS 8+, RHEL 8+)
  • Agents: Ubuntu, Debian, RHEL, CentOS, Rocky Linux, AlmaLinux, Fedora
  • Development: Linux, macOS, Windows (with WSL2)

🚀 Quick Start

  1. Clone the repository:

    git clone <repository-url>
cd patch-monitor

  2. Configure environment:

    cp env.example .env
# Edit .env with your configuration

  3. Start the services:

    docker-compose up -d

  4. Access the dashboard:

  5. Deploy agents on your Linux hosts:

    sudo ./agent/install.sh --server-url http://your-server.com --token your-agent-token

📊 Performance & Scale

Tested Limits

  • Hosts: 1,000+ Linux hosts per instance
  • Updates: 10,000+ pending updates tracked
  • Response Time: < 2 seconds for dashboard load
  • Data Retention: 1 year+ of historical data
  • Concurrent Users: 50+ simultaneous dashboard users

Resource Usage

  • Backend: ~200MB RAM, 1 CPU core
  • Frontend: ~50MB RAM, minimal CPU
  • Agent: < 50MB RAM, < 1% CPU per host
  • Database: ~100MB per 100 hosts

🛠️ Development

Prerequisites

  • Docker and Docker Compose
  • Node.js 18+ (for frontend development)
  • Python 3.11+ (for backend development)
  • PostgreSQL 13+

Backend Development

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend Development

cd frontend
npm install
npm run dev

Agent Development

cd agent
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py --help

📁 Project Structure

patch-monitor/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── models.py       # Database models
│   │   ├── schemas.py      # Pydantic schemas
│   │   ├── routers/        # API endpoints
│   │   └── main.py         # FastAPI app
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/                # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── pages/          # Page components
│   │   ├── api/            # API client
│   │   └── stores/         # State management
│   ├── package.json
│   └── Dockerfile
├── agent/                   # Python agent
│   ├── main.py             # Agent application
│   ├── install.sh          # Installation script
│   └── requirements.txt
├── docs/                    # Documentation
│   ├── installation.md
│   ├── user-guide.md
│   ├── api.md
│   └── agent-deployment.md
├── docker-compose.yml       # Docker setup
├── PRD.md                   # Product Requirements
└── README.md

🔧 Configuration

Environment Variables

Key configuration options in .env:

  • DATABASE_URL: PostgreSQL connection string
  • SECRET_KEY: JWT signing key (change in production)
  • AGENT_SECRET_KEY: Token for agent authentication
  • COLLECTION_INTERVAL_MINUTES: How often agents collect data
  • CORS_ORIGINS: Allowed frontend origins

Agent Configuration

The agent can be configured via:

  1. Command line arguments:

    python main.py --server-url http://server.com --token abc123 --interval 3600

  2. Environment variables:

    export PATCHMONITOR_SERVER_URL="http://server.com"
export PATCHMONITOR_TOKEN="abc123"

  3. Configuration file:

    {
  "server_url": "http://server.com",
  "agent_token": "abc123",
  "collection_interval": 3600
}

🔧 API Examples

Get All Hosts

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8001/api/hosts

Get Host Details

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8001/api/hosts/1

Generate Compliance Report

curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"report_type": "compliance", "format": "pdf"}' \
     http://localhost:8001/api/reports/generate

Agent Data Submission

curl -X POST \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"hostname": "web-server-01", "os_name": "Ubuntu", "os_version": "22.04"}' \
     http://localhost:8001/api/agents/submit

🎯 Use Cases & Examples

Enterprise Security Team

  • Daily: Check critical security updates across 500+ servers
  • Weekly: Generate compliance reports for audit requirements
  • Monthly: Review patch trends and identify problem hosts

DevOps Team

  • Pre-deployment: Verify all staging hosts are patched
  • Post-deployment: Monitor production patch status
  • Incident Response: Quickly identify vulnerable hosts during security incidents

Compliance Officer

  • Audit Preparation: Generate comprehensive patch compliance reports
  • Risk Assessment: Identify hosts with critical vulnerabilities
  • Policy Enforcement: Ensure patch policies are being followed

🚨 Troubleshooting

Common Issues

Agent Not Connecting

# Check agent status
sudo systemctl status patchmonitor-agent

# View agent logs
sudo journalctl -u patchmonitor-agent -f

# Test connectivity
curl -v http://your-server.com:8001/api/health

Dashboard Not Loading

# Check frontend container
docker-compose logs frontend

# Check backend API
curl http://localhost:8001/api/health

# Check database connection
docker-compose exec backend python -c "from app.database import engine; print(engine.execute('SELECT 1').scalar())"

Database Issues

# Check database status
docker-compose exec postgres psql -U patchmonitor -d patchmonitor -c "SELECT version();"

# Reset database (WARNING: This will delete all data)
docker-compose down -v
docker-compose up -d

Performance Issues

  • Slow Dashboard: Check database indexes and query performance
  • High Memory Usage: Monitor container resource limits
  • Agent Timeouts: Verify network connectivity and server response times

📚 Documentation

🔒 Security Features

  • Role-based Access Control: Admin, Operator, and Viewer roles
  • JWT Authentication: Secure token-based authentication
  • Data Encryption: All sensitive data encrypted at rest
  • Non-root Agent: Agents run with minimal privileges
  • Audit Logging: Comprehensive activity logging
  • HTTPS Support: Secure communication channels

🚀 Deployment Options

Docker Compose (Recommended)

docker-compose up -d

Manual Installation

  • Backend: FastAPI with PostgreSQL + TimescaleDB
  • Frontend: React with Vite build system
  • Agent: Python with systemd service

Cloud Deployment

  • AWS, Azure, GCP compatible
  • Kubernetes manifests available
  • Auto-scaling support

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

📊 Monitoring & Alerting

  • Real-time Status: Live host status updates
  • Patch Compliance: Automated compliance tracking
  • Security Alerts: Critical vulnerability notifications
  • Performance Metrics: System resource monitoring
  • Custom Dashboards: Configurable views and reports

🆘 Support

  • Documentation: Comprehensive guides and API docs
  • Issues: GitHub issues for bug reports
  • Community: Discussion forums and chat
  • Professional Support: Available for enterprise deployments

📈 Roadmap

  • Windows/macOS agent support
  • Container monitoring
  • Mobile application
  • AI-powered patch recommendations
  • Advanced compliance frameworks (CIS, NIST)
  • Integration with ticketing systems

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ for SecOps teams who need reliable patch monitoring

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages