runsentry-agent 1.0.0__tar.gz

runsentry_agent-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include scripts/install.sh
+include runsentry-agent.service
+recursive-include runsentry *.py
+

runsentry_agent-1.0.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: runsentry-agent
+Version: 1.0.0
+Summary: RunSentry Agent - Monitor and track scheduled job executions
+Author-email: RunSentry <support@runsentry.io>
+License: MIT
+Project-URL: Homepage, https://runsentry.io
+Project-URL: Documentation, https://docs.runsentry.io
+Project-URL: Repository, https://github.com/runsentry/agent
+Keywords: monitoring,cron,scheduled-jobs,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: k8s
+Requires-Dist: kubernetes>=28.0.0; extra == "k8s"
+
+# RunSentry Agent
+
+The RunSentry agent monitors and tracks scheduled job executions on Linux systems. It discovers cron jobs and Kubernetes CronJobs, tracks their executions, and sends data to the RunSentry backend.
+
+## Features
+
+- 🔍 **Automatic Discovery**: Discovers cron jobs and Kubernetes CronJobs
+- 📊 **Execution Tracking**: Tracks job start, finish, duration, and exit codes
+- 🔒 **Secure**: Outbound-only HTTPS communication, no inbound ports
+- 💾 **Resilient**: Local event buffering for offline operation
+- 🚀 **Easy Installation**: One-line installer script
+
+## Quick Start
+
+### Installation
+
+**One-line installation with automatic registration:**
+
+```bash
+RUNSENTRY_TOKEN=your_token_here curl -fsSL https://get.runsentry.io/install.sh | bash
+```
+
+The installer will:
+1. Validate Linux OS and Python 3.10+
+2. Create isolated virtual environment at `/opt/runsentry/venv`
+3. Install the RunSentry agent package
+4. Automatically register agent with backend (if `RUNSENTRY_TOKEN` is provided)
+5. Install and enable systemd service
+6. Start the service automatically if registration succeeds
+
+**Installation without token (for later registration):**
+
+```bash
+curl -fsSL https://get.runsentry.io/install.sh | bash
+
+# Register manually later
+RUNSENTRY_TOKEN=xxx /opt/runsentry/venv/bin/runsentry register --backend-url https://api.runsentry.io
+systemctl start runsentry-agent
+```
+
+**With custom backend URL:**
+
+```bash
+RUNSENTRY_TOKEN=xxx RUNSENTRY_BACKEND_URL=https://api.example.com curl -fsSL https://get.runsentry.io/install.sh | bash
+```
+
+## Usage
+
+### Daemon Mode
+
+The agent runs as a systemd service automatically after installation:
+
+```bash
+# Check status
+systemctl status runsentry-agent
+
+# View logs
+journalctl -u runsentry-agent -f
+
+# Restart
+systemctl restart runsentry-agent
+```
+
+The daemon will:
+- Discover jobs on startup and periodically (every hour)
+- Flush buffered events to the backend (every minute)
+- Run continuously until stopped
+
+### Execution Wrapper
+
+Wrap your cron jobs to track executions:
+
+```bash
+# Instead of:
+0 * * * * /path/to/script.sh
+
+# Use:
+0 * * * * /opt/runsentry/venv/bin/runsentry exec /path/to/script.sh
+```
+
+The wrapper will:
+- Send execution start event
+- Execute your command
+- Capture exit code and duration
+- Send execution finish event
+- Works even if backend is temporarily unavailable (events are buffered)
+
+### CLI Commands
+
+The agent exposes three commands:
+
+- **`runsentry daemon`** - Run agent daemon (used by systemd service)
+- **`runsentry exec <command>`** - Execute and track a job execution
+- **`runsentry register`** - Register agent with backend (internal, used by install.sh)
+
+**Note:** The `register` command is internal and used automatically by `install.sh`. Manual registration can be done if needed:
+```bash
+/opt/runsentry/venv/bin/runsentry register --token xxx --backend-url https://api.runsentry.io
+```
+
+## Configuration
+
+Configuration is stored at `/etc/runsentry/config.yaml`:
+
+```yaml
+agent_id: agt_123
+backend_url: https://api.runsentry.io
+token: <signed-jwt>
+agent_name: prod-vm-1
+```
+
+## Discovery
+
+The agent automatically discovers:
+
+- **Linux Cron**: 
+  - User crontab (`crontab -l`)
+  - System crontab (`/etc/crontab`)
+  - Cron.d directory (`/etc/cron.d/*`)
+
+- **Kubernetes CronJobs**:
+  - Requires `kubernetes` Python package
+  - Uses in-cluster config or kubeconfig
+  - Discovers all namespaces
+
+## Systemd Service
+
+The agent runs as a systemd service:
+
+```bash
+# Check status
+systemctl status runsentry-agent
+
+# View logs
+journalctl -u runsentry-agent -f
+
+# Restart
+systemctl restart runsentry-agent
+
+# Stop
+systemctl stop runsentry-agent
+```
+
+## Upgrading
+
+Upgrade the agent package manually:
+
+```bash
+source /opt/runsentry/venv/bin/activate
+pip install --upgrade runsentry-agent
+systemctl restart runsentry-agent
+```
+
+Configuration is preserved during upgrades.
+
+## Development
+
+### Local Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/runsentry/agent.git
+cd agent
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install in development mode
+pip install -e .
+
+# Install with Kubernetes support
+pip install -e ".[k8s]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Architecture
+
+The agent operates in two modes:
+
+1. **Daemon Mode**: Continuous background process for discovery and sync
+2. **Exec Mode**: Wrapper for individual job executions
+
+All communication is outbound-only HTTPS to the RunSentry backend.
+
+## Security
+
+- ✅ Outbound-only HTTPS
+- ✅ Token-based authentication
+- ✅ Signed agent JWT
+- ✅ Read-only discovery permissions
+- ✅ No inbound ports
+- ✅ Secure configuration file (600 permissions)
+
+## Requirements
+
+- Python 3.10+
+- Linux (Ubuntu, Debian, RHEL, etc.)
+- Network access to RunSentry backend
+- Root or sudo access for installation
+
+## Troubleshooting
+
+### Agent not discovering jobs
+
+- Check that cron jobs exist: `crontab -l`
+- Verify agent has read permissions to `/etc/crontab` and `/etc/cron.d/`
+- Check daemon logs: `journalctl -u runsentry-agent`
+
+### Events not reaching backend
+
+- Check network connectivity to backend URL
+- Verify agent token is valid
+- Check buffered events: `/var/lib/runsentry/buffer/events.jsonl`
+- Review logs for errors
+
+### Service won't start
+
+- Check Python version: `python3 --version`
+- Verify virtual environment exists: `/opt/runsentry/venv`
+- Check systemd logs: `journalctl -u runsentry-agent`
+
+## License
+
+MIT License
+
+## Support
+
+For issues and questions:
+- Documentation: https://docs.runsentry.io
+- Support: support@runsentry.io
+

runsentry_agent-1.0.0/README.md

@@ -0,0 +1,237 @@
+# RunSentry Agent
+
+The RunSentry agent monitors and tracks scheduled job executions on Linux systems. It discovers cron jobs and Kubernetes CronJobs, tracks their executions, and sends data to the RunSentry backend.
+
+## Features
+
+- 🔍 **Automatic Discovery**: Discovers cron jobs and Kubernetes CronJobs
+- 📊 **Execution Tracking**: Tracks job start, finish, duration, and exit codes
+- 🔒 **Secure**: Outbound-only HTTPS communication, no inbound ports
+- 💾 **Resilient**: Local event buffering for offline operation
+- 🚀 **Easy Installation**: One-line installer script
+
+## Quick Start
+
+### Installation
+
+**One-line installation with automatic registration:**
+
+```bash
+RUNSENTRY_TOKEN=your_token_here curl -fsSL https://get.runsentry.io/install.sh | bash
+```
+
+The installer will:
+1. Validate Linux OS and Python 3.10+
+2. Create isolated virtual environment at `/opt/runsentry/venv`
+3. Install the RunSentry agent package
+4. Automatically register agent with backend (if `RUNSENTRY_TOKEN` is provided)
+5. Install and enable systemd service
+6. Start the service automatically if registration succeeds
+
+**Installation without token (for later registration):**
+
+```bash
+curl -fsSL https://get.runsentry.io/install.sh | bash
+
+# Register manually later
+RUNSENTRY_TOKEN=xxx /opt/runsentry/venv/bin/runsentry register --backend-url https://api.runsentry.io
+systemctl start runsentry-agent
+```
+
+**With custom backend URL:**
+
+```bash
+RUNSENTRY_TOKEN=xxx RUNSENTRY_BACKEND_URL=https://api.example.com curl -fsSL https://get.runsentry.io/install.sh | bash
+```
+
+## Usage
+
+### Daemon Mode
+
+The agent runs as a systemd service automatically after installation:
+
+```bash
+# Check status
+systemctl status runsentry-agent
+
+# View logs
+journalctl -u runsentry-agent -f
+
+# Restart
+systemctl restart runsentry-agent
+```
+
+The daemon will:
+- Discover jobs on startup and periodically (every hour)
+- Flush buffered events to the backend (every minute)
+- Run continuously until stopped
+
+### Execution Wrapper
+
+Wrap your cron jobs to track executions:
+
+```bash
+# Instead of:
+0 * * * * /path/to/script.sh
+
+# Use:
+0 * * * * /opt/runsentry/venv/bin/runsentry exec /path/to/script.sh
+```
+
+The wrapper will:
+- Send execution start event
+- Execute your command
+- Capture exit code and duration
+- Send execution finish event
+- Works even if backend is temporarily unavailable (events are buffered)
+
+### CLI Commands
+
+The agent exposes three commands:
+
+- **`runsentry daemon`** - Run agent daemon (used by systemd service)
+- **`runsentry exec <command>`** - Execute and track a job execution
+- **`runsentry register`** - Register agent with backend (internal, used by install.sh)
+
+**Note:** The `register` command is internal and used automatically by `install.sh`. Manual registration can be done if needed:
+```bash
+/opt/runsentry/venv/bin/runsentry register --token xxx --backend-url https://api.runsentry.io
+```
+
+## Configuration
+
+Configuration is stored at `/etc/runsentry/config.yaml`:
+
+```yaml
+agent_id: agt_123
+backend_url: https://api.runsentry.io
+token: <signed-jwt>
+agent_name: prod-vm-1
+```
+
+## Discovery
+
+The agent automatically discovers:
+
+- **Linux Cron**: 
+  - User crontab (`crontab -l`)
+  - System crontab (`/etc/crontab`)
+  - Cron.d directory (`/etc/cron.d/*`)
+
+- **Kubernetes CronJobs**:
+  - Requires `kubernetes` Python package
+  - Uses in-cluster config or kubeconfig
+  - Discovers all namespaces
+
+## Systemd Service
+
+The agent runs as a systemd service:
+
+```bash
+# Check status
+systemctl status runsentry-agent
+
+# View logs
+journalctl -u runsentry-agent -f
+
+# Restart
+systemctl restart runsentry-agent
+
+# Stop
+systemctl stop runsentry-agent
+```
+
+## Upgrading
+
+Upgrade the agent package manually:
+
+```bash
+source /opt/runsentry/venv/bin/activate
+pip install --upgrade runsentry-agent
+systemctl restart runsentry-agent
+```
+
+Configuration is preserved during upgrades.
+
+## Development
+
+### Local Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/runsentry/agent.git
+cd agent
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install in development mode
+pip install -e .
+
+# Install with Kubernetes support
+pip install -e ".[k8s]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## Architecture
+
+The agent operates in two modes:
+
+1. **Daemon Mode**: Continuous background process for discovery and sync
+2. **Exec Mode**: Wrapper for individual job executions
+
+All communication is outbound-only HTTPS to the RunSentry backend.
+
+## Security
+
+- ✅ Outbound-only HTTPS
+- ✅ Token-based authentication
+- ✅ Signed agent JWT
+- ✅ Read-only discovery permissions
+- ✅ No inbound ports
+- ✅ Secure configuration file (600 permissions)
+
+## Requirements
+
+- Python 3.10+
+- Linux (Ubuntu, Debian, RHEL, etc.)
+- Network access to RunSentry backend
+- Root or sudo access for installation
+
+## Troubleshooting
+
+### Agent not discovering jobs
+
+- Check that cron jobs exist: `crontab -l`
+- Verify agent has read permissions to `/etc/crontab` and `/etc/cron.d/`
+- Check daemon logs: `journalctl -u runsentry-agent`
+
+### Events not reaching backend
+
+- Check network connectivity to backend URL
+- Verify agent token is valid
+- Check buffered events: `/var/lib/runsentry/buffer/events.jsonl`
+- Review logs for errors
+
+### Service won't start
+
+- Check Python version: `python3 --version`
+- Verify virtual environment exists: `/opt/runsentry/venv`
+- Check systemd logs: `journalctl -u runsentry-agent`
+
+## License
+
+MIT License
+
+## Support
+
+For issues and questions:
+- Documentation: https://docs.runsentry.io
+- Support: support@runsentry.io
+

runsentry_agent-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runsentry-agent"
+version = "1.0.0"
+description = "RunSentry Agent - Monitor and track scheduled job executions"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "RunSentry", email = "support@runsentry.io"}
+]
+keywords = ["monitoring", "cron", "scheduled-jobs", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Monitoring",
+]
+
+dependencies = [
+    "requests>=2.31.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+k8s = [
+    "kubernetes>=28.0.0",
+]
+
+[project.scripts]
+runsentry = "runsentry.cli:main"
+
+[project.urls]
+Homepage = "https://runsentry.io"
+Documentation = "https://docs.runsentry.io"
+Repository = "https://github.com/runsentry/agent"
+
+[tool.setuptools]
+packages = ["runsentry", "runsentry.discovery", "runsentry.storage", "runsentry.transport"]
+
+[tool.setuptools.package-data]
+runsentry = ["*.yaml", "*.yml"]
+

runsentry_agent-1.0.0/runsentry/__init__.py

@@ -0,0 +1,4 @@
+"""RunSentry Agent - Monitor and track scheduled job executions."""
+
+__version__ = "1.0.0"
+

runsentry_agent-1.0.0/runsentry/__main__.py

@@ -0,0 +1,8 @@
+"""CLI entrypoint for RunSentry agent."""
+
+import sys
+from runsentry.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())
+

runsentry_agent-1.0.0/runsentry/auth.py

@@ -0,0 +1,140 @@
+"""Authentication and agent registration.
+
+Internal module used by install.sh for agent registration.
+Not intended for direct user use.
+"""
+
+import logging
+import sys
+import os
+import time
+import platform
+import socket
+import requests
+from typing import Optional
+from runsentry.config import get_config, CONFIG_PATH
+
+logger = logging.getLogger(__name__)
+
+
+def register_agent(token: str, backend_url: str, agent_name: Optional[str] = None, retries: int = 3, retry_delay: int = 5) -> bool:
+    """
+    Register agent with RunSentry backend.
+    
+    Internal function used by install.sh. Handles registration with retries
+    and saves configuration.
+    
+    Args:
+        token: Registration token (required)
+        backend_url: Backend URL (required)
+        agent_name: Agent name (optional, defaults to hostname)
+        retries: Number of registration retry attempts (default: 3)
+        retry_delay: Delay between retries in seconds (default: 5)
+    
+    Returns:
+        True if registration successful, False otherwise
+    """
+    if not token:
+        logger.error("Registration token is required")
+        return False
+    
+    if not backend_url:
+        logger.error("Backend URL is required")
+        return False
+    
+    config = get_config()
+    
+    # Check if already configured (idempotency)
+    if config.is_configured():
+        logger.info(f"Agent is already configured (ID: {config.agent_id})")
+        return True
+    
+    # Detect agent name if not provided
+    if not agent_name:
+        agent_name = os.environ.get("RUNSENTRY_AGENT_NAME") or socket.gethostname()
+    
+    # Detect host information
+    hostname = socket.gethostname()
+    os_name = platform.system().lower()
+    arch = platform.machine()
+    
+    # Detect agent type
+    agent_type = "linux-cron"
+    if os.path.exists("/var/run/secrets/kubernetes.io"):
+        agent_type = "kubernetes"
+    
+    payload = {
+        "agentName": agent_name,
+        "agentType": agent_type,
+        "version": "1.0.0",
+        "host": {
+            "hostname": hostname,
+            "os": os_name,
+            "arch": arch,
+        },
+    }
+    
+    # Retry logic for registration
+    logger.info(f"Registering agent with backend: {backend_url}")
+    logger.info(f"Agent name: {agent_name}")
+    
+    for attempt in range(1, retries + 1):
+        try:
+            response = requests.post(
+                f"{backend_url}/api/v1/agents/register",
+                json=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "X-Registration-Token": token,
+                },
+                timeout=30,
+            )
+            response.raise_for_status()
+            
+            data = response.json()
+            agent_id = data.get("agentId")
+            agent_token = data.get("token")  # Non-expiring token for all API calls
+            workspace_id = data.get("workspaceId")
+            backend_url_from_response = data.get("backendUrl", backend_url)
+            
+            if not agent_id or not agent_token:
+                raise ValueError("Invalid response from backend: missing agentId or token")
+            
+            # Save configuration
+            config.agent_id = agent_id
+            config.token = agent_token  # This token never expires, use for all API calls
+            config.backend_url = backend_url_from_response  # Use backend URL from response
+            config.agent_name = agent_name
+            if workspace_id:
+                config.workspace_id = workspace_id
+            config.save()
+            
+            logger.info(f"Successfully registered agent: {agent_name} ({agent_id})")
+            logger.info(f"Configuration saved to {CONFIG_PATH}")
+            
+            return True
+            
+        except requests.exceptions.RequestException as e:
+            if attempt < retries:
+                logger.warning(f"Registration attempt {attempt}/{retries} failed: {e}")
+                logger.info(f"Retrying in {retry_delay} seconds...")
+                time.sleep(retry_delay)
+            else:
+                logger.error(f"Failed to register agent after {retries} attempts")
+                if hasattr(e, "response") and e.response is not None:
+                    try:
+                        error_data = e.response.json()
+                        logger.error(f"Backend error: {error_data}")
+                    except:
+                        logger.error(f"Response: {e.response.text}")
+                else:
+                    logger.error(f"Error details: {e}")
+            continue
+        except Exception as e:
+            logger.error(f"Unexpected error during registration: {e}", exc_info=True)
+            if attempt < retries:
+                time.sleep(retry_delay)
+            continue
+    
+    return False
+