From d142732519743cf0f68a588165016f39ca94c202 Mon Sep 17 00:00:00 2001 From: bhumi bhati Date: Sun, 24 May 2026 16:18:50 +0530 Subject: [PATCH 1/2] feat: implement contract validation and auto-generate api documentation examples --- docs/api_examples/health_check_200.json | 9 + docs/api_examples/list_plugins_200.json | 1109 +++++++++++++++++ .../missing_consent_error_400.json | 3 + .../missing_plugin_error_404.json | 3 + docs/api_examples/plugin_summary_200.json | 8 + docs/api_examples/start_task_result_200.json | 102 ++ docs/api_examples/start_task_submit_200.json | 6 + testing/backend/conftest.py | 25 + testing/backend/integration/test_routes.py | 23 +- 9 files changed, 1278 insertions(+), 10 deletions(-) create mode 100644 docs/api_examples/health_check_200.json create mode 100644 docs/api_examples/list_plugins_200.json create mode 100644 docs/api_examples/missing_consent_error_400.json create mode 100644 docs/api_examples/missing_plugin_error_404.json create mode 100644 docs/api_examples/plugin_summary_200.json create mode 100644 docs/api_examples/start_task_result_200.json create mode 100644 docs/api_examples/start_task_submit_200.json diff --git a/docs/api_examples/health_check_200.json b/docs/api_examples/health_check_200.json new file mode 100644 index 00000000..a44e3efd --- /dev/null +++ b/docs/api_examples/health_check_200.json @@ -0,0 +1,9 @@ +{ + "status": "operational", + "version": "0.1.0-alpha", + "system": { + "platform": "Windows", + "python_version": "3.13.7", + "docker_available": false + } +} \ No newline at end of file diff --git a/docs/api_examples/list_plugins_200.json b/docs/api_examples/list_plugins_200.json new file mode 100644 index 00000000..0d657010 --- /dev/null +++ b/docs/api_examples/list_plugins_200.json @@ -0,0 +1,1109 @@ +{ + "plugins": [ + { + "id": "amass", + "name": "Amass", + "description": "Deep attack-surface mapping and subdomain discovery.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "amass" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (amass). Install required tools locally to enable this scanner." + } + }, + { + "id": "api_scanner", + "name": "API Scanner", + "description": "Check for specific API vulnerabilities (REST and GraphQL).", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "API vulnerability scanning is active and requires authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nuclei" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nuclei). Install required tools locally to enable this scanner." + } + }, + { + "id": "cloud_scanner", + "name": "Cloud Scanner", + "description": "Cloud infrastructure security (AWS/GCP/Azure).", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Cloud scanning requires explicit account-level authorization.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "cloud_storage_auditor", + "name": "S3 / Blob Auditor", + "description": "Find misconfigured S3 buckets and exposed cloud storage.", + "category": "vulnerability", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Cloud storage auditing should be scoped to authorized assets.", + "availability": { + "runnable": false, + "missing_binaries": [ + "uncover" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (uncover). Install required tools locally to enable this scanner." + } + }, + { + "id": "code_analyzer", + "name": "Code Analyzer (Bandit)", + "description": "Static analysis for Python code", + "category": "code", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udcc3", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "bandit" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (bandit). Install required tools locally to enable this scanner." + } + }, + { + "id": "container_scanner", + "name": "Container Scan (Trivy)", + "description": "Scan Docker images and registries for known vulnerabilities", + "category": "network", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udce6", + "requires_consent": false, + "consent_message": "Scanning public container images is safe and passive.", + "availability": { + "runnable": false, + "missing_binaries": [ + "trivy" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (trivy). Install required tools locally to enable this scanner." + } + }, + { + "id": "crawler", + "name": "Crawler", + "description": "Recursive web crawler for link discovery.", + "category": "robots", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Crawler sends active traffic and requires authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "katana" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (katana). Install required tools locally to enable this scanner." + } + }, + { + "id": "dir_discovery", + "name": "Directory Discovery", + "description": "Discover hidden directories and files on web servers", + "category": "web", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udcc2", + "requires_consent": true, + "consent_message": "Directory brute-forcing generates significant traffic and may trigger rate limiting or security alerts. Only scan authorized targets.", + "availability": { + "runnable": false, + "missing_binaries": [ + "ffuf" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (ffuf). Install required tools locally to enable this scanner." + } + }, + { + "id": "dnsx", + "name": "dnsx", + "description": "DNS resolution and wildcard-aware validation at scale.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "dnsx" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (dnsx). Install required tools locally to enable this scanner." + } + }, + { + "id": "dns_enum", + "name": "DNS Reconnaissance", + "description": "Enumerate DNS records and configurations", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udce6", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "dnsrecon" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (dnsrecon). Install required tools locally to enable this scanner." + } + }, + { + "id": "domain-finder", + "name": "Domain Finder", + "description": "Discover additional domain names of target organization.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "amass" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (amass). Install required tools locally to enable this scanner." + } + }, + { + "id": "droopescan", + "name": "Drupal Security Scan", + "description": "Drupal-focused CMS scanner for version and surface enumeration.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee1\ufe0f", + "requires_consent": true, + "consent_message": "Droopescan performs active CMS probing and should be used with authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "droopescan" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (droopescan). Install required tools locally to enable this scanner." + } + }, + { + "id": "fuzzer", + "name": "Payload Fuzzer", + "description": "Autonomously fuzz target fields with massive dictionaries.", + "category": "robots", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Payload fuzzing is aggressive and must be authorized.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "google-dorking", + "name": "Google Hacking", + "description": "Find publicly indexed information about target.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "hashcat", + "name": "Password Recovery Audit", + "description": "Password recovery and hash audit workflow.", + "category": "expert", + "safety_level": "exploit", + "enabled": true, + "icon": "\u26a1", + "requires_consent": true, + "consent_message": "Hashcat performs offensive-style password recovery. Use only for authorized assessments.", + "availability": { + "runnable": false, + "missing_binaries": [ + "hashcat" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (hashcat). Install required tools locally to enable this scanner." + } + }, + { + "id": "httpx", + "name": "httpx", + "description": "Live host probing with status, title, and technology fingerprinting.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "http_inspector", + "name": "HTTP Inspector", + "description": "Inspect HTTP/HTTPS endpoints for headers, cookies, and TLS configuration", + "category": "web", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83c\udf10", + "requires_consent": true, + "consent_message": "This tool will make HTTP requests to the target URL.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "http_request_logger", + "name": "HTTP Request Logger", + "description": "Handle incoming HTTP requests and record data.", + "category": "exploit", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Active request logging should only be run in authorized scope.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "iac_scanner", + "name": "IaC Scanner (Checkov)", + "description": "Analyze Terraform and CloudFormation code for flaws.", + "category": "vulnerability", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "icmp_ping", + "name": "ICMP Ping", + "description": "Check if a server is live and responds to ICMP Echo requests.", + "category": "utils", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "joomscan", + "name": "Joomla Security Scan", + "description": "Joomla security scanner for version and common weakness discovery.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83c\udff7\ufe0f", + "requires_consent": true, + "consent_message": "JoomScan runs active checks and should only be used on authorized targets.", + "availability": { + "runnable": false, + "missing_binaries": [ + "joomscan" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (joomscan). Install required tools locally to enable this scanner." + } + }, + { + "id": "katana", + "name": "Katana", + "description": "Web crawling for endpoint and route discovery.", + "category": "recon", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": true, + "consent_message": "Crawler generates active traffic. Ensure authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "katana" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (katana). Install required tools locally to enable this scanner." + } + }, + { + "id": "kubernetes_scanner", + "name": "K8s Scanner", + "description": "Kubernetes cluster security assessment.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Kubernetes assessments require cluster owner authorization.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "metasploit", + "name": "Exploitation Connector", + "description": "Metasploit connector for controlled exploit-module execution.", + "category": "expert", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\ude80", + "requires_consent": true, + "consent_message": "Metasploit can launch exploit payloads. Explicit authorization is mandatory.", + "availability": { + "runnable": false, + "missing_binaries": [ + "msfconsole" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (msfconsole). Install required tools locally to enable this scanner." + } + }, + { + "id": "network_scanner", + "name": "Network Scanner", + "description": "Check for 10,000+ CVEs and server misconfigurations.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Network scanning is active probing and must be authorized.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nmap" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nmap). Install required tools locally to enable this scanner." + } + }, + { + "id": "nikto", + "name": "Nikto", + "description": "Web server vulnerability scanner powered by the Nikto CLI", + "category": "web", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": true, + "consent_message": "Nikto sends active web probes and can trigger security monitoring. Only scan targets where you have explicit authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nikto" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nikto). Install required tools locally to enable this scanner." + } + }, + { + "id": "nmap", + "name": "Network Scanning", + "description": "Network discovery and port scanning tool", + "category": "network", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0d", + "requires_consent": true, + "consent_message": "Port scanning may trigger IDS/IPS alerts. Only scan authorized targets.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nmap" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nmap). Install required tools locally to enable this scanner." + } + }, + { + "id": "nuclei", + "name": "Template Vulnerability Scan", + "description": "Fast and customizable vulnerability scanner", + "category": "web", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83e\uddec", + "requires_consent": true, + "consent_message": "Nuclei will send hundreds of payloads looking for known vulnerabilities. Proceed with caution.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nuclei" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nuclei). Install required tools locally to enable this scanner." + } + }, + { + "id": "password_auditor", + "name": "Password Auditor", + "description": "Discover weak credentials in network services and web apps.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Credential auditing requires explicit permission.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "people-email-discovery", + "name": "People Hunter", + "description": "Discover email addresses and social media profiles.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "theHarvester" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (theHarvester). Install required tools locally to enable this scanner." + } + }, + { + "id": "port-scanner", + "name": "Port Scanner", + "description": "Detect open ports and fingerprint services.", + "category": "recon", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": true, + "consent_message": "Port scanning is active probing. Ensure authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nmap" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nmap). Install required tools locally to enable this scanner." + } + }, + { + "id": "scapy_recon", + "name": "Advanced Network Recon", + "description": "Advanced network probing using Scapy", + "category": "network", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udce1", + "requires_consent": true, + "consent_message": "Scapy requires elevated privileges for raw sockets. Ensure you have authorization to scan this network.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "secret_scanner", + "name": "Secret Scanner", + "description": "Scan directories for hardcoded secrets", + "category": "code", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd11", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "gitleaks" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (gitleaks). Install required tools locally to enable this scanner." + } + }, + { + "id": "sharepoint_scanner", + "name": "Sharepoint Scanner", + "description": "Check SharePoint for security issues, misconfigs, and more.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "SharePoint scanning requires explicit permission.", + "availability": { + "runnable": false, + "missing_binaries": [ + "nuclei" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (nuclei). Install required tools locally to enable this scanner." + } + }, + { + "id": "sitemap_gen", + "name": "Sitemap Generator", + "description": "Build complete XML sitemaps by autonomously parsing targets.", + "category": "robots", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Sitemap generation crawls target resources actively.", + "availability": { + "runnable": false, + "missing_binaries": [ + "katana" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (katana). Install required tools locally to enable this scanner." + } + }, + { + "id": "sniper", + "name": "Sniper: Auto-Exploiter", + "description": "Validate critical CVEs by automatic exploitation.", + "category": "exploit", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Sniper models exploit flows. Use only with explicit authorization.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "spider", + "name": "Spider", + "description": "Advanced web spider with JS execution support.", + "category": "robots", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Spidering with JS support is active reconnaissance.", + "availability": { + "runnable": false, + "missing_binaries": [ + "katana" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (katana). Install required tools locally to enable this scanner." + } + }, + { + "id": "sqli_checker", + "name": "SQL Injection Feasibility", + "description": "SQL injection feasibility scanner powered by Ghauri.", + "category": "expert", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83e\uddea", + "requires_consent": true, + "consent_message": "SQLi checks actively probe injection vectors. Use only with authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "ghauri" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (ghauri). Install required tools locally to enable this scanner." + } + }, + { + "id": "sqli_exploiter", + "name": "SQLi Exploiter", + "description": "Exploit SQL injection in web apps to extract data.", + "category": "exploit", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "SQLi exploitation is high risk and must be explicitly authorized.", + "availability": { + "runnable": false, + "missing_binaries": [ + "sqlmap" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (sqlmap). Install required tools locally to enable this scanner." + } + }, + { + "id": "sqlmap", + "name": "SQL Injection Testing", + "description": "Automatic SQL injection and database takeover tool", + "category": "web", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\udc89", + "requires_consent": true, + "consent_message": "SQL injection attacks are highly intrusive and modify database states. ONLY run this against systems you own.", + "availability": { + "runnable": false, + "missing_binaries": [ + "sqlmap" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (sqlmap). Install required tools locally to enable this scanner." + } + }, + { + "id": "ssh_runner", + "name": "SSH Runner", + "description": "Remote command execution via SSH", + "category": "execution", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udda5\ufe0f", + "requires_consent": true, + "consent_message": "SSH execution can be dangerous. Ensure you are using authorized credentials and non-destructive commands.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "subdomain-finder", + "name": "Subdomain Finder", + "description": "Discover subdomains of a domain.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "subfinder" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (subfinder). Install required tools locally to enable this scanner." + } + }, + { + "id": "subdomain_discovery", + "name": "Subdomain Scanner", + "description": "Enumerate subdomains using passive sources", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83c\udf10", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "subfinder" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (subfinder). Install required tools locally to enable this scanner." + } + }, + { + "id": "subdomain_takeover", + "name": "Subdomain Takeover", + "description": "Discover dangling DNS entries pointing to external services.", + "category": "exploit", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "Subdomain takeover checks may touch third-party hosted endpoints.", + "availability": { + "runnable": false, + "missing_binaries": [ + "subfinder" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (subfinder). Install required tools locally to enable this scanner." + } + }, + { + "id": "subfinder", + "name": "Subfinder", + "description": "Fast passive subdomain enumeration.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "subfinder" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (subfinder). Install required tools locally to enable this scanner." + } + }, + { + "id": "theharvester", + "name": "theHarvester", + "description": "OSINT collection for emails, domains, and hosts.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "theHarvester" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (theHarvester). Install required tools locally to enable this scanner." + } + }, + { + "id": "tls_inspector", + "name": "TLS Security Analysis", + "description": "Examine TLS/SSL certificates and cipher configurations", + "category": "security", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd10", + "requires_consent": true, + "consent_message": "This tool will connect to the target server to inspect TLS configuration.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "uncover", + "name": "Uncover", + "description": "Discover internet-exposed assets from external search sources.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "uncover" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (uncover). Install required tools locally to enable this scanner." + } + }, + { + "id": "url-fuzzer-2", + "name": "URL Fuzzer", + "description": "Discover hidden files and directories.", + "category": "recon", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": true, + "consent_message": "URL fuzzing sends many active requests. Ensure authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "ffuf" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (ffuf). Install required tools locally to enable this scanner." + } + }, + { + "id": "urlfinder", + "name": "urlfinder", + "description": "Passive historical URL collection.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "urlfinder" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (urlfinder). Install required tools locally to enable this scanner." + } + }, + { + "id": "virtual-host-finder", + "name": "Virtual Hosts Finder", + "description": "Find multiple websites hosted on the same server.", + "category": "recon", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": true, + "consent_message": "Virtual host probing is active scanning. Ensure authorization.", + "availability": { + "runnable": false, + "missing_binaries": [ + "ffuf" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (ffuf). Install required tools locally to enable this scanner." + } + }, + { + "id": "volatility", + "name": "Volatility", + "description": "Memory forensics workflow using Volatility 3 plugins.", + "category": "forensics", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83e\udde0", + "requires_consent": true, + "consent_message": "Memory forensics can expose sensitive in-memory data. Authorized handling is required.", + "availability": { + "runnable": false, + "missing_binaries": [ + "volatility3" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (volatility3). Install required tools locally to enable this scanner." + } + }, + { + "id": "waf-detection", + "name": "WAF Detector", + "description": "Fingerprint the Web Application Firewall behind target app.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "wafw00f" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (wafw00f). Install required tools locally to enable this scanner." + } + }, + { + "id": "waf_detector", + "name": "WAF Detector", + "description": "Automatically identify Web Application Firewalls protecting targets.", + "category": "robots", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": false, + "missing_binaries": [ + "wafw00f" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (wafw00f). Install required tools locally to enable this scanner." + } + }, + { + "id": "website-recon-2", + "name": "Website Recon", + "description": "Fingerprint web technologies of target website.", + "category": "recon", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "whois_lookup", + "name": "Domain Registration Lookup", + "description": "Domain registration information lookup", + "category": "utils", + "safety_level": "safe", + "enabled": true, + "icon": "\ud83d\udd0e", + "requires_consent": false, + "consent_message": null, + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "wpscan", + "name": "WordPress Security Scan", + "description": "WordPress security scanner for plugin, theme, and core risk visibility.", + "category": "vulnerability", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udcdd", + "requires_consent": true, + "consent_message": "WPScan performs active probing of the target WordPress instance.", + "availability": { + "runnable": false, + "missing_binaries": [ + "wpscan" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (wpscan). Install required tools locally to enable this scanner." + } + }, + { + "id": "xss_exploiter", + "name": "XSS Exploiter", + "description": "Exploit XSS in real life-attacks, extract cookies and data.", + "category": "exploit", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "XSS exploitation simulation requires explicit authorization.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + }, + { + "id": "yara_scan", + "name": "Binary Signature Scan", + "description": "Binary and file-system signature matching with YARA rules.", + "category": "forensics", + "safety_level": "intrusive", + "enabled": true, + "icon": "\ud83d\udd2c", + "requires_consent": true, + "consent_message": "YARA can process sensitive binaries/artifacts. Ensure approved forensic scope.", + "availability": { + "runnable": false, + "missing_binaries": [ + "yara" + ], + "status": "unavailable", + "guidance": "Unavailable: Requires external binaries (yara). Install required tools locally to enable this scanner." + } + }, + { + "id": "zap_scanner", + "name": "DAST Web Proxy (ZAP)", + "description": "Dynamic proxy spidering and payload injection.", + "category": "vulnerability", + "safety_level": "exploit", + "enabled": true, + "icon": "\ud83d\udee0\ufe0f", + "requires_consent": true, + "consent_message": "DAST payload injection should only run in authorized environments.", + "availability": { + "runnable": true, + "missing_binaries": [], + "status": "available", + "guidance": null + } + } + ], + "total": 60 +} \ No newline at end of file diff --git a/docs/api_examples/missing_consent_error_400.json b/docs/api_examples/missing_consent_error_400.json new file mode 100644 index 00000000..cef582af --- /dev/null +++ b/docs/api_examples/missing_consent_error_400.json @@ -0,0 +1,3 @@ +{ + "detail": "Consent required. You must acknowledge the legal notice." +} \ No newline at end of file diff --git a/docs/api_examples/missing_plugin_error_404.json b/docs/api_examples/missing_plugin_error_404.json new file mode 100644 index 00000000..6cee79f4 --- /dev/null +++ b/docs/api_examples/missing_plugin_error_404.json @@ -0,0 +1,3 @@ +{ + "detail": "Plugin not found: plugin_does_not_exist_123" +} \ No newline at end of file diff --git a/docs/api_examples/plugin_summary_200.json b/docs/api_examples/plugin_summary_200.json new file mode 100644 index 00000000..5640e54e --- /dev/null +++ b/docs/api_examples/plugin_summary_200.json @@ -0,0 +1,8 @@ +{ + "total_plugins": 60, + "runnable_count": 18, + "unavailable_count": 42, + "category_counts": { + "unknown": 60 + } +} \ No newline at end of file diff --git a/docs/api_examples/start_task_result_200.json b/docs/api_examples/start_task_result_200.json new file mode 100644 index 00000000..6379b3da --- /dev/null +++ b/docs/api_examples/start_task_result_200.json @@ -0,0 +1,102 @@ +{ + "task_id": "87244a27-cdf2-4209-ae97-0e8d354b24ab", + "plugin_id": "http_inspector", + "tool": "HTTP Inspector", + "target": "http://127.0.0.1:8000", + "timestamp": "2026-05-24 10:32:54", + "duration_seconds": 7.414817810058594e-05, + "status": "completed", + "preset": "quick", + "inputs": { + "follow_redirects": false, + "timeout": 5, + "url": "http://127.0.0.1:8000" + }, + "summary": [ + "Assessment identified 4 minor observations; no critical or high-severity threats were found." + ], + "severity_counts": { + "medium": 4 + }, + "findings": [ + { + "title": "Missing X-Frame-Options Header", + "category": "Security Headers", + "severity": "medium", + "description": "The lack of X-Frame-Options makes the site vulnerable to clickjacking.", + "remediation": "Implement the x-frame-options header in the web server configuration.", + "metadata": {} + }, + { + "title": "Missing X-Content-Type-Options Header", + "category": "Security Headers", + "severity": "medium", + "description": "Without this header set to 'nosniff', the browser may try to MIME-sniff the content, potentially executing malicious code.", + "remediation": "Implement the x-content-type-options header in the web server configuration.", + "metadata": {} + }, + { + "title": "Missing Content-Security-Policy Header", + "category": "Security Headers", + "severity": "medium", + "description": "CSP helps mitigate XSS and other injection attacks. It is currently missing.", + "remediation": "Implement the content-security-policy header in the web server configuration.", + "metadata": {} + }, + { + "title": "Missing Strict-Transport-Security Header", + "category": "Security Headers", + "severity": "medium", + "description": "HSTS should be enabled to force HTTPS connections.", + "remediation": "Implement the strict-transport-security header in the web server configuration.", + "metadata": {} + } + ], + "structured": { + "findings": [ + { + "title": "Missing X-Frame-Options Header", + "category": "Security Headers", + "severity": "medium", + "description": "The lack of X-Frame-Options makes the site vulnerable to clickjacking.", + "remediation": "Implement the x-frame-options header in the web server configuration.", + "metadata": {} + }, + { + "title": "Missing X-Content-Type-Options Header", + "category": "Security Headers", + "severity": "medium", + "description": "Without this header set to 'nosniff', the browser may try to MIME-sniff the content, potentially executing malicious code.", + "remediation": "Implement the x-content-type-options header in the web server configuration.", + "metadata": {} + }, + { + "title": "Missing Content-Security-Policy Header", + "category": "Security Headers", + "severity": "medium", + "description": "CSP helps mitigate XSS and other injection attacks. It is currently missing.", + "remediation": "Implement the content-security-policy header in the web server configuration.", + "metadata": {} + }, + { + "title": "Missing Strict-Transport-Security Header", + "category": "Security Headers", + "severity": "medium", + "description": "HSTS should be enabled to force HTTPS connections.", + "remediation": "Implement the strict-transport-security header in the web server configuration.", + "metadata": {} + } + ], + "technologies": [], + "headers": {}, + "count": 4 + }, + "raw_output_path": "C:\\Users\\shanu\\AppData\\Local\\Temp\\tmppv_bkwr1\\raw\\87244a27-cdf2-4209-ae97-0e8d354b24ab.txt", + "raw_output_excerpt": "Mocked successful output", + "raw_output": "Mocked successful output", + "command_used": "curl -i -L --max-time 5 http://127.0.0.1:8000", + "errors": [], + "error_message": null, + "exit_code": 0, + "metadata": {} +} \ No newline at end of file diff --git a/docs/api_examples/start_task_submit_200.json b/docs/api_examples/start_task_submit_200.json new file mode 100644 index 00000000..f49690d4 --- /dev/null +++ b/docs/api_examples/start_task_submit_200.json @@ -0,0 +1,6 @@ +{ + "task_id": "87244a27-cdf2-4209-ae97-0e8d354b24ab", + "status": "queued", + "created_at": "now", + "stream_url": "/api/v1/task/87244a27-cdf2-4209-ae97-0e8d354b24ab/stream" +} \ No newline at end of file diff --git a/testing/backend/conftest.py b/testing/backend/conftest.py index 4805de89..2dffc7cb 100644 --- a/testing/backend/conftest.py +++ b/testing/backend/conftest.py @@ -61,3 +61,28 @@ async def teardown(): await database_module.db.disconnect() asyncio.run(teardown()) + +import json +import os +from pathlib import Path + +DOCS_DIR = Path(__file__).resolve().parents[2] / "docs" / "api_examples" + +@pytest.fixture +def validate_contract(): + def _validate(endpoint_name, response): + os.makedirs(DOCS_DIR, exist_ok=True) + file_path = DOCS_DIR / f"{endpoint_name}_{response.status_code}.json" + + actual_data = response.json() + + if file_path.exists(): + with open(file_path, "r") as f: + expected_data = json.load(f) + assert actual_data.keys() == expected_data.keys(), f"API docs mismatch for {endpoint_name}!" + + else: + with open(file_path, "w") as f: + json.dump(actual_data, f, indent=2) + + return _validate diff --git a/testing/backend/integration/test_routes.py b/testing/backend/integration/test_routes.py index c390327a..ce01ce48 100644 --- a/testing/backend/integration/test_routes.py +++ b/testing/backend/integration/test_routes.py @@ -4,16 +4,16 @@ from backend.secuscan.models import TaskStatus -def test_health_check(test_client): +def test_health_check(test_client,validate_contract): """Test health check endpoint.""" response = test_client.get("/api/v1/health") assert response.status_code == 200 data = response.json() assert data["status"] == "operational" assert "version" in data + validate_contract("health_check",response) - -def test_list_plugins(test_client): +def test_list_plugins(test_client,validate_contract): """Test plugins list endpoint.""" response = test_client.get("/api/v1/plugins") assert response.status_code == 200 @@ -27,8 +27,9 @@ def test_list_plugins(test_client): assert "availability" in first assert "runnable" in first["availability"] assert "missing_binaries" in first["availability"] + validate_contract("list_plugins",response) -def test_plugin_summary(test_client): +def test_plugin_summary(test_client ,validate_contract): """Test plugin summary endpoint.""" response = test_client.get("/api/v1/plugins/summary") @@ -41,7 +42,7 @@ def test_plugin_summary(test_client): assert "runnable_count" in data assert "unavailable_count" in data assert "category_counts" in data - + validate_contract("plugin_summary",response) assert isinstance(data["total_plugins"], int) assert isinstance(data["runnable_count"], int) assert isinstance(data["unavailable_count"], int) @@ -52,7 +53,7 @@ def test_plugin_summary(test_client): ) == data["total_plugins"] -def test_start_task(test_client): +def test_start_task(test_client,validate_contract): """Test starting a task with a mocked executor.""" with patch("backend.secuscan.executor.TaskExecutor._execute_command") as mock_exec: mock_exec.return_value = ("Mocked successful output", 0) @@ -66,6 +67,7 @@ def test_start_task(test_client): response = test_client.post("/api/v1/task/start", json=payload) assert response.status_code == 200 + validate_contract("start_task_submit",response) data = response.json() assert "task_id" in data assert data["status"] == "queued" @@ -82,17 +84,18 @@ def test_start_task(test_client): assert result_response.status_code == 200 result_data = result_response.json() assert "Mocked successful output" in result_data["raw_output_excerpt"] + validate_contract("start_task_result",result_response) -def test_missing_consent(test_client): +def test_missing_consent(test_client,validate_contract): """Test starting a task without consent.""" payload = { "plugin_id": "http_inspector", "inputs": {"url": "http://127.0.0.1:8000"}, "consent_granted": False, } - response = test_client.post("/api/v1/task/start", json=payload) + validate_contract("missing_consent_error",response) assert response.status_code == 400 assert "Consent required" in response.json()["detail"] @@ -106,7 +109,7 @@ def test_get_settings(test_client): assert "sandbox" in data assert "safety" in data -def test_start_task_missing_plugin(test_client): +def test_start_task_missing_plugin(test_client,validate_contract): """Starting a task with a missing plugin should return 404 and helpful detail.""" missing_id = "plugin_does_not_exist_123" payload = { @@ -114,8 +117,8 @@ def test_start_task_missing_plugin(test_client): "inputs": {"url": "http://127.0.0.1:8000"}, "consent_granted": True, } - response = test_client.post("/api/v1/task/start", json=payload) + validate_contract("missing_plugin_error",response) assert response.status_code == 404 detail = response.json().get("detail", "") assert missing_id in detail or "plugin" in detail.lower() \ No newline at end of file From 0c97c56a2d92b113601b7b503b9942bf697144ab Mon Sep 17 00:00:00 2001 From: bhumi bhati Date: Sun, 24 May 2026 16:58:43 +0530 Subject: [PATCH 2/2] fix:remove trailing whitespace --- testing/backend/conftest.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/testing/backend/conftest.py b/testing/backend/conftest.py index 2dffc7cb..e7790416 100644 --- a/testing/backend/conftest.py +++ b/testing/backend/conftest.py @@ -73,16 +73,12 @@ def validate_contract(): def _validate(endpoint_name, response): os.makedirs(DOCS_DIR, exist_ok=True) file_path = DOCS_DIR / f"{endpoint_name}_{response.status_code}.json" - actual_data = response.json() - if file_path.exists(): with open(file_path, "r") as f: expected_data = json.load(f) assert actual_data.keys() == expected_data.keys(), f"API docs mismatch for {endpoint_name}!" - else: with open(file_path, "w") as f: json.dump(actual_data, f, indent=2) - - return _validate + return _validate \ No newline at end of file