hardstop 0.0.1 → 1.4.0

package/hooks/risk_scoring.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Risk scoring system for command execution safety.
+
+Tracks cumulative risk score per session based on blocked commands.
+Each blocked command contributes to a session risk score based on its severity.
+
+Part of Hardstop v1.4.0 - Phase 2.3: Risk Scoring System
+"""
+
+from typing import Dict, Tuple
+
+# Severity weights: points added to risk score when command is blocked
+SEVERITY_WEIGHTS = {
+    "critical": 25,  # Fork bomb, rm -rf /, credential theft
+    "high": 15,      # Reverse shell, sudo abuse, network exfiltration
+    "medium": 10,    # Config changes, overly permissive permissions
+    "low": 5,        # Suspicious but likely benign
+    "info": 1,       # Logged but not concerning
+}
+
+# Risk thresholds: ranges that define overall session risk level
+RISK_THRESHOLDS = {
+    "low": (0, 24),           # 0-24: minimal risk
+    "moderate": (25, 49),     # 25-49: some concerning patterns
+    "high": (50, 74),         # 50-74: multiple dangerous attempts
+    "critical": (75, float('inf')),  # 75+: sustained attack pattern
+}
+
+
+def calculate_risk_level(score: int) -> str:
+    """
+    Calculate risk level from numeric score.
+
+    Args:
+        score: Cumulative risk score (sum of severity weights)
+
+    Returns:
+        Risk level: "low", "moderate", "high", or "critical"
+
+    Examples:
+        >>> calculate_risk_level(10)
+        'low'
+        >>> calculate_risk_level(30)
+        'moderate'
+        >>> calculate_risk_level(60)
+        'high'
+        >>> calculate_risk_level(100)
+        'critical'
+    """
+    for level, (min_score, max_score) in RISK_THRESHOLDS.items():
+        if min_score <= score <= max_score:
+            return level
+    return "unknown"
+
+
+def get_severity_weight(severity: str) -> int:
+    """
+    Get numeric weight for a severity level.
+
+    Args:
+        severity: Severity level string
+
+    Returns:
+        Weight (points to add to risk score)
+
+    Examples:
+        >>> get_severity_weight("critical")
+        25
+        >>> get_severity_weight("high")
+        15
+        >>> get_severity_weight("invalid")
+        0
+    """
+    return SEVERITY_WEIGHTS.get(severity.lower(), 0)
+
+
+def get_risk_color(level: str) -> str:
+    """
+    Get ANSI color code for risk level.
+
+    Args:
+        level: Risk level string
+
+    Returns:
+        ANSI color code
+
+    Examples:
+        >>> get_risk_color("critical")
+        '\\033[91m'
+        >>> get_risk_color("low")
+        '\\033[92m'
+    """
+    colors = {
+        "low": "\033[92m",      # Green
+        "moderate": "\033[93m",  # Yellow
+        "high": "\033[91m",      # Red
+        "critical": "\033[95m",  # Magenta
+    }
+    return colors.get(level.lower(), "\033[0m")
+
+
+def format_risk_display(score: int, level: str) -> str:
+    """
+    Format risk score and level for display.
+
+    Args:
+        score: Numeric risk score
+        level: Risk level string
+
+    Returns:
+        Formatted string with color
+
+    Examples:
+        >>> format_risk_display(35, "moderate")
+        '\\033[93mMODERATE\\033[0m (35 points)'
+    """
+    color = get_risk_color(level)
+    reset = "\033[0m"
+    return f"{color}{level.upper()}{reset} ({score} points)"
+
+
+def get_risk_description(level: str) -> str:
+    """
+    Get human-readable description of risk level.
+
+    Args:
+        level: Risk level string
+
+    Returns:
+        Description of what this risk level means
+    """
+    descriptions = {
+        "low": "Minimal risk detected. Normal usage patterns.",
+        "moderate": "Some concerning patterns detected. Review blocked commands.",
+        "high": "Multiple dangerous attempts detected. Potential security threat.",
+        "critical": "Sustained attack pattern detected. Immediate review recommended.",
+    }
+    return descriptions.get(level.lower(), "Unknown risk level.")
+
+
+# Export all public functions
+__all__ = [
+    'SEVERITY_WEIGHTS',
+    'RISK_THRESHOLDS',
+    'calculate_risk_level',
+    'get_severity_weight',
+    'get_risk_color',
+    'format_risk_display',
+    'get_risk_description',
+]

package/hooks/session_tracker.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+Session-based risk tracking for Hardstop.
+
+Tracks blocked commands and cumulative risk score per session.
+Persists data to ~/.hardstop/session.json
+
+Part of Hardstop v1.4.0 - Phase 2.3: Risk Scoring System
+"""
+
+import json
+import os
+from pathlib import Path
+from datetime import datetime
+from typing import List, Dict, Optional
+from risk_scoring import SEVERITY_WEIGHTS, calculate_risk_level, get_severity_weight
+
+HARDSTOP_DIR = Path.home() / ".hardstop"
+SESSION_FILE = HARDSTOP_DIR / "session.json"
+
+
+class SessionTracker:
+    """Track session risk and blocked commands."""
+
+    def __init__(self):
+        """Initialize session tracker."""
+        self.session_id = self._get_session_id()
+        self.data = self._load_session()
+
+    def _get_session_id(self) -> str:
+        """
+        Get or create session ID.
+
+        Uses HARDSTOP_SESSION_ID environment variable if set,
+        otherwise creates a new session ID from current timestamp.
+
+        Returns:
+            Session ID string
+        """
+        session_id = os.environ.get('HARDSTOP_SESSION_ID')
+        if not session_id:
+            session_id = datetime.now().strftime('%Y%m%d_%H%M%S')
+            os.environ['HARDSTOP_SESSION_ID'] = session_id
+        return session_id
+
+    def _load_session(self) -> Dict:
+        """
+        Load session data from disk.
+
+        If session file exists and session ID matches, loads existing data.
+        Otherwise creates a new session.
+
+        Returns:
+            Session data dictionary
+        """
+        if SESSION_FILE.exists():
+            try:
+                with open(SESSION_FILE) as f:
+                    data = json.load(f)
+                    # Reset if session ID changed
+                    if data.get('session_id') != self.session_id:
+                        return self._create_new_session()
+                    return data
+            except (json.JSONDecodeError, IOError) as e:
+                # If file is corrupted, create new session
+                print(f"Warning: Failed to load session data: {e}", flush=True)
+                return self._create_new_session()
+        return self._create_new_session()
+
+    def _create_new_session(self) -> Dict:
+        """
+        Create new session data structure.
+
+        Returns:
+            New session dictionary with initial values
+        """
+        return {
+            'session_id': self.session_id,
+            'started_at': datetime.now().isoformat(),
+            'risk_score': 0,
+            'blocked_commands': [],
+        }
+
+    def _save_session(self):
+        """
+        Persist session data to disk.
+
+        Creates ~/.hardstop directory if it doesn't exist.
+        """
+        try:
+            HARDSTOP_DIR.mkdir(parents=True, exist_ok=True)
+            with open(SESSION_FILE, 'w') as f:
+                json.dump(self.data, f, indent=2)
+        except IOError as e:
+            print(f"Warning: Failed to save session data: {e}", flush=True)
+
+    def record_block(self, command: str, pattern_data: Dict):
+        """
+        Record a blocked command and update risk score.
+
+        Args:
+            command: The command that was blocked
+            pattern_data: Pattern information including severity, message, etc.
+        """
+        severity = pattern_data.get('severity', 'medium')
+        weight = get_severity_weight(severity)
+
+        block_record = {
+            'timestamp': datetime.now().isoformat(),
+            'command': command[:200],  # Truncate long commands
+            'severity': severity,
+            'weight': weight,
+            'message': pattern_data.get('message', ''),
+            'pattern_id': pattern_data.get('id', ''),
+            'mitre_attack': pattern_data.get('mitre_attack'),
+            'category': pattern_data.get('category'),
+        }
+
+        self.data['blocked_commands'].append(block_record)
+        self.data['risk_score'] += weight
+        self.data['last_blocked_at'] = datetime.now().isoformat()
+        self._save_session()
+
+    def get_risk_score(self) -> int:
+        """
+        Get current session risk score.
+
+        Returns:
+            Current risk score (cumulative weight of all blocked commands)
+        """
+        return self.data.get('risk_score', 0)
+
+    def get_risk_level(self) -> str:
+        """
+        Get current risk level based on score.
+
+        Returns:
+            Risk level: "low", "moderate", "high", or "critical"
+        """
+        return calculate_risk_level(self.get_risk_score())
+
+    def get_blocked_commands(self) -> List[Dict]:
+        """
+        Get list of blocked commands this session.
+
+        Returns:
+            List of blocked command records
+        """
+        return self.data.get('blocked_commands', [])
+
+    def get_blocked_count(self) -> int:
+        """
+        Get count of blocked commands.
+
+        Returns:
+            Number of commands blocked this session
+        """
+        return len(self.data.get('blocked_commands', []))
+
+    def get_session_info(self) -> Dict:
+        """
+        Get complete session information.
+
+        Returns:
+            Dictionary with session_id, started_at, risk_score, risk_level, blocked_count
+        """
+        return {
+            'session_id': self.session_id,
+            'started_at': self.data.get('started_at'),
+            'last_blocked_at': self.data.get('last_blocked_at'),
+            'risk_score': self.get_risk_score(),
+            'risk_level': self.get_risk_level(),
+            'blocked_count': self.get_blocked_count(),
+        }
+
+    def get_severity_breakdown(self) -> Dict[str, int]:
+        """
+        Get breakdown of blocked commands by severity.
+
+        Returns:
+            Dictionary mapping severity levels to counts
+        """
+        breakdown = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0, 'info': 0}
+        for cmd in self.get_blocked_commands():
+            severity = cmd.get('severity', 'medium')
+            if severity in breakdown:
+                breakdown[severity] += 1
+        return breakdown
+
+    def reset_session(self):
+        """
+        Reset session data.
+
+        Creates a new session with fresh ID and zero risk score.
+        """
+        new_session_id = datetime.now().strftime('%Y%m%d_%H%M%S')
+        os.environ['HARDSTOP_SESSION_ID'] = new_session_id
+        self.session_id = new_session_id
+
+        self.data = {
+            'session_id': self.session_id,
+            'started_at': datetime.now().isoformat(),
+            'risk_score': 0,
+            'blocked_commands': [],
+        }
+        self._save_session()
+
+    def clear_history(self):
+        """
+        Clear blocked commands history but keep current session.
+
+        Resets risk score and command list while maintaining session ID.
+        """
+        self.data['risk_score'] = 0
+        self.data['blocked_commands'] = []
+        if 'last_blocked_at' in self.data:
+            del self.data['last_blocked_at']
+        self._save_session()
+
+
+# Global tracker instance (singleton)
+_tracker: Optional[SessionTracker] = None
+
+
+def get_tracker() -> SessionTracker:
+    """
+    Get global session tracker instance.
+
+    Creates tracker on first call, returns existing instance on subsequent calls.
+
+    Returns:
+        SessionTracker instance
+    """
+    global _tracker
+    if _tracker is None:
+        _tracker = SessionTracker()
+    return _tracker
+
+
+# Export public API
+__all__ = [
+    'SessionTracker',
+    'get_tracker',
+    'HARDSTOP_DIR',
+    'SESSION_FILE',
+]

package/package.json

@@ -1,29 +1,52 @@
 {
   "name": "hardstop",
-  "version": "0.0.1",
-  "description": "The mechanical brake for AI-generated commands. Pre-execution safety validation for Claude Code.",
-  "main": "index.js",
+  "version": "1.4.0",
+  "description": "Pre-execution safety layer for Claude Code - blocks dangerous commands before they run",
   "keywords": [
-    "hardstop",
-    "ai-safety",
-    "command-validation",
-    "security",
     "claude-code",
-    "mcp",
-    "pre-execution",
-    "fail-closed",
-    "llm",
-    "bash",
-    "shell"
+    "plugin",
+    "safety",
+    "security",
+    "command-safety",
+    "shell-protection",
+    "ai-safety",
+    "mitre-attack",
+    "risk-scoring"
   ],
-  "author": "frmoretto <francesco.marinoni.moretto@gmail.com>",
+  "author": {
+    "name": "Francesco Marinoni Moretto",
+    "email": "contact@clarity-gate.org"
+  },
   "license": "CC-BY-4.0",
+  "homepage": "https://github.com/frmoretto/hardstop",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/frmoretto/hardstop.git"
+    "url": "https://github.com/frmoretto/hardstop.git"
   },
   "bugs": {
     "url": "https://github.com/frmoretto/hardstop/issues"
   },
-  "homepage": "https://github.com/frmoretto/hardstop"
+  "bin": {
+    "hardstop": "./bin/install.js"
+  },
+  "files": [
+    ".claude-plugin/",
+    "hooks/",
+    "commands/",
+    "patterns/",
+    "bin/",
+    "skills/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=16.7.0"
+  },
+  "scripts": {
+    "test": "echo \"Use pytest for testing: cd hardstop && pytest tests/\"",
+    "postinstall": "echo \"Run 'npx hardstop install' to install the plugin\""
+  },
+  "dependencies": {},
+  "devDependencies": {}
 }