pynetworkintel 0.2.0__py3-none-any.whl

pynetworkintel/__init__.py

@@ -0,0 +1,7 @@
+"""PyNetworkIntel: AI-powered network intelligence platform."""
+
+__version__ = "0.1.0"
+
+from pynetworkintel.core import Scanner, Analyzer
+
+__all__ = ["Scanner", "Analyzer"]

pynetworkintel/alerts.py

@@ -0,0 +1,276 @@
+"""Alerting system for security findings and changes."""
+
+import logging
+import json
+from datetime import datetime
+from typing import List, Dict, Any, Optional, Callable
+from abc import ABC, abstractmethod
+from sqlalchemy.orm import Session
+
+from pynetworkintel.db import Database, Alert as DBAlert
+
+logger = logging.getLogger(__name__)
+
+
+class AlertChannel(ABC):
+    """Base class for alert channels."""
+
+    @abstractmethod
+    def send(self, alert: Dict[str, Any]) -> bool:
+        """Send alert through channel. Returns True if successful."""
+        pass
+
+
+class SlackAlertChannel(AlertChannel):
+    """Send alerts to Slack."""
+
+    def __init__(self, webhook_url: str):
+        self.webhook_url = webhook_url
+
+    def send(self, alert: Dict[str, Any]) -> bool:
+        """Send alert to Slack via webhook."""
+        try:
+            import requests
+
+            severity_colors = {
+                "critical": "#FF0000",
+                "high": "#FF6600",
+                "medium": "#FFCC00",
+                "low": "#00CC00",
+                "info": "#0099FF",
+            }
+
+            severity = alert.get("severity", "info").lower()
+            color = severity_colors.get(severity, "#999999")
+
+            payload = {
+                "attachments": [
+                    {
+                        "color": color,
+                        "title": alert.get("title", "Security Alert"),
+                        "text": alert.get("description", ""),
+                        "fields": [
+                            {"title": "Severity", "value": severity.upper(), "short": True},
+                            {"title": "Device", "value": alert.get("device_ip", "unknown"), "short": True},
+                            {"title": "Type", "value": alert.get("alert_type", "unknown"), "short": True},
+                        ],
+                        "footer": "PyNetworkIntel",
+                        "ts": int(datetime.utcnow().timestamp()),
+                    }
+                ]
+            }
+
+            response = requests.post(self.webhook_url, json=payload, timeout=10)
+            return response.status_code == 200
+
+        except Exception as e:
+            logger.error(f"Failed to send Slack alert: {e}")
+            return False
+
+
+class EmailAlertChannel(AlertChannel):
+    """Send alerts via email."""
+
+    def __init__(self, smtp_server: str, smtp_port: int, sender: str, recipients: List[str], password: str = ""):
+        self.smtp_server = smtp_server
+        self.smtp_port = smtp_port
+        self.sender = sender
+        self.recipients = recipients
+        self.password = password
+
+    def send(self, alert: Dict[str, Any]) -> bool:
+        """Send alert via email."""
+        try:
+            import smtplib
+            from email.mime.text import MIMEText
+            from email.mime.multipart import MIMEMultipart
+
+            severity = alert.get("severity", "INFO").upper()
+            subject = f"[{severity}] {alert.get('title', 'Security Alert')}"
+
+            body = f"""
+PyNetworkIntel Security Alert
+
+Type: {alert.get('alert_type', 'Unknown')}
+Severity: {severity}
+Device: {alert.get('device_ip', 'Unknown')}
+Title: {alert.get('title', 'N/A')}
+
+Description:
+{alert.get('description', 'No description')}
+
+Time: {datetime.utcnow().isoformat()}
+"""
+
+            message = MIMEMultipart()
+            message["From"] = self.sender
+            message["To"] = ", ".join(self.recipients)
+            message["Subject"] = subject
+            message.attach(MIMEText(body, "plain"))
+
+            with smtplib.SMTP(self.smtp_server, self.smtp_port) as server:
+                if self.password:
+                    server.starttls()
+                    server.login(self.sender, self.password)
+                server.send_message(message)
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to send email alert: {e}")
+            return False
+
+
+class WebhookAlertChannel(AlertChannel):
+    """Send alerts via generic webhook."""
+
+    def __init__(self, webhook_url: str):
+        self.webhook_url = webhook_url
+
+    def send(self, alert: Dict[str, Any]) -> bool:
+        """Send alert to webhook."""
+        try:
+            import requests
+
+            payload = json.dumps(alert, default=str)
+            response = requests.post(
+                self.webhook_url,
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                timeout=10,
+            )
+            return response.status_code in (200, 201, 202)
+
+        except Exception as e:
+            logger.error(f"Failed to send webhook alert: {e}")
+            return False
+
+
+class AlertManager:
+    """Manage alert channels and routing."""
+
+    def __init__(self, db: Database):
+        self.db = db
+        self.channels: Dict[str, AlertChannel] = {}
+        self.rules: List[Dict[str, Any]] = []
+
+    def add_channel(self, name: str, channel: AlertChannel):
+        """Add an alert channel."""
+        self.channels[name] = channel
+        logger.info(f"Registered alert channel: {name}")
+
+    def add_rule(self, rule: Dict[str, Any]):
+        """
+        Add alert routing rule.
+
+        Example:
+            {
+                "condition": "severity == 'critical'",
+                "channels": ["slack", "email"],
+                "enabled": True
+            }
+        """
+        self.rules.append(rule)
+
+    def create_alert(
+        self,
+        alert_type: str,
+        severity: str,
+        title: str,
+        description: str,
+        device_ip: Optional[str] = None,
+        cve_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Create and send alert."""
+        alert = {
+            "alert_type": alert_type,
+            "severity": severity,
+            "title": title,
+            "description": description,
+            "device_ip": device_ip,
+            "cve_id": cve_id,
+            "created_at": datetime.utcnow().isoformat(),
+        }
+
+        # Save to database
+        self._save_alert(alert)
+
+        # Send through channels
+        self._send_alert(alert)
+
+        return alert
+
+    def _send_alert(self, alert: Dict[str, Any]):
+        """Send alert through appropriate channels."""
+        # Determine which channels to use (simple routing based on severity)
+        severity_map = {
+            "critical": ["slack", "email"],
+            "high": ["slack", "email"],
+            "medium": ["slack"],
+            "low": ["email"],
+            "info": [],
+        }
+
+        severity = alert.get("severity", "info").lower()
+        channel_names = severity_map.get(severity, [])
+
+        for channel_name in channel_names:
+            if channel_name in self.channels:
+                try:
+                    self.channels[channel_name].send(alert)
+                except Exception as e:
+                    logger.error(f"Error sending alert via {channel_name}: {e}")
+
+    def _save_alert(self, alert: Dict[str, Any]):
+        """Save alert to database."""
+        session = self.db.get_session()
+
+        try:
+            db_alert = DBAlert(
+                alert_type=alert.get("alert_type"),
+                severity=alert.get("severity"),
+                title=alert.get("title"),
+                description=alert.get("description"),
+                device_ip=alert.get("device_ip"),
+                cve_id=alert.get("cve_id"),
+                status="pending",
+            )
+            session.add(db_alert)
+            session.commit()
+
+        finally:
+            session.close()
+
+    def get_pending_alerts(self) -> List[Dict[str, Any]]:
+        """Get all pending alerts."""
+        session = self.db.get_session()
+
+        try:
+            alerts = session.query(DBAlert).filter(DBAlert.status == "pending").all()
+            return [
+                {
+                    "id": a.id,
+                    "alert_type": a.alert_type,
+                    "severity": a.severity,
+                    "title": a.title,
+                    "created_at": a.created_at,
+                }
+                for a in alerts
+            ]
+
+        finally:
+            session.close()
+
+    def acknowledge_alert(self, alert_id: int):
+        """Mark alert as acknowledged."""
+        session = self.db.get_session()
+
+        try:
+            alert = session.query(DBAlert).filter(DBAlert.id == alert_id).first()
+            if alert:
+                alert.acknowledged_at = datetime.utcnow()
+                alert.status = "acknowledged"
+                session.commit()
+
+        finally:
+            session.close()

pynetworkintel/analysis/__init__.py

@@ -0,0 +1,7 @@
+"""Security analysis engines."""
+
+from pynetworkintel.analysis.rules import RuleChecker, Rule
+from pynetworkintel.analysis.cve import CVEChecker
+from pynetworkintel.analysis.llm import LLMAnalyzer
+
+__all__ = ["RuleChecker", "Rule", "CVEChecker", "LLMAnalyzer"]

pynetworkintel/analysis/cve.py

@@ -0,0 +1,184 @@
+"""CVE database integration and vulnerability checking."""
+
+import logging
+import requests
+import time
+from typing import List, Optional, Dict, Any
+from functools import lru_cache
+from datetime import datetime, timedelta
+
+from pynetworkintel.models import Device, Service, SecurityFinding, Severity, FindingType
+
+logger = logging.getLogger(__name__)
+
+# NVD API endpoint
+NVD_API_URL = "https://services.nvd.nist.gov/rest/json/cves/2.0"
+
+# Service name to CVE search keywords
+SERVICE_KEYWORDS = {
+    "ssh": "OpenSSH",
+    "http": "Apache HTTP",
+    "https": "Apache HTTP",
+    "apache": "Apache HTTP",
+    "nginx": "Nginx",
+    "mysql": "MySQL",
+    "postgresql": "PostgreSQL",
+    "mongodb": "MongoDB",
+    "redis": "Redis",
+    "docker": "Docker",
+    "kubernetes": "Kubernetes",
+    "python": "Python",
+    "nodejs": "Node.js",
+    "java": "Java",
+}
+
+
+class CVEChecker:
+    """Check services for known vulnerabilities via NVD API."""
+
+    def __init__(self, rate_limit_delay: float = 0.6):
+        self.rate_limit_delay = rate_limit_delay
+        self.last_request_time = 0.0
+        self._cache = {}
+
+    def check_device(self, device: Device) -> List[SecurityFinding]:
+        """
+        Check all services on device for known vulnerabilities.
+
+        Args:
+            device: Device to check
+
+        Returns:
+            List of CVE-based security findings
+        """
+        findings = []
+
+        for service in device.services:
+            if service.version:
+                cves = self.get_cves_for_service(service.name, service.version)
+                for cve in cves:
+                    finding = self._create_finding(device, service, cve)
+                    findings.append(finding)
+
+        return findings
+
+    def get_cves_for_service(self, service_name: str, version: str) -> List[Dict[str, Any]]:
+        """
+        Get CVEs for a specific service and version.
+
+        Args:
+            service_name: Name of the service (e.g., 'Apache', 'OpenSSH')
+            version: Version string
+
+        Returns:
+            List of CVE dictionaries
+        """
+        cache_key = f"{service_name}:{version}"
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        keyword = SERVICE_KEYWORDS.get(service_name.lower(), service_name)
+        search_query = f"{keyword} {version}"
+
+        try:
+            cves = self._query_nvd(search_query)
+            self._cache[cache_key] = cves
+            return cves
+        except Exception as e:
+            logger.warning(f"Failed to query CVEs for {service_name}: {e}")
+            return []
+
+    def _query_nvd(self, keyword: str) -> List[Dict[str, Any]]:
+        """Query NVD API for CVEs matching keyword."""
+        self._respect_rate_limit()
+
+        params = {
+            "keywordSearch": keyword,
+            "resultsPerPage": 5,
+        }
+
+        try:
+            response = requests.get(NVD_API_URL, params=params, timeout=10)
+            response.raise_for_status()
+
+            data = response.json()
+            vulnerabilities = data.get("vulnerabilities", [])
+
+            cves = []
+            for vuln in vulnerabilities:
+                cve_data = vuln.get("cve", {})
+                cve_id = cve_data.get("id")
+                description = cve_data.get("descriptions", [{}])[0].get("value", "")
+                cvss_score = self._extract_cvss_score(cve_data)
+
+                if cve_id:
+                    cves.append(
+                        {
+                            "id": cve_id,
+                            "description": description,
+                            "cvss_score": cvss_score,
+                        }
+                    )
+
+            return cves
+
+        except requests.RequestException as e:
+            logger.error(f"NVD API request failed: {e}")
+            return []
+
+    def _extract_cvss_score(self, cve_data: Dict[str, Any]) -> Optional[float]:
+        """Extract CVSS score from CVE data."""
+        metrics = cve_data.get("metrics", {})
+
+        # Try CVSS 3.1 first (more recent)
+        cvss31 = metrics.get("cvssMetricV31", [{}])[0]
+        if cvss31 and "cvssData" in cvss31:
+            return cvss31["cvssData"].get("baseScore")
+
+        # Fall back to CVSS 2.0
+        cvss20 = metrics.get("cvssMetricV20", [{}])[0]
+        if cvss20 and "cvssData" in cvss20:
+            return cvss20["cvssData"].get("baseScore")
+
+        return None
+
+    def _respect_rate_limit(self):
+        """Respect NVD API rate limit (1 request per 6 seconds)."""
+        elapsed = time.time() - self.last_request_time
+        if elapsed < self.rate_limit_delay:
+            time.sleep(self.rate_limit_delay - elapsed)
+        self.last_request_time = time.time()
+
+    def _create_finding(
+        self, device: Device, service: Service, cve: Dict[str, Any]
+    ) -> SecurityFinding:
+        """Create security finding from CVE information."""
+        severity = self._cvss_to_severity(cve.get("cvss_score"))
+
+        return SecurityFinding(
+            device=f"{device.ip} ({device.hostname or 'unknown'})",
+            finding_type=FindingType.CVE,
+            severity=severity,
+            title=f"{service.name} {service.version} - {cve['id']}",
+            description=cve.get("description", "Known vulnerability"),
+            evidence=f"Service: {service.name}, Version: {service.version}, Port: {service.port}",
+            recommendation=f"Upgrade {service.name} to a patched version",
+            business_impact=f"Known vulnerability in {service.name} could allow remote attack",
+            cve_id=cve["id"],
+            cvss_score=cve.get("cvss_score"),
+        )
+
+    @staticmethod
+    def _cvss_to_severity(cvss_score: Optional[float]) -> Severity:
+        """Convert CVSS score to severity level."""
+        if cvss_score is None:
+            return Severity.MEDIUM
+
+        if cvss_score >= 9.0:
+            return Severity.CRITICAL
+        elif cvss_score >= 7.0:
+            return Severity.HIGH
+        elif cvss_score >= 4.0:
+            return Severity.MEDIUM
+        else:
+            return Severity.LOW

pynetworkintel/analysis/llm.py

@@ -0,0 +1,183 @@
+"""LLM-powered analysis and summarization using Claude."""
+
+import logging
+import json
+from typing import Optional
+from anthropic import Anthropic
+
+from pynetworkintel.models import ScanResult, SecurityFinding, Severity
+
+logger = logging.getLogger(__name__)
+
+
+class LLMAnalyzer:
+    """Use Claude to synthesize findings and provide business-focused analysis."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.client = Anthropic(api_key=api_key)
+        self.model = "claude-3-5-sonnet-20241022"
+
+    def summarize_findings(self, scan_result: ScanResult) -> str:
+        """
+        Synthesize security findings into plain English summary.
+
+        Args:
+            scan_result: Scan results with devices and findings
+
+        Returns:
+            AI-generated plain English summary
+        """
+        if not scan_result.findings:
+            return self._generate_empty_summary(scan_result)
+
+        prompt = self._build_summary_prompt(scan_result)
+
+        try:
+            message = self.client.messages.create(
+                model=self.model,
+                max_tokens=1500,
+                messages=[{"role": "user", "content": prompt}],
+            )
+
+            return message.content[0].text
+
+        except Exception as e:
+            logger.error(f"LLM summarization failed: {e}")
+            return self._generate_fallback_summary(scan_result)
+
+    def _build_summary_prompt(self, scan_result: ScanResult) -> str:
+        """Build prompt for LLM analysis."""
+        findings_json = json.dumps(
+            [f.to_dict() for f in scan_result.findings],
+            indent=2,
+            default=str,
+        )
+
+        devices_json = json.dumps(
+            [d.to_dict() for d in scan_result.devices],
+            indent=2,
+        )
+
+        return f"""You are a network security analyst explaining findings to an electronics/IoT engineer who doesn't understand networking jargon.
+
+NETWORK SCAN RESULTS:
+{devices_json}
+
+SECURITY FINDINGS:
+{findings_json}
+
+Please provide a clear, non-technical summary:
+
+1. **OVERVIEW** (1-2 sentences): Is the network generally healthy or are there problems?
+
+2. **TOP 3 THINGS TO FIX** (in priority order):
+   - For each: What is it? Why does it matter? How to fix it? Time required?
+
+3. **WHAT'S GOOD** (if anything):
+   - List positive findings
+
+4. **QUESTIONS TO ASK YOUR TEAM**:
+   - What questions should they investigate?
+
+Keep language simple. Use analogies to hardware/electronics when possible. No networking jargon. Explain WHY each issue matters for business/security/reliability."""
+
+    def _generate_empty_summary(self, scan_result: ScanResult) -> str:
+        """Generate summary when no findings detected."""
+        summary = f"""✅ NETWORK HEALTH CHECK - NO ISSUES DETECTED
+
+Devices Found: {scan_result.summary()['total_devices']}
+Online: {scan_result.summary()['online_devices']}
+Critical Issues: 0
+High Priority Issues: 0
+
+Good news! Your network scan didn't find any major security problems. Everything looks secure and properly configured.
+
+However, you should:
+- Continue monitoring regularly (weekly or monthly scans)
+- Keep software updated when new versions are released
+- Review access rules periodically
+"""
+        return summary
+
+    def _generate_fallback_summary(self, scan_result: ScanResult) -> str:
+        """Fallback summary if LLM fails."""
+        summary = scan_result.summary()
+        critical = summary["critical_findings"]
+        high = summary["high_findings"]
+
+        output = f"""NETWORK SECURITY SUMMARY
+
+Devices Discovered: {summary['total_devices']}
+Online Devices: {summary['online_devices']}
+
+ISSUES FOUND:
+- Critical Issues: {critical}
+- High Priority Issues: {high}
+- Total Issues: {summary['total_findings']}
+
+TOP ISSUES:
+"""
+
+        # Sort findings by severity
+        sorted_findings = sorted(
+            scan_result.findings,
+            key=lambda f: (
+                0 if f.severity == Severity.CRITICAL
+                else 1 if f.severity == Severity.HIGH
+                else 2 if f.severity == Severity.MEDIUM
+                else 3
+            ),
+        )
+
+        for i, finding in enumerate(sorted_findings[:3], 1):
+            output += f"""
+{i}. {finding.title}
+   Device: {finding.device}
+   Why it matters: {finding.business_impact}
+   How to fix: {finding.recommendation}
+"""
+
+        return output
+
+    def explain_finding(self, finding: SecurityFinding) -> str:
+        """
+        Explain a single finding in plain English.
+
+        Args:
+            finding: Security finding to explain
+
+        Returns:
+            Plain English explanation
+        """
+        prompt = f"""Explain this security finding to an electronics engineer in simple terms.
+No networking jargon. Use hardware/electronics analogies when helpful.
+
+FINDING: {finding.title}
+DEVICE: {finding.device}
+DESCRIPTION: {finding.description}
+EVIDENCE: {finding.evidence}
+IMPACT: {finding.business_impact}
+RECOMMENDATION: {finding.recommendation}
+
+Please explain:
+1. What is this in simple terms?
+2. Why should they care?
+3. How to fix it (step by step if possible)?
+4. How long does it take to fix?"""
+
+        try:
+            message = self.client.messages.create(
+                model=self.model,
+                max_tokens=800,
+                messages=[{"role": "user", "content": prompt}],
+            )
+
+            return message.content[0].text
+
+        except Exception as e:
+            logger.error(f"Explanation generation failed: {e}")
+            return (
+                f"{finding.title}\n\n"
+                f"Why it matters: {finding.business_impact}\n\n"
+                f"How to fix: {finding.recommendation}"
+            )