pandoraspec 0.2.0__tar.gz

pandoraspec-0.2.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pandoraspec
+Version: 0.2.0
+Summary: DORA Compliance Auditor for OpenAPI Specs
+Author-email: Ulises Merlan <ulimerlan@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: schemathesis==4.9.1
+Requires-Dist: typer[all]
+Requires-Dist: rich
+Requires-Dist: weasyprint
+Requires-Dist: jinja2
+Requires-Dist: requests
+
+# PanDoraSpec
+
+**The Open DORA Compliance Engine for OpenAPI Specs.**
+
+PanDoraSpec is a CLI tool that performs deep technical due diligence on APIs to verify compliance with **DORA (Digital Operational Resilience Act)** requirements. It compares OpenAPI/Swagger specifications against real-world implementation to detect schema drift, resilience gaps, and security issues.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pandoraspec
+```
+
+### System Requirements
+The PDF report generation requires `weasyprint`, which depends on **Pango**.
+
+**macOS:**
+```bash
+brew install pango
+```
+
+**Debian / Ubuntu:**
+```bash
+sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0
+```
+
+## 🛠️ Development Setup
+
+To run the CLI locally without reinstalling after every change:
+
+1. **Clone & CD**:
+```bash
+git clone ...
+cd pandoraspec
+```
+
+2. **Create & Activate Virtual Environment**:
+It's recommended to use a virtual environment to keep dependencies isolated.
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. **Editable Install**:
+```bash
+pip install -e .
+```
+This links the `pandoraspec` command directly to your source code. Any changes you make will be reflected immediately.
+
+## 🚀 Usage
+
+Run the audit directly from your terminal.
+
+### Basic Scan
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json
+```
+
+### With Options
+```bash
+pandoraspec https://api.example.com/spec.json --vendor "Stripe" --key "sk_live_..."
+```
+
+### Local File
+```bash
+pandoraspec ./openapi.yaml
+```
+
+---
+
+## 🏎️ Zero-Config Testing (DORA Compliance)
+
+For standard **DORA compliance**, you simply need to verify that your API implementation matches its specification. **No configuration is required.**
+
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json
+```
+
+This runs a **fuzzing** audit where random data is generated based on your schema types (e.g., sending random integers for IDs). 
+- **Value:** This is sufficient to prove that your API correctly handles unexpected inputs and adheres to the basic contract (e.g., returning 400 Bad Request instead of 500 Server Error).
+- **Limitation:** Detailed business logic requiring valid IDs (e.g., `GET /user/{id}` where `{id}` must exist) may return `404 Not Found`. This is acceptable for a compliance scan but may not fully exercise deeper code paths.
+
+---
+
+## 🧠 Advanced Testing with Seed Data
+
+To test **specific business workflows** (e.g., successfully retrieving a user profile), you can provide "Seed Data". This tells PanDoraSpec to use known, valid values instead of random fuzzing data.
+
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json --config seed_parameters.yaml
+```
+
+### Configuration Hierarchy
+You can define seed values at three levels of specificity. The engine resolves values in this order: **Endpoints > Verbs > General**.
+
+```yaml
+seed_data:
+  # 1. General: Applies to EVERYTHING (path params, query params, headers)
+  general:
+    username: "test_user"
+    limit: 50
+
+  # 2. Verbs: Applies only to specific HTTP methods (Overwrites General)
+  verbs:
+    POST:
+      username: "admin_user" # Creation requests use a different user
+
+  # 3. Endpoints: Applies only to specific routes (Overwrites Everything)
+  endpoints:
+    /users/me:
+      GET:
+        limit: 10
+```
+
+### 🔗 Dynamic Seed Data (Chaining Requests)
+You can even test **dependency chains** where one endpoint requires data from another (e.g., get a User ID from a search result to query their profile).
+
+**Supported Features:**
+- **Dynamic Resolution:** Fetch a value from another API call before running the test.
+- **Extraction:** Extract values from JSON responses or plain text.
+- **Parameter Interpolation:** Use `{param}` in the dependency URL to chain multiple steps.
+
+```yaml
+endpoints:
+  /user/{username}:
+    GET:
+      username:
+        # 1. Fetch the user list first
+        # 2. Extract the 'username' field from the response
+        from_endpoint: "GET /users/search?role=admin"
+        extract: "data.items.0.username"
+
+  /orders/{orderId}:
+    GET:
+      orderId:
+        # 1. Use the {userId} from our general seeds
+        # 2. Call /users/{userId}/latest-order
+        # 3. Extract the ID using Regex from a message string
+        from_endpoint: "GET /users/{userId}/latest-order"
+        extract: "message"
+        regex: "Order ID: ([0-9]+)"
+```
+
+---
+
+## 🛡️ What It Checks
+
+### Module A: The Integrity Test (Drift)
+Checks if your API implementation matches your documentation.
+- **Why?** DORA requires you to monitor if the service effectively supports your critical functions. If the API behaves differently than documented, it's a risk.
+
+### Module B: The Resilience Test
+Stress tests the API to ensure it handles invalid inputs gracefully (`4xx` vs `5xx`).
+- **Why?** DORA Article 25 calls for "Digital operational resilience testing".
+
+### Module C: Security Hygiene
+Checks for common security headers and configurations.
+
+### Module D: The Report
+Generates a PDF report: **"DORA ICT Third-Party Technical Risk Assessment"**.
+
+---
+
+## 📄 License
+
+MIT

pandoraspec-0.2.0/README.md

@@ -0,0 +1,167 @@
+# PanDoraSpec
+
+**The Open DORA Compliance Engine for OpenAPI Specs.**
+
+PanDoraSpec is a CLI tool that performs deep technical due diligence on APIs to verify compliance with **DORA (Digital Operational Resilience Act)** requirements. It compares OpenAPI/Swagger specifications against real-world implementation to detect schema drift, resilience gaps, and security issues.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pandoraspec
+```
+
+### System Requirements
+The PDF report generation requires `weasyprint`, which depends on **Pango**.
+
+**macOS:**
+```bash
+brew install pango
+```
+
+**Debian / Ubuntu:**
+```bash
+sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0
+```
+
+## 🛠️ Development Setup
+
+To run the CLI locally without reinstalling after every change:
+
+1. **Clone & CD**:
+```bash
+git clone ...
+cd pandoraspec
+```
+
+2. **Create & Activate Virtual Environment**:
+It's recommended to use a virtual environment to keep dependencies isolated.
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. **Editable Install**:
+```bash
+pip install -e .
+```
+This links the `pandoraspec` command directly to your source code. Any changes you make will be reflected immediately.
+
+## 🚀 Usage
+
+Run the audit directly from your terminal.
+
+### Basic Scan
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json
+```
+
+### With Options
+```bash
+pandoraspec https://api.example.com/spec.json --vendor "Stripe" --key "sk_live_..."
+```
+
+### Local File
+```bash
+pandoraspec ./openapi.yaml
+```
+
+---
+
+## 🏎️ Zero-Config Testing (DORA Compliance)
+
+For standard **DORA compliance**, you simply need to verify that your API implementation matches its specification. **No configuration is required.**
+
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json
+```
+
+This runs a **fuzzing** audit where random data is generated based on your schema types (e.g., sending random integers for IDs). 
+- **Value:** This is sufficient to prove that your API correctly handles unexpected inputs and adheres to the basic contract (e.g., returning 400 Bad Request instead of 500 Server Error).
+- **Limitation:** Detailed business logic requiring valid IDs (e.g., `GET /user/{id}` where `{id}` must exist) may return `404 Not Found`. This is acceptable for a compliance scan but may not fully exercise deeper code paths.
+
+---
+
+## 🧠 Advanced Testing with Seed Data
+
+To test **specific business workflows** (e.g., successfully retrieving a user profile), you can provide "Seed Data". This tells PanDoraSpec to use known, valid values instead of random fuzzing data.
+
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json --config seed_parameters.yaml
+```
+
+### Configuration Hierarchy
+You can define seed values at three levels of specificity. The engine resolves values in this order: **Endpoints > Verbs > General**.
+
+```yaml
+seed_data:
+  # 1. General: Applies to EVERYTHING (path params, query params, headers)
+  general:
+    username: "test_user"
+    limit: 50
+
+  # 2. Verbs: Applies only to specific HTTP methods (Overwrites General)
+  verbs:
+    POST:
+      username: "admin_user" # Creation requests use a different user
+
+  # 3. Endpoints: Applies only to specific routes (Overwrites Everything)
+  endpoints:
+    /users/me:
+      GET:
+        limit: 10
+```
+
+### 🔗 Dynamic Seed Data (Chaining Requests)
+You can even test **dependency chains** where one endpoint requires data from another (e.g., get a User ID from a search result to query their profile).
+
+**Supported Features:**
+- **Dynamic Resolution:** Fetch a value from another API call before running the test.
+- **Extraction:** Extract values from JSON responses or plain text.
+- **Parameter Interpolation:** Use `{param}` in the dependency URL to chain multiple steps.
+
+```yaml
+endpoints:
+  /user/{username}:
+    GET:
+      username:
+        # 1. Fetch the user list first
+        # 2. Extract the 'username' field from the response
+        from_endpoint: "GET /users/search?role=admin"
+        extract: "data.items.0.username"
+
+  /orders/{orderId}:
+    GET:
+      orderId:
+        # 1. Use the {userId} from our general seeds
+        # 2. Call /users/{userId}/latest-order
+        # 3. Extract the ID using Regex from a message string
+        from_endpoint: "GET /users/{userId}/latest-order"
+        extract: "message"
+        regex: "Order ID: ([0-9]+)"
+```
+
+---
+
+## 🛡️ What It Checks
+
+### Module A: The Integrity Test (Drift)
+Checks if your API implementation matches your documentation.
+- **Why?** DORA requires you to monitor if the service effectively supports your critical functions. If the API behaves differently than documented, it's a risk.
+
+### Module B: The Resilience Test
+Stress tests the API to ensure it handles invalid inputs gracefully (`4xx` vs `5xx`).
+- **Why?** DORA Article 25 calls for "Digital operational resilience testing".
+
+### Module C: Security Hygiene
+Checks for common security headers and configurations.
+
+### Module D: The Report
+Generates a PDF report: **"DORA ICT Third-Party Technical Risk Assessment"**.
+
+---
+
+## 📄 License
+
+MIT

pandoraspec-0.2.0/pandoraspec/cli.py

@@ -0,0 +1,85 @@
+import typer
+import yaml
+import os
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from .core import AuditEngine
+from .reporting import generate_report
+
+app = typer.Typer(help="DORA Audit CLI - Verify Compliance of OpenAI Specs")
+console = Console()
+
+def load_config(config_path: str):
+    if os.path.exists(config_path):
+        with open(config_path, "r") as f:
+            return yaml.safe_load(f)
+    return {}
+
+def run_audit(
+    target: str = typer.Argument(..., help="URL or path to OpenAPI schema"),
+    api_key: str = typer.Option(None, "--key", "-k", help="API Key for authenticated endpoints"),
+    vendor: str = typer.Option("Vendor", "--vendor", "-v", help="Vendor name for the report"),
+    config: str = typer.Option(None, "--config", "-c", help="Path to .yaml configuration file")
+):
+    """
+    Run a DORA audit against an OpenAPI schema.
+    """
+    console.print(Panel(f"[bold blue]Starting DORA Audit for {vendor}[/bold blue]", border_style="blue"))
+    console.print(f"🔎 Scanning [bold]{target}[/bold]...")
+
+    # 1. Load Config
+    seed_data = {}
+    if config:
+        config_data = load_config(config)
+        seed_data = config_data.get("seed_data", {})
+        
+        if seed_data:
+            console.print(f"[green]Loaded {len(seed_data)} seed values from {config}[/green]")
+
+    try:
+        # 2. Pass seed_data to Engine
+        engine = AuditEngine(target=target, api_key=api_key, seed_data=seed_data)
+        
+        results = engine.run_full_audit()
+        
+        # Display Summary Table
+        table = Table(title="Audit Summary")
+        table.add_column("Module", style="cyan", no_wrap=True)
+        table.add_column("Status", style="bold")
+        table.add_column("Issues (Pass/Fail)", style="magenta")
+
+        # Drift
+        drift_pass = len([r for r in results["drift_check"] if r.get("status") == "PASS"])
+        drift_fail = len([r for r in results["drift_check"] if r.get("status") != "PASS"])
+        drift_status = "[bold red]FAIL[/bold red]" if drift_fail > 0 else "[bold green]PASS[/bold green]"
+        table.add_row("Module A: Integrity", drift_status, f"{drift_pass} / {drift_fail}")
+
+        # Resilience
+        res_pass = len([r for r in results["resilience"] if r.get("status") == "PASS"])
+        res_fail = len([r for r in results["resilience"] if r.get("status") != "PASS"])
+        res_status = "[bold red]FAIL[/bold red]" if res_fail > 0 else "[bold green]PASS[/bold green]"
+        table.add_row("Module B: Resilience", res_status, f"{res_pass} / {res_fail}")
+
+        # Security
+        sec_pass = len([r for r in results["security"] if r.get("status") == "PASS"])
+        sec_fail = len([r for r in results["security"] if r.get("status") != "PASS"])
+        sec_status = "[bold red]FAIL[/bold red]" if sec_fail > 0 else "[bold green]PASS[/bold green]"
+        table.add_row("Module C: Security", sec_status, f"{sec_pass} / {sec_fail}")
+
+        console.print(table)
+
+        # Generate Report
+        report_path = generate_report(vendor, results)
+        
+        console.print(Panel(f"[bold green]Audit Complete![/bold green]\n📄 Report generated: [link={report_path}]{report_path}[/link]", border_style="green"))
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {str(e)}")
+        raise typer.Exit(code=1)
+
+def main():
+    typer.run(run_audit)
+
+if __name__ == "__main__":
+    main()

pandoraspec-0.2.0/pandoraspec/core.py

@@ -0,0 +1,470 @@
+import schemathesis
+from typing import List, Dict, Any
+import requests
+import re
+from schemathesis import checks
+from schemathesis.specs.openapi import checks as oai_checks
+from schemathesis.checks import CheckContext, ChecksConfig
+import html
+import os
+
+class AuditEngine:
+    def __init__(self, target: str, api_key: str = None, seed_data: Dict[str, Any] = None):
+        self.target = target
+        self.api_key = api_key
+        self.seed_data = seed_data or {}
+        self.base_url = None
+        self.dynamic_cache = {} # Cache for dynamic seed values
+
+        try:
+            if os.path.exists(target) and os.path.isfile(target):
+                 print(f"DEBUG: Loading schema from local file: {target}")
+                 self.schema = schemathesis.openapi.from_path(target)
+            else:
+                 self.schema = schemathesis.openapi.from_url(target)
+            
+            # Priority 1: Extract from the 'servers' field in the spec
+            resolved_url = None
+            if hasattr(self.schema, "raw_schema"):
+                servers = self.schema.raw_schema.get("servers", [])
+                if servers and isinstance(servers, list) and len(servers) > 0:
+                    spec_server_url = servers[0].get("url")
+                    if spec_server_url:
+                        resolved_url = spec_server_url
+                        print(f"DEBUG: Found server URL in specification: {resolved_url}")
+            
+            # Priority 2: Use whatever schemathesis resolved automatically (fallback)
+            if not resolved_url:
+                resolved_url = getattr(self.schema, "base_url", None)
+                print(f"DEBUG: Falling back to Schemathesis resolved base_url: {resolved_url}")
+
+            if not resolved_url and self.target and not os.path.exists(self.target):
+                # Fallback: Derive from target URL (e.g., remove swagger.json)
+                try:
+                    from urllib.parse import urlparse, urlunparse
+                    parsed = urlparse(self.target)
+                    path_parts = parsed.path.split('/')
+                    # Simple heuristic: remove the last segment (e.g. swagger.json) to get base
+                    if '.' in path_parts[-1]: 
+                        path_parts.pop()
+                    new_path = '/'.join(path_parts)
+                    resolved_url = urlunparse(parsed._replace(path=new_path))
+                    print(f"DEBUG: Derived base_url from schema_url: {resolved_url}")
+                except Exception as e:
+                    print(f"DEBUG: Failed to derive base_url from schema_url: {e}")
+
+            print(f"DEBUG: Final resolved base_url for engine: {resolved_url}")
+            self.base_url = resolved_url
+            if resolved_url:
+                try:
+                    self.schema.base_url = resolved_url
+                except Exception:
+                        pass
+        except Exception as e:
+             # Handle invalid URL or schema loading error gracefully
+             print(f"Error loading schema: {e}")
+             if target and (target.startswith("http") or os.path.exists(target)):
+                pass # Allow to continue if it's just a warning, but schemathesis might fail later
+             else:
+                raise ValueError(f"Failed to load OpenAPI schema from {target}. Error: {str(e)}")
+
+    def _resolve_dynamic_value(self, config_value: Any) -> Any:
+        """Resolves dynamic seed values like `from_endpoint`"""
+        if not isinstance(config_value, dict) or "from_endpoint" not in config_value:
+            return config_value
+
+        endpoint_def = config_value["from_endpoint"]
+        if endpoint_def in self.dynamic_cache:
+            return self.dynamic_cache[endpoint_def]
+
+        try:
+            method, path = endpoint_def.split(" ", 1)
+            
+            # Interpolate path parameters (e.g., /user/{id}) from general seeds
+            if '{' in path:
+                general_seeds = self.seed_data.get('general', {})
+                
+                def replace_param(match):
+                    param_name = match.group(1)
+                    if param_name in general_seeds:
+                        return str(general_seeds[param_name])
+                    print(f"WARNING: Missing seed value for {{{param_name}}} in dynamic endpoint {endpoint_def}")
+                    return match.group(0) # Leave as is
+
+                path = re.sub(r"\{([a-zA-Z0-9_]+)\}", replace_param, path)
+
+            url = f"{self.base_url.rstrip('/')}/{path.lstrip('/')}"
+            
+            headers = {}
+            if self.api_key:
+                 auth_header = self.api_key if self.api_key.lower().startswith("bearer ") else f"Bearer {self.api_key}"
+                 headers["Authorization"] = auth_header
+
+            print(f"AUDIT LOG: Resolving dynamic seed from {method} {path}")
+            response = requests.request(method, url, headers=headers)
+            
+            if response.status_code >= 400:
+                print(f"WARNING: Dynamic seed request failed with {response.status_code}")
+                return None
+
+            result = None
+            extract_key = config_value.get("extract")
+            regex_pattern = config_value.get("regex")
+
+            # JSON Extraction
+            if extract_key:
+                try:
+                    json_data = response.json()
+                    # Simple key traversal for now (e.g. 'data.id')
+                    keys = extract_key.split('.')
+                    val = json_data
+                    for k in keys:
+                        if isinstance(val, dict):
+                            val = val.get(k)
+                        else:
+                            val = None
+                            break
+                    result = val
+                except Exception:
+                    print("WARNING: Failed to parse JSON or extract key")
+            else:
+                 # Default to text body
+                 result = response.text
+
+            # Regex Extraction
+            if regex_pattern and result is not None:
+                match = re.search(regex_pattern, str(result))
+                if match:
+                    # Return first group if exists, else the whole match
+                    result = match.group(1) if match.groups() else match.group(0)
+            
+            self.dynamic_cache[endpoint_def] = result
+            return result
+
+        except Exception as e:
+            print(f"ERROR: Failed to resolve dynamic seed: {e}")
+            return None
+
+    def _apply_seed_data(self, case):
+        """Helper to inject seed data into test cases with hierarchy: General < Verbs < Endpoints"""
+        if not self.seed_data:
+            return
+
+        # Determine if using hierarchical structure
+        is_hierarchical = any(k in self.seed_data for k in ['general', 'verbs', 'endpoints'])
+        
+        if is_hierarchical:
+            # 1. Start with General
+            merged_data = self.seed_data.get('general', {}).copy()
+            
+            # 2. Apply Verb-specific
+            if hasattr(case, 'operation'):
+                method = case.operation.method.upper()
+                path = case.operation.path
+                
+                verb_data = self.seed_data.get('verbs', {}).get(method, {})
+                merged_data.update(verb_data)
+                
+                # 3. Apply Endpoint-specific
+                # precise match on path template
+                endpoint_data = self.seed_data.get('endpoints', {}).get(path, {}).get(method, {})
+                merged_data.update(endpoint_data)
+        else:
+            # Legacy flat structure
+            merged_data = self.seed_data.copy() # Copy to avoid mutating original config
+
+        # Resolve dynamic values for the final merged dataset
+        resolved_data = {}
+        for k, v in merged_data.items():
+            resolved_val = self._resolve_dynamic_value(v)
+            if resolved_val is not None:
+                resolved_data[k] = resolved_val
+
+        # Inject into Path Parameters (e.g., /users/{userId})
+        if hasattr(case, 'path_parameters') and case.path_parameters:
+            for key in case.path_parameters:
+                if key in resolved_data:
+                    case.path_parameters[key] = resolved_data[key]
+
+        # Inject into Query Parameters (e.g., ?status=active)
+        if hasattr(case, 'query') and case.query:
+            for key in case.query:
+                if key in resolved_data:
+                    case.query[key] = resolved_data[key]
+                    
+        # Inject into Headers (e.g., X-Tenant-ID)
+        if hasattr(case, 'headers') and case.headers:
+            for key in case.headers:
+                if key in resolved_data:
+                    case.headers[key] = str(resolved_data[key])
+
+    def run_drift_check(self) -> List[Dict]:
+        """
+        Module A: The 'Docs vs. Code' Drift Check (The Integrity Test)
+        Uses schemathesis to verify if the API implementation matches the spec.
+        """
+        results = []
+        # Mapping check names to actual functions
+        check_map = {
+            "not_a_server_error": checks.not_a_server_error,
+            "status_code_conformance": oai_checks.status_code_conformance,
+            "response_schema_conformance": oai_checks.response_schema_conformance
+        }
+        check_names = list(check_map.keys())
+        
+        # Schemathesis 4.x checks require a context object
+        checks_config = ChecksConfig()
+        check_ctx = CheckContext(
+            override=None,
+            auth=None,
+            headers=None,
+            config=checks_config,
+            transport_kwargs=None,
+        )
+        
+        for op in self.schema.get_all_operations():
+            # Handle Result type (Ok/Err) wrapping if present
+            operation = op.ok() if hasattr(op, "ok") else op
+            
+            try:
+                # Generate test case
+                try:
+                    case = operation.as_strategy().example()
+                except (AttributeError, Exception):
+                    try:
+                        cases = list(operation.make_case())
+                        case = cases[0] if cases else None
+                    except (AttributeError, Exception):
+                        case = None
+                
+                if not case:
+                    continue
+
+                self._apply_seed_data(case)
+
+                formatted_path = operation.path
+                if case.path_parameters:
+                    for key, value in case.path_parameters.items():
+                         formatted_path = formatted_path.replace(f"{{{key}}}", f"{{{key}:{value}}}")
+                
+                print(f"AUDIT LOG: Testing endpoint {operation.method.upper()} {formatted_path}")
+
+                headers = {}
+                if self.api_key:
+                    auth_header = self.api_key if self.api_key.lower().startswith("bearer ") else f"Bearer {self.api_key}"
+                    headers["Authorization"] = auth_header
+
+                # Call the API
+                target_url = f"{self.base_url.rstrip('/')}/{formatted_path.lstrip('/')}"
+                print(f"AUDIT LOG: Calling {operation.method.upper()} {target_url}")
+                
+                response = case.call(base_url=self.base_url, headers=headers)
+                print(f"AUDIT LOG: Response Status Code: {response.status_code}")
+                
+                # We manually call the check function to ensure arguments are passed correctly.
+                for check_name in check_names:
+                    check_func = check_map[check_name]
+                    try:
+                        # Direct call: check_func(ctx, response, case)
+                        check_func(check_ctx, response, case)
+                        
+                        # If we get here, the check passed
+                        results.append({
+                            "module": "A",
+                            "endpoint": f"{operation.method.upper()} {operation.path}",
+                            "issue": f"{check_name} - Passed",
+                            "status": "PASS",
+                            "severity": "INFO",
+                            "details": f"Status: {response.status_code}"
+                        })
+
+                    except AssertionError as e:
+                        # This catches actual drift (e.g., Schema validation failed)
+                        # Capture and format detailed error info
+                        validation_errors = []
+                        
+                        # Safely get causes if they exist and are iterable
+                        causes = getattr(e, "causes", None)
+                        if causes:
+                            for cause in causes:
+                                if hasattr(cause, "message"):
+                                    validation_errors.append(cause.message)
+                                else:
+                                    validation_errors.append(str(cause))
+                        
+                        if not validation_errors:
+                            validation_errors.append(str(e) or "Validation failed")
+                        
+                        err_msg = "<br>".join(validation_errors)
+                        safe_err = html.escape(err_msg)
+                        
+                        # Add helpful context (Status & Body Preview)
+                        context_msg = f"Status: {response.status_code}"
+                        try:
+                            if response.content:
+                                preview = response.text[:500]
+                                safe_preview = html.escape(preview)
+                                context_msg += f"<br>Response: {safe_preview}"
+                        except Exception:
+                            pass
+                            
+                        full_details = f"<strong>Error:</strong> {safe_err}<br><br><strong>Context:</strong><br>{context_msg}"
+
+                        print(f"AUDIT LOG: Validation {check_name} failed: {err_msg}")
+                        results.append({
+                            "module": "A",
+                            "endpoint": f"{operation.method.upper()} {operation.path}",
+                            "issue": f"Schema Drift Detected ({check_name})",
+                            "status": "FAIL",
+                            "details": full_details,
+                            "severity": "HIGH"
+                        })
+                    except Exception as e:
+                        # This catches unexpected coding errors
+                        print(f"AUDIT LOG: Error executing check {check_name}: {str(e)}")
+                        results.append({
+                            "module": "A",
+                            "endpoint": f"{operation.method.upper()} {operation.path}",
+                            "issue": f"Check Execution Error ({check_name})",
+                            "status": "FAIL",
+                            "details": str(e),
+                            "severity": "HIGH"
+                        })
+                        
+            except Exception as e:
+                print(f"AUDIT LOG: Critical Error during endpoint test: {str(e)}")
+                continue
+                
+        return results
+
+    def run_resilience_tests(self) -> List[Dict]:
+        """
+        Module B: The 'Resilience' Stress Test (Art. 24 & 25)
+        Checks for Rate Limiting and Timeout gracefully handling.
+        """
+        results = []
+        ops = list(self.schema.get_all_operations())
+        if not ops:
+            return []
+        
+        print("AUDIT LOG: Starting Module B: Resilience Stress Test (flooding requests)...")
+        
+        
+        operation = ops[0].ok() if hasattr(ops[0], "ok") else ops[0]
+        
+        # Simulate flooding
+        responses = []
+        for _ in range(50): 
+            try:
+                case = operation.as_strategy().example()
+            except (AttributeError, Exception):
+                try:
+                    cases = list(operation.make_case())
+                    case = cases[0] if cases else None
+                except (AttributeError, Exception):
+                    case = None
+            
+            if case:
+                self._apply_seed_data(case)
+
+                headers = {}
+                if self.api_key:
+                    auth_header = self.api_key if self.api_key.lower().startswith("bearer ") else f"Bearer {self.api_key}"
+                    headers["Authorization"] = auth_header
+                    
+                responses.append(case.call(base_url=self.base_url, headers=headers))
+        
+        has_429 = any(r.status_code == 429 for r in responses)
+        has_500 = any(r.status_code == 500 for r in responses)
+        
+        if not has_429 and has_500:
+            results.append({
+                "module": "B",
+                "issue": "Poor Resilience: 500 Error during flood",
+                "status": "FAIL",
+                "details": "The API returned 500 Internal Server Error instead of 429 Too Many Requests when flooded.",
+                "severity": "CRITICAL"
+            })
+        elif not has_429:
+             results.append({
+                "module": "B",
+                "issue": "No Rate Limiting Enforced",
+                "status": "FAIL",
+                "details": "The API did not return 429 Too Many Requests during high volume testing.",
+                "severity": "MEDIUM"
+            })
+        else:
+            results.append({
+                "module": "B",
+                "issue": "Rate Limiting Functional",
+                "status": "PASS",
+                "details": "The API correctly returned 429 Too Many Requests when flooded.",
+                "severity": "INFO"
+            })
+            
+        if not has_500:
+             results.append({
+                "module": "B",
+                "issue": "Stress Handling",
+                "status": "PASS",
+                "details": "No 500 Internal Server Errors were observed during stress testing.",
+                "severity": "INFO"
+            })
+
+        return results
+
+    def run_security_hygiene(self) -> List[Dict]:
+        """
+        Module C: Security Hygiene Check
+        Checks for TLS and Auth leakage in URL.
+        """
+        results = []
+        print(f"AUDIT LOG: Checking Security Hygiene for base URL: {self.base_url}")
+        if self.base_url and not self.base_url.startswith("https"):
+            results.append({
+                "module": "C",
+                "issue": "Insecure Connection (No TLS)",
+                "status": "FAIL",
+                "details": "The API base URL does not use HTTPS.",
+                "severity": "CRITICAL"
+            })
+        else:
+             results.append({
+                "module": "C",
+                "issue": "Secure Connection (TLS)",
+                "status": "PASS",
+                "details": "The API uses HTTPS.",
+                "severity": "INFO"
+            })
+        
+        auth_leakage_found = False
+        for op in self.schema.get_all_operations():
+            operation = op.ok() if hasattr(op, "ok") else op
+            endpoint = operation.path
+            if "key" in endpoint.lower() or "token" in endpoint.lower():
+                auth_leakage_found = True
+                results.append({
+                    "module": "C",
+                    "issue": "Auth Leakage Risk",
+                    "status": "FAIL",
+                    "details": f"Endpoint '{endpoint}' indicates auth tokens might be passed in the URL.",
+                    "severity": "HIGH"
+                })
+        
+        if not auth_leakage_found:
+            results.append({
+                "module": "C",
+                "issue": "No Auth Leakage in URLs",
+                "status": "PASS",
+                "details": "No endpoints found with 'key' or 'token' in the path, suggesting safe header-based auth.",
+                "severity": "INFO"
+            })
+        
+        return results
+
+    def run_full_audit(self) -> Dict:
+        return {
+            "drift_check": self.run_drift_check(),
+            "resilience": self.run_resilience_tests(),
+            "security": self.run_security_hygiene()
+        }

pandoraspec-0.2.0/pandoraspec/reporting.py

@@ -0,0 +1,209 @@
+import os
+from datetime import datetime
+from jinja2 import Environment, FileSystemLoader
+from weasyprint import HTML
+
+TEMPLATE_DIR = os.path.join(os.path.dirname(__file__), "templates")
+REPORTS_DIR = "reports"
+
+if not os.path.exists(REPORTS_DIR):
+    os.makedirs(REPORTS_DIR)
+
+def generate_report(vendor_name: str, audit_results: dict) -> str:
+    """
+    Module D: The Compliance Report (The Deliverable)
+    Generates a branded PDF report.
+    """
+    # Calculate score (simple MVP logic)
+    # Filter out PASS results for scoring
+    drift_issues = [r for r in audit_results["drift_check"] if r.get("status") != "PASS"]
+    resilience_issues = [r for r in audit_results["resilience"] if r.get("status") != "PASS"]
+    security_issues = [r for r in audit_results["security"] if r.get("status") != "PASS"]
+
+    drift_score = max(0, 100 - len(drift_issues) * 10)
+    resilience_score = max(0, 100 - len(resilience_issues) * 15)
+    security_score = max(0, 100 - len(security_issues) * 20)
+    
+    total_score = (drift_score + resilience_score + security_score) / 3
+    
+    # Pass/Fail based on score
+    is_compliant = total_score >= 80
+
+    context = {
+        "vendor_name": vendor_name,
+        "date": datetime.now().strftime("%Y-%m-%d"),
+        "score": round(total_score),
+        "is_compliant": is_compliant,
+        "results": audit_results
+    }
+
+    # Helper to render findings tables
+    def render_findings_table(module_name, findings):
+        if not findings:
+            return f"<p class='no-issues'>✅ No issues found in {module_name}.</p>"
+        
+        rows = ""
+        for f in findings:
+            endpoint = f.get('endpoint', 'Global')
+            status = f.get('status', 'FAIL')
+            
+            if status == "PASS":
+                severity_class = "pass"
+                severity_text = "PASS"
+            else:
+                severity_class = f.get('severity', 'LOW').lower()
+                severity_text = f.get('severity')
+
+            rows += f"""
+            <tr>
+                <td><span class="badge badge-{severity_class}">{severity_text}</span></td>
+                <td><code>{endpoint}</code></td>
+                <td><strong>{f.get('issue')}</strong></td>
+                <td>{f.get('details')}</td>
+            </tr>
+            """
+        
+        return f"""
+        <table>
+            <thead>
+                <tr>
+                    <th style="width: 10%">Status</th>
+                    <th style="width: 25%">Endpoint</th>
+                    <th style="width: 25%">Issue</th>
+                    <th>Technical Details</th>
+                </tr>
+            </thead>
+            <tbody>
+                {rows}
+            </tbody>
+        </table>
+        """
+
+    html_content = f"""
+    <html>
+    <head>
+        <style>
+            @page {{ margin: 50px; }}
+            body {{ font-family: 'Inter', 'Helvetica Neue', Helvetica, Arial, sans-serif; color: #1e293b; line-height: 1.5; }}
+            .header {{ 
+                background: linear-gradient(135deg, #1e1b4b 0%, #4338ca 100%); 
+                color: white; 
+                padding: 40px; 
+                text-align: center; 
+                border-radius: 12px;
+                margin-bottom: 40px;
+            }}
+            .header h1 {{ margin: 0; font-size: 28px; letter-spacing: -0.5px; }}
+            .header p {{ margin: 10px 0 0; opacity: 0.8; font-size: 16px; }}
+            
+            .summary-grid {{ display: flex; justify-content: space-between; margin-bottom: 40px; }}
+            .summary-card {{ 
+                background: #f8fafc; 
+                padding: 20px; 
+                border-radius: 8px; 
+                width: 45%; 
+                border: 1px solid #e2e8f0;
+            }}
+            
+            .score-big {{ font-size: 56px; font-weight: 800; margin: 10px 0; }}
+            .status-badge {{ 
+                display: inline-block; 
+                padding: 6px 16px; 
+                border-radius: 99px; 
+                font-weight: 700; 
+                text-transform: uppercase;
+                font-size: 14px;
+            }}
+            .status-pass {{ background: #dcfce7; color: #166534; }}
+            .status-fail {{ background: #fee2e2; color: #991b1b; }}
+            
+            .section {{ margin-top: 40px; page-break-inside: avoid; }}
+            .section h3 {{ border-bottom: 2px solid #e2e8f0; padding-bottom: 10px; color: #0f172a; margin-bottom: 20px; }}
+            
+            table {{ width: 100%; border-collapse: collapse; margin-top: 10px; font-size: 12px; table-layout: fixed; word-wrap: break-word; }}
+            th, td {{ padding: 12px; text-align: left; border-bottom: 1px solid #e2e8f0; vertical-align: top; }}
+            td {{ word-break: break-word; white-space: pre-wrap; }}
+            th {{ background-color: #f1f5f9; color: #475569; font-weight: 600; text-transform: uppercase; letter-spacing: 0.5px; }}
+            
+            .badge {{ 
+                padding: 4px 8px; 
+                border-radius: 4px; 
+                font-size: 10px; 
+                font-weight: 700; 
+                color: white; 
+                text-transform: uppercase; 
+            }}
+            .badge-critical {{ background: #ef4444; }}
+            .badge-high {{ background: #f97316; }}
+            .badge-medium {{ background: #eab308; }}
+            .badge-low {{ background: #3b82f6; }}
+            .badge-pass {{ background: #16a34a; }}
+            
+            .no-issues {{ color: #059669; font-weight: 500; padding: 10px 0; }}
+            code {{ font-family: 'Courier New', monospace; background: #f1f5f9; padding: 2px 4px; border-radius: 3px; font-size: 11px; }}
+            
+            footer {{ margin-top: 50px; text-align: center; color: #94a3b8; font-size: 10px; border-top: 1px solid #e2e8f0; padding-top: 20px; }}
+        </style>
+    </head>
+    <body>
+        <div class="header">
+            <h1>DORA ICT Third-Party Risk Assessment</h1>
+            <p>Vendor Compliance Audit for <strong>{vendor_name}</strong></p>
+            <p>Report Date: {datetime.now().strftime("%B %d, %Y")}</p>
+        </div>
+
+        <div class="summary-grid">
+            <div class="summary-card">
+                <p style="margin:0; color:#64748b; font-weight:600;">Overall Risk Score</p>
+                <div class="score-big" style="color: {'#166534' if is_compliant else '#991b1b'}">{round(total_score)}<span style="font-size: 24px; color:#94a3b8; font-weight:400;">/100</span></div>
+            </div>
+            <div class="summary-card">
+                <p style="margin:0; color:#64748b; font-weight:600;">Compliance Status</p>
+                <div style="margin-top: 20px;">
+                    <span class="status-badge {'status-pass' if is_compliant else 'status-fail'}">
+                        {'COMPLIANT (PASS)' if is_compliant else 'NON-COMPLIANT (FAIL)'}
+                    </span>
+                </div>
+            </div>
+        </div>
+
+        <div class="section">
+            <h3>Technical Findings - Module A: Schema Integrity (Docs vs. Code)</h3>
+            <p style="font-size: 13px; color: #64748b; margin-bottom: 15px;">
+                This check verifies if the actual API implementation adheres to the provided OpenAPI specification.
+                Discrepancies here indicate "Schema Drift," which violates DORA requirements for accurate ICT documentation.
+            </p>
+            {render_findings_table("Module A", audit_results['drift_check'])}
+        </div>
+
+        <div class="section">
+            <h3>Technical Findings - Module B: Resilience Stress Test</h3>
+            <p style="font-size: 13px; color: #64748b; margin-bottom: 15px;">
+                Assesses high-load behavior and error handling (DORA Art. 24 & 25).
+                Checks if the system gracefully handles request flooding with appropriate 429 status codes.
+            </p>
+            {render_findings_table("Module B", audit_results['resilience'])}
+        </div>
+
+        <div class="section">
+            <h3>Technical Findings - Module C: Security Hygiene</h3>
+            <p style="font-size: 13px; color: #64748b; margin-bottom: 15px;">
+                Evaluates baseline security controls including TLS encryption and sensitive information leakage in URLs.
+            </p>
+            {render_findings_table("Module C", audit_results['security'])}
+        </div>
+
+        <footer>
+            <p>CONFIDENTIAL - FOR INTERNAL AUDIT PURPOSES ONLY</p>
+            <p>Generated by PanDoraSpec</p>
+        </footer>
+    </body>
+    </html>
+    """
+
+    filename = f"{vendor_name.replace(' ', '_')}_{datetime.now().strftime('%Y%m%d%H%M%S')}.pdf"
+    filepath = os.path.join(REPORTS_DIR, filename)
+    
+    HTML(string=html_content).write_pdf(filepath)
+    
+    return filepath

pandoraspec-0.2.0/pandoraspec.egg-info/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pandoraspec
+Version: 0.2.0
+Summary: DORA Compliance Auditor for OpenAPI Specs
+Author-email: Ulises Merlan <ulimerlan@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: schemathesis==4.9.1
+Requires-Dist: typer[all]
+Requires-Dist: rich
+Requires-Dist: weasyprint
+Requires-Dist: jinja2
+Requires-Dist: requests
+
+# PanDoraSpec
+
+**The Open DORA Compliance Engine for OpenAPI Specs.**
+
+PanDoraSpec is a CLI tool that performs deep technical due diligence on APIs to verify compliance with **DORA (Digital Operational Resilience Act)** requirements. It compares OpenAPI/Swagger specifications against real-world implementation to detect schema drift, resilience gaps, and security issues.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pandoraspec
+```
+
+### System Requirements
+The PDF report generation requires `weasyprint`, which depends on **Pango**.
+
+**macOS:**
+```bash
+brew install pango
+```
+
+**Debian / Ubuntu:**
+```bash
+sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0
+```
+
+## 🛠️ Development Setup
+
+To run the CLI locally without reinstalling after every change:
+
+1. **Clone & CD**:
+```bash
+git clone ...
+cd pandoraspec
+```
+
+2. **Create & Activate Virtual Environment**:
+It's recommended to use a virtual environment to keep dependencies isolated.
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. **Editable Install**:
+```bash
+pip install -e .
+```
+This links the `pandoraspec` command directly to your source code. Any changes you make will be reflected immediately.
+
+## 🚀 Usage
+
+Run the audit directly from your terminal.
+
+### Basic Scan
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json
+```
+
+### With Options
+```bash
+pandoraspec https://api.example.com/spec.json --vendor "Stripe" --key "sk_live_..."
+```
+
+### Local File
+```bash
+pandoraspec ./openapi.yaml
+```
+
+---
+
+## 🏎️ Zero-Config Testing (DORA Compliance)
+
+For standard **DORA compliance**, you simply need to verify that your API implementation matches its specification. **No configuration is required.**
+
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json
+```
+
+This runs a **fuzzing** audit where random data is generated based on your schema types (e.g., sending random integers for IDs). 
+- **Value:** This is sufficient to prove that your API correctly handles unexpected inputs and adheres to the basic contract (e.g., returning 400 Bad Request instead of 500 Server Error).
+- **Limitation:** Detailed business logic requiring valid IDs (e.g., `GET /user/{id}` where `{id}` must exist) may return `404 Not Found`. This is acceptable for a compliance scan but may not fully exercise deeper code paths.
+
+---
+
+## 🧠 Advanced Testing with Seed Data
+
+To test **specific business workflows** (e.g., successfully retrieving a user profile), you can provide "Seed Data". This tells PanDoraSpec to use known, valid values instead of random fuzzing data.
+
+```bash
+pandoraspec https://petstore.swagger.io/v2/swagger.json --config seed_parameters.yaml
+```
+
+### Configuration Hierarchy
+You can define seed values at three levels of specificity. The engine resolves values in this order: **Endpoints > Verbs > General**.
+
+```yaml
+seed_data:
+  # 1. General: Applies to EVERYTHING (path params, query params, headers)
+  general:
+    username: "test_user"
+    limit: 50
+
+  # 2. Verbs: Applies only to specific HTTP methods (Overwrites General)
+  verbs:
+    POST:
+      username: "admin_user" # Creation requests use a different user
+
+  # 3. Endpoints: Applies only to specific routes (Overwrites Everything)
+  endpoints:
+    /users/me:
+      GET:
+        limit: 10
+```
+
+### 🔗 Dynamic Seed Data (Chaining Requests)
+You can even test **dependency chains** where one endpoint requires data from another (e.g., get a User ID from a search result to query their profile).
+
+**Supported Features:**
+- **Dynamic Resolution:** Fetch a value from another API call before running the test.
+- **Extraction:** Extract values from JSON responses or plain text.
+- **Parameter Interpolation:** Use `{param}` in the dependency URL to chain multiple steps.
+
+```yaml
+endpoints:
+  /user/{username}:
+    GET:
+      username:
+        # 1. Fetch the user list first
+        # 2. Extract the 'username' field from the response
+        from_endpoint: "GET /users/search?role=admin"
+        extract: "data.items.0.username"
+
+  /orders/{orderId}:
+    GET:
+      orderId:
+        # 1. Use the {userId} from our general seeds
+        # 2. Call /users/{userId}/latest-order
+        # 3. Extract the ID using Regex from a message string
+        from_endpoint: "GET /users/{userId}/latest-order"
+        extract: "message"
+        regex: "Order ID: ([0-9]+)"
+```
+
+---
+
+## 🛡️ What It Checks
+
+### Module A: The Integrity Test (Drift)
+Checks if your API implementation matches your documentation.
+- **Why?** DORA requires you to monitor if the service effectively supports your critical functions. If the API behaves differently than documented, it's a risk.
+
+### Module B: The Resilience Test
+Stress tests the API to ensure it handles invalid inputs gracefully (`4xx` vs `5xx`).
+- **Why?** DORA Article 25 calls for "Digital operational resilience testing".
+
+### Module C: Security Hygiene
+Checks for common security headers and configurations.
+
+### Module D: The Report
+Generates a PDF report: **"DORA ICT Third-Party Technical Risk Assessment"**.
+
+---
+
+## 📄 License
+
+MIT

pandoraspec-0.2.0/pandoraspec.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+pandoraspec/__init__.py
+pandoraspec/cli.py
+pandoraspec/core.py
+pandoraspec/reporting.py
+pandoraspec.egg-info/PKG-INFO
+pandoraspec.egg-info/SOURCES.txt
+pandoraspec.egg-info/dependency_links.txt
+pandoraspec.egg-info/entry_points.txt
+pandoraspec.egg-info/requires.txt
+pandoraspec.egg-info/top_level.txt

pandoraspec-0.2.0/pandoraspec.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pandoraspec-0.2.0/pandoraspec.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pandoraspec = pandoraspec.cli:main

pandoraspec-0.2.0/pandoraspec.egg-info/requires.txt

@@ -0,0 +1,6 @@
+schemathesis==4.9.1
+typer[all]
+rich
+weasyprint
+jinja2
+requests

pandoraspec-0.2.0/pandoraspec.egg-info/top_level.txt

@@ -0,0 +1 @@
+pandoraspec

pandoraspec-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pandoraspec"
+version = "0.2.0"
+description = "DORA Compliance Auditor for OpenAPI Specs"
+readme = "README.md"
+authors = [{ name = "Ulises Merlan", email = "ulimerlan@gmail.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = [
+    "schemathesis==4.9.1",
+    "typer[all]",
+    "rich",
+    "weasyprint",
+    "jinja2",
+    "requests"
+]
+
+[project.scripts]
+# This maps the terminal command 'pandoraspec' to your python code
+pandoraspec = "pandoraspec.cli:main" 
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pandoraspec*"]
+exclude = ["tests*"]

pandoraspec-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+