exaai-agent 2.0.5__py3-none-any.whl → 2.0.6__py3-none-any.whl

exaaiagnt/tools/tool_prompts.py

@@ -0,0 +1,210 @@
+"""
+Tool Prompts - Enhanced prompts for security testing tools.
+
+Provides intelligent prompts and guidance for:
+- Smart Fuzzer usage
+- Response analysis
+- Vulnerability validation
+- WAF bypass techniques
+"""
+
+# Smart Fuzzer prompts
+FUZZER_SYSTEM_PROMPT = """
+You are an expert security fuzzer. When fuzzing parameters:
+
+1. IDENTIFY PARAMETER TYPE:
+   - Numeric IDs → Test for IDOR, SQLi
+   - URLs → Test for SSRF, Open Redirect
+   - File paths → Test for Path Traversal
+   - User input → Test for XSS, SQLi, SSTI
+
+2. USE CONTEXT-AWARE PAYLOADS:
+   - API endpoints → Focus on injection
+   - Authentication → Focus on bypass
+   - File operations → Focus on traversal
+   - Search/filter → Focus on SQLi
+
+3. ANALYZE RESPONSES:
+   - 500 errors → Possible injection point
+   - Different content length → Boolean-based detection
+   - Time delays → Time-based injection
+   - Error messages → Information disclosure
+
+4. PRIORITIZE:
+   - Critical: SQLi, Command Injection, SSRF
+   - High: XSS, Path Traversal, SSTI
+   - Medium: IDOR, Open Redirect
+"""
+
+# Response Analyzer prompts
+ANALYZER_SYSTEM_PROMPT = """
+When analyzing responses, look for:
+
+1. ERROR PATTERNS:
+   - SQL errors (MySQL, PostgreSQL, MSSQL, Oracle, SQLite)
+   - Stack traces (Python, Java, PHP, Node.js)
+   - Path disclosures (/var/www, C:\\inetpub, /home/)
+
+2. INFORMATION LEAKAGE:
+   - API keys, secrets, tokens
+   - Internal IPs and hostnames
+   - Database connection strings
+   - Debug information
+
+3. SECURITY HEADERS:
+   - Missing: X-Frame-Options, CSP, X-Content-Type-Options
+   - Weak: Permissive CORS, insecure cookies
+
+4. BEHAVIORAL CHANGES:
+   - Response time differences (timing attacks)
+   - Content length variations (boolean-based)
+   - Status code changes
+"""
+
+# Vulnerability Validator prompts
+VALIDATOR_SYSTEM_PROMPT = """
+When validating vulnerabilities:
+
+1. CONFIRM THE FINDING:
+   - Reproduce the issue multiple times
+   - Test with different payloads
+   - Verify impact is real
+
+2. ASSESS SEVERITY:
+   - Critical: RCE, SQLi with data access, Auth bypass
+   - High: XSS (stored), SSRF to internal services
+   - Medium: IDOR, Reflected XSS, Info disclosure
+   - Low: Self-XSS, Rate limit issues
+
+3. GENERATE PoC:
+   - Clear step-by-step reproduction
+   - Include all necessary parameters
+   - Document expected vs actual behavior
+
+4. PROVIDE REMEDIATION:
+   - Specific fix recommendations
+   - Code examples when possible
+   - Security best practices
+"""
+
+# WAF Bypass prompts
+WAF_BYPASS_PROMPT = """
+When encountering WAF blocks:
+
+1. IDENTIFY THE WAF:
+   - Check response headers (Server, X-*)
+   - Analyze block page content
+   - Note status codes (403, 406, 429)
+
+2. TRY BYPASS TECHNIQUES:
+   - URL encoding variations
+   - Unicode normalization
+   - Case manipulation
+   - Comment insertion
+   - HTTP parameter pollution
+   - HTTP verb tampering
+
+3. ENCODING STRATEGIES:
+   - Double URL encoding
+   - HTML entities
+   - Hex encoding
+   - Unicode escapes
+
+4. EVASION PATTERNS:
+   - Payload splitting
+   - Null bytes
+   - Tab/newline injection
+   - JSON/XML smuggling
+"""
+
+# Combined tool usage prompt
+SECURITY_TESTING_PROMPT = """
+# ExaAi Security Testing Workflow
+
+## Step 1: Reconnaissance
+- Map endpoints and parameters
+- Identify input types and contexts
+- Note authentication requirements
+
+## Step 2: Intelligent Fuzzing
+Use SmartFuzzer for context-aware testing:
+```python
+from exaaiagnt.tools import fuzz_parameter, VulnCategory
+# Automatic payload selection based on parameter type
+payloads = fuzz_parameter("user_id", "123")
+```
+
+## Step 3: Response Analysis
+Analyze every response for indicators:
+```python
+from exaaiagnt.tools import analyze_response
+result = analyze_response(response.text, response.status_code)
+for detection in result.detections:
+    print(f"Found: {detection.detection_type} - {detection.evidence}")
+```
+
+## Step 4: WAF Detection & Bypass
+If blocked, attempt bypass:
+```python
+from exaaiagnt.tools import detect_waf, generate_bypasses
+waf_result = detect_waf(status_code, headers, body)
+if waf_result.detected:
+    bypasses = generate_bypasses(original_payload)
+```
+
+## Step 5: Vulnerability Validation
+Confirm and document findings:
+```python
+from exaaiagnt.tools import create_vuln_report
+report = create_vuln_report(
+    vuln_type="sql_injection",
+    url=target_url,
+    parameter="id",
+    payload="' OR 1=1--",
+    evidence="Database error in response"
+)
+# Generates PoC, CVSS, remediation
+```
+
+## Step 6: Report Generation
+Compile all confirmed vulnerabilities with:
+- Severity ratings
+- Proof of Concept
+- Remediation guidance
+"""
+
+
+def get_fuzzer_prompt() -> str:
+    """Get the fuzzer system prompt."""
+    return FUZZER_SYSTEM_PROMPT.strip()
+
+
+def get_analyzer_prompt() -> str:
+    """Get the analyzer system prompt."""
+    return ANALYZER_SYSTEM_PROMPT.strip()
+
+
+def get_validator_prompt() -> str:
+    """Get the validator system prompt."""
+    return VALIDATOR_SYSTEM_PROMPT.strip()
+
+
+def get_waf_bypass_prompt() -> str:
+    """Get the WAF bypass prompt."""
+    return WAF_BYPASS_PROMPT.strip()
+
+
+def get_security_testing_prompt() -> str:
+    """Get the combined security testing workflow prompt."""
+    return SECURITY_TESTING_PROMPT.strip()
+
+
+def get_all_tool_prompts() -> dict[str, str]:
+    """Get all tool prompts as a dictionary."""
+    return {
+        "fuzzer": get_fuzzer_prompt(),
+        "analyzer": get_analyzer_prompt(),
+        "validator": get_validator_prompt(),
+        "waf_bypass": get_waf_bypass_prompt(),
+        "security_testing": get_security_testing_prompt(),
+    }

exaaiagnt/tools/vuln_validator.py

@@ -0,0 +1,412 @@
+"""
+Vulnerability Validator - Validates and confirms detected vulnerabilities.
+
+Features:
+- Confirmation testing
+- PoC generation
+- False positive reduction
+- Severity assessment
+"""
+
+import logging
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional, Callable
+from datetime import datetime
+
+
+logger = logging.getLogger(__name__)
+
+
+class VulnStatus(Enum):
+    """Vulnerability validation status."""
+    PENDING = "pending"
+    CONFIRMED = "confirmed"
+    FALSE_POSITIVE = "false_positive"
+    NEEDS_REVIEW = "needs_review"
+    EXPLOITABLE = "exploitable"
+
+
+class Severity(Enum):
+    """Vulnerability severity levels."""
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "informational"
+
+
+@dataclass
+class VulnerabilityReport:
+    """A validated vulnerability report."""
+    vuln_id: str
+    vuln_type: str
+    status: VulnStatus
+    severity: Severity
+    url: str
+    parameter: str
+    payload: str
+    evidence: str
+    poc_steps: list[str] = field(default_factory=list)
+    remediation: str = ""
+    cvss_score: float = 0.0
+    discovered_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    confirmed_at: Optional[str] = None
+    notes: str = ""
+
+
+@dataclass
+class ValidationTest:
+    """A validation test case."""
+    test_name: str
+    test_func: Callable
+    required: bool = True
+
+
+class VulnValidator:
+    """
+    Vulnerability validation engine.
+    
+    Features:
+    - Confirms vulnerabilities with additional tests
+    - Generates PoC steps
+    - Calculates CVSS scores
+    - Provides remediation advice
+    """
+    
+    _instance: Optional["VulnValidator"] = None
+    
+    def __new__(cls) -> "VulnValidator":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+    
+    def __init__(self):
+        if self._initialized:
+            return
+        
+        self._reports: dict[str, VulnerabilityReport] = {}
+        self._remediation_db = self._load_remediation_db()
+        self._initialized = True
+        logger.info("VulnValidator initialized")
+    
+    def _load_remediation_db(self) -> dict[str, dict[str, Any]]:
+        """Load remediation advice database."""
+        return {
+            "sql_injection": {
+                "severity": Severity.CRITICAL,
+                "cvss_base": 9.8,
+                "remediation": """
+1. Use parameterized queries (prepared statements)
+2. Use ORM frameworks with built-in protection
+3. Validate and sanitize all user inputs
+4. Apply principle of least privilege to database accounts
+5. Enable WAF with SQL injection rules
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Insert payload '{payload}' in parameter '{parameter}'",
+                    "Observe the response showing SQL error or data leakage",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "xss": {
+                "severity": Severity.HIGH,
+                "cvss_base": 7.1,
+                "remediation": """
+1. Encode output based on context (HTML, JS, URL, CSS)
+2. Use Content-Security-Policy header
+3. Validate and sanitize input
+4. Use frameworks with auto-escaping (React, Vue, Angular)
+5. Set HttpOnly flag on cookies
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Insert XSS payload '{payload}' in parameter '{parameter}'",
+                    "Observe JavaScript execution or DOM modification",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "ssrf": {
+                "severity": Severity.HIGH,
+                "cvss_base": 8.6,
+                "remediation": """
+1. Validate and whitelist allowed URLs/domains
+2. Block requests to internal IP ranges
+3. Disable unnecessary URL schemes (file://, gopher://)
+4. Use network segmentation
+5. Implement proper egress filtering
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Supply internal URL '{payload}' in parameter '{parameter}'",
+                    "Observe access to internal resources",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "path_traversal": {
+                "severity": Severity.HIGH,
+                "cvss_base": 7.5,
+                "remediation": """
+1. Validate and sanitize file paths
+2. Use whitelist of allowed files
+3. Chroot or sandbox file access
+4. Remove ../ sequences from input
+5. Use secure file APIs
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Supply path traversal payload '{payload}' in parameter '{parameter}'",
+                    "Observe disclosure of system files",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "command_injection": {
+                "severity": Severity.CRITICAL,
+                "cvss_base": 10.0,
+                "remediation": """
+1. Never pass user input to system commands
+2. Use language-specific APIs instead of shell commands
+3. If unavoidable, use strict input validation
+4. Apply least privilege to application user
+5. Use containerization/sandboxing
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Insert command injection payload '{payload}' in parameter '{parameter}'",
+                    "Observe command execution on server",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "idor": {
+                "severity": Severity.MEDIUM,
+                "cvss_base": 6.5,
+                "remediation": """
+1. Implement proper authorization checks
+2. Use indirect object references (GUIDs)
+3. Verify user has access to requested resource
+4. Log and monitor access patterns
+5. Implement rate limiting
+""",
+                "poc_template": [
+                    "Authenticate as User A",
+                    "Navigate to {url}",
+                    "Change parameter '{parameter}' to another user's ID '{payload}'",
+                    "Observe access to User B's data",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "ssti": {
+                "severity": Severity.CRITICAL,
+                "cvss_base": 9.8,
+                "remediation": """
+1. Never pass user input directly to templates
+2. Use sandboxed template engines
+3. Disable dangerous template features
+4. Validate and sanitize input
+5. Use Content-Security-Policy
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Insert template payload '{payload}' in parameter '{parameter}'",
+                    "Observe template expression evaluation",
+                    "Evidence: {evidence}"
+                ]
+            },
+            "open_redirect": {
+                "severity": Severity.LOW,
+                "cvss_base": 4.7,
+                "remediation": """
+1. Validate redirect URLs against whitelist
+2. Use relative URLs only
+3. Remove user control over redirect destination
+4. Add confirmation page for external redirects
+5. Log redirect attempts
+""",
+                "poc_template": [
+                    "Navigate to {url}",
+                    "Supply external URL '{payload}' in parameter '{parameter}'",
+                    "Observe redirect to external site",
+                    "Evidence: {evidence}"
+                ]
+            },
+        }
+    
+    def create_report(
+        self,
+        vuln_type: str,
+        url: str,
+        parameter: str,
+        payload: str,
+        evidence: str,
+        status: VulnStatus = VulnStatus.PENDING
+    ) -> VulnerabilityReport:
+        """Create a new vulnerability report."""
+        vuln_id = f"{vuln_type}_{hash(url + parameter + payload) & 0xFFFFFFFF:08x}"
+        
+        # Get info from remediation DB
+        vuln_info = self._remediation_db.get(vuln_type, {})
+        severity = vuln_info.get("severity", Severity.MEDIUM)
+        cvss = vuln_info.get("cvss_base", 5.0)
+        remediation = vuln_info.get("remediation", "Review and fix the vulnerability.")
+        
+        # Generate PoC steps
+        poc_template = vuln_info.get("poc_template", [])
+        poc_steps = [
+            step.format(url=url, parameter=parameter, payload=payload, evidence=evidence)
+            for step in poc_template
+        ]
+        
+        report = VulnerabilityReport(
+            vuln_id=vuln_id,
+            vuln_type=vuln_type,
+            status=status,
+            severity=severity,
+            url=url,
+            parameter=parameter,
+            payload=payload,
+            evidence=evidence,
+            poc_steps=poc_steps,
+            remediation=remediation.strip(),
+            cvss_score=cvss
+        )
+        
+        self._reports[vuln_id] = report
+        logger.info(f"Created vulnerability report: {vuln_id}")
+        
+        return report
+    
+    def confirm_vulnerability(self, vuln_id: str, additional_evidence: str = "") -> bool:
+        """Mark a vulnerability as confirmed."""
+        if vuln_id not in self._reports:
+            return False
+        
+        report = self._reports[vuln_id]
+        report.status = VulnStatus.CONFIRMED
+        report.confirmed_at = datetime.now().isoformat()
+        
+        if additional_evidence:
+            report.evidence += f"\n\nAdditional evidence:\n{additional_evidence}"
+        
+        logger.info(f"Confirmed vulnerability: {vuln_id}")
+        return True
+    
+    def mark_exploitable(self, vuln_id: str, exploit_details: str) -> bool:
+        """Mark a vulnerability as exploitable with details."""
+        if vuln_id not in self._reports:
+            return False
+        
+        report = self._reports[vuln_id]
+        report.status = VulnStatus.EXPLOITABLE
+        report.notes += f"\n\nExploit details:\n{exploit_details}"
+        
+        # Increase severity for exploitable vulns
+        if report.severity == Severity.MEDIUM:
+            report.severity = Severity.HIGH
+        elif report.severity == Severity.HIGH:
+            report.severity = Severity.CRITICAL
+        
+        logger.info(f"Marked vulnerability as exploitable: {vuln_id}")
+        return True
+    
+    def mark_false_positive(self, vuln_id: str, reason: str) -> bool:
+        """Mark a vulnerability as false positive."""
+        if vuln_id not in self._reports:
+            return False
+        
+        report = self._reports[vuln_id]
+        report.status = VulnStatus.FALSE_POSITIVE
+        report.notes = f"False positive reason: {reason}"
+        
+        logger.info(f"Marked as false positive: {vuln_id}")
+        return True
+    
+    def get_report(self, vuln_id: str) -> Optional[VulnerabilityReport]:
+        """Get a vulnerability report by ID."""
+        return self._reports.get(vuln_id)
+    
+    def get_all_reports(
+        self,
+        status: Optional[VulnStatus] = None,
+        severity: Optional[Severity] = None
+    ) -> list[VulnerabilityReport]:
+        """Get all reports, optionally filtered."""
+        reports = list(self._reports.values())
+        
+        if status:
+            reports = [r for r in reports if r.status == status]
+        
+        if severity:
+            reports = [r for r in reports if r.severity == severity]
+        
+        return reports
+    
+    def get_confirmed_vulns(self) -> list[VulnerabilityReport]:
+        """Get all confirmed vulnerabilities."""
+        return [
+            r for r in self._reports.values()
+            if r.status in [VulnStatus.CONFIRMED, VulnStatus.EXPLOITABLE]
+        ]
+    
+    def generate_summary(self) -> dict[str, Any]:
+        """Generate a summary of all findings."""
+        all_reports = list(self._reports.values())
+        
+        summary = {
+            "total": len(all_reports),
+            "by_status": {},
+            "by_severity": {},
+            "by_type": {},
+            "critical_count": 0,
+            "high_count": 0,
+        }
+        
+        for report in all_reports:
+            # By status
+            status_key = report.status.value
+            summary["by_status"][status_key] = summary["by_status"].get(status_key, 0) + 1
+            
+            # By severity
+            sev_key = report.severity.value
+            summary["by_severity"][sev_key] = summary["by_severity"].get(sev_key, 0) + 1
+            
+            # By type
+            summary["by_type"][report.vuln_type] = summary["by_type"].get(report.vuln_type, 0) + 1
+            
+            # Critical/High counts
+            if report.severity == Severity.CRITICAL:
+                summary["critical_count"] += 1
+            elif report.severity == Severity.HIGH:
+                summary["high_count"] += 1
+        
+        return summary
+    
+    def clear_reports(self):
+        """Clear all reports."""
+        self._reports.clear()
+
+
+# Global instance
+_validator: Optional[VulnValidator] = None
+
+
+def get_vuln_validator() -> VulnValidator:
+    """Get or create the global validator instance."""
+    global _validator
+    if _validator is None:
+        _validator = VulnValidator()
+    return _validator
+
+
+def create_vuln_report(
+    vuln_type: str,
+    url: str,
+    parameter: str,
+    payload: str,
+    evidence: str
+) -> VulnerabilityReport:
+    """Convenience function to create a vulnerability report."""
+    validator = get_vuln_validator()
+    return validator.create_report(vuln_type, url, parameter, payload, evidence)