gwc-pybundle 2.1.2__py3-none-any.whl

pybundle/steps/fastapi_integration.py

@@ -0,0 +1,250 @@
+"""
+Step: FastAPI Integration
+Validate FastAPI OpenAPI schema and endpoint documentation.
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+
+from .base import Step, StepResult
+
+
+class FastAPIIntegrationStep(Step):
+    """Validate FastAPI schema and endpoint completeness."""
+
+    name = "fastapi schema"
+
+    def run(self, ctx: "BundleContext") -> StepResult:  # type: ignore[name-defined]
+        """Validate FastAPI integration."""
+        import time
+
+        start = time.time()
+
+        root = ctx.root
+
+        # Find FastAPI app
+        app_info = self._find_fastapi_app(root)
+        if not app_info:
+            elapsed = int(time.time() - start)
+            return StepResult(
+                self.name, "SKIP", elapsed, "No FastAPI application found"
+            )
+
+        # Analyze endpoints
+        endpoints = self._analyze_endpoints(root, app_info)
+
+        # Generate report
+        lines = [
+            "=" * 80,
+            "FASTAPI INTEGRATION REPORT",
+            "=" * 80,
+            "",
+        ]
+
+        lines.extend(
+            [
+                "SUMMARY",
+                "=" * 80,
+                f"FastAPI app location: {app_info['file']}:{app_info['name']}",
+                f"Total endpoints: {len(endpoints)}",
+                "",
+            ]
+        )
+
+        # Endpoint analysis
+        lines.extend(
+            [
+                "ENDPOINTS",
+                "=" * 80,
+                "",
+            ]
+        )
+
+        documented = 0
+        undocumented = 0
+
+        for endpoint in sorted(endpoints, key=lambda e: e["path"]):
+            doc_status = "✓" if endpoint["has_docstring"] else "⚠"
+            documented += 1 if endpoint["has_docstring"] else 0
+            undocumented += 0 if endpoint["has_docstring"] else 1
+
+            lines.append(f"{doc_status} {endpoint['method']:6} {endpoint['path']}")
+            if endpoint["has_docstring"]:
+                lines.append(f"   Summary: {endpoint['docstring_first_line']}")
+            else:
+                lines.append("   ⚠ Missing docstring (won't appear in OpenAPI)")
+
+        lines.append("")
+
+        # Statistics
+        lines.extend(
+            [
+                "DOCUMENTATION STATISTICS",
+                "-" * 80,
+                f"Documented endpoints: {documented}/{len(endpoints)} ({100*documented//len(endpoints)}%)" if endpoints else "No endpoints found",
+                f"Undocumented endpoints: {undocumented}/{len(endpoints)}" if endpoints else "",
+                "",
+            ]
+        )
+
+        # Response models
+        lines.extend(
+            [
+                "RESPONSE MODELS",
+                "=" * 80,
+                "",
+            ]
+        )
+
+        models_count = 0
+        for endpoint in endpoints:
+            if endpoint.get("response_model"):
+                models_count += 1
+                lines.append(f"  {endpoint['method']:6} {endpoint['path']}")
+                lines.append(f"    Response: {endpoint['response_model']}")
+
+        if models_count == 0:
+            lines.append("  ℹ No response models found")
+
+        lines.append("")
+
+        # Recommendations
+        lines.extend(
+            [
+                "=" * 80,
+                "BEST PRACTICES & RECOMMENDATIONS",
+                "=" * 80,
+                "",
+                "1. DOCUMENTATION",
+                "   ✓ Add docstrings to all endpoint handlers",
+                "   ✓ Use triple-quoted docstrings for OpenAPI summary",
+                "   ✓ Include examples in docstrings for clarity",
+                "",
+                "2. RESPONSE MODELS",
+                "   ✓ Define Pydantic models for all responses",
+                "   ✓ Use response_model parameter in @app.get/post/etc",
+                "   ✓ Include status_code for non-200 responses",
+                "",
+                "3. REQUEST VALIDATION",
+                "   ✓ Use Pydantic models for request bodies",
+                "   ✓ Use Path, Query, Header for parameter validation",
+                "   ✓ Provide examples in Field descriptions",
+                "",
+                "4. ERROR HANDLING",
+                "   ✓ Define responses for 400, 404, 500, etc",
+                "   ✓ Use HTTPException with detail messages",
+                "   ✓ Document possible error responses in docstrings",
+                "",
+                "5. SECURITY",
+                "   ✓ Use security=[] parameter for protected endpoints",
+                "   ✓ Document security requirements in OpenAPI",
+                "   ✓ Validate bearer tokens and API keys",
+                "",
+                "6. TESTING",
+                "   ✓ Use TestClient for endpoint testing",
+                "   ✓ Test all response status codes",
+                "   ✓ Test request validation (happy path + errors)",
+                "",
+            ]
+        )
+
+        # Write report
+        output = "\n".join(lines)
+        dest = ctx.workdir / "logs" / "150_fastapi_schema.txt"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(output, encoding="utf-8")
+
+        elapsed = int(time.time() - start)
+        return StepResult(self.name, "OK", elapsed, "")
+
+    def _find_fastapi_app(self, root: Path) -> Optional[Dict[str, Any]]:
+        """Find FastAPI app instance."""
+        python_files = list(root.rglob("*.py"))
+
+        for py_file in python_files:
+            if any(
+                part in py_file.parts
+                for part in ["venv", ".venv", "env", "__pycache__", "site-packages"]
+            ):
+                continue
+
+            try:
+                source = py_file.read_text(encoding="utf-8", errors="ignore")
+
+                # Look for FastAPI imports and app creation
+                if "from fastapi import" in source or "import fastapi" in source:
+                    if "app = FastAPI" in source or "app: FastAPI" in source:
+                        # Extract app variable name
+                        import re
+
+                        match = re.search(r"(\w+)\s*=\s*FastAPI\(", source)
+                        if match:
+                            return {
+                                "file": str(py_file.relative_to(root)),
+                                "name": match.group(1),
+                            }
+            except (OSError, UnicodeDecodeError):
+                continue
+
+        return None
+
+    def _analyze_endpoints(self, root: Path, app_info: Dict) -> List[Dict[str, Any]]:
+        """Analyze FastAPI endpoints."""
+        endpoints = []
+
+        # Look for route decorators in the app file
+        app_file = root / app_info["file"]
+        if not app_file.exists():
+            return endpoints
+
+        try:
+            source = app_file.read_text(encoding="utf-8", errors="ignore")
+
+            # Look for decorators: @app.get, @app.post, etc.
+            import re
+
+            # Pattern: @app.method("path")
+            pattern = r"@(?:app|router)\.(get|post|put|delete|patch|head|options)\(['\"]([^'\"]+)['\"]"
+            for match in re.finditer(pattern, source):
+                method, path = match.groups()
+                endpoints.append(
+                    {
+                        "method": method.upper(),
+                        "path": path,
+                        "has_docstring": False,
+                        "docstring_first_line": "",
+                        "response_model": None,
+                    }
+                )
+
+            # Check for docstrings in functions following decorators
+            lines = source.split("\n")
+            for i, line in enumerate(lines):
+                if re.search(r"@(?:app|router)\.(get|post|put|delete|patch|head|options)", line):
+                    # Look for function definition
+                    for j in range(i + 1, min(i + 5, len(lines))):
+                        if "def " in lines[j]:
+                            # Check for docstring
+                            if j + 1 < len(lines):
+                                next_line = lines[j + 1].strip()
+                                if next_line.startswith('"""') or next_line.startswith("'''"):
+                                    docstring = next_line.replace('"""', "").replace("'''", "").strip()
+                                    if endpoints:
+                                        endpoints[-1]["has_docstring"] = True
+                                        endpoints[-1]["docstring_first_line"] = docstring
+                            break
+
+            # Check for response_model
+            for i, line in enumerate(lines):
+                if "response_model=" in line and endpoints:
+                    import re
+
+                    match = re.search(r"response_model=(\w+)", line)
+                    if match:
+                        endpoints[-1]["response_model"] = match.group(1)
+
+        except Exception:
+            pass
+
+        return endpoints

pybundle/steps/flask_debugging.py

@@ -0,0 +1,312 @@
+"""
+Step: Flask Debugging
+Detect Flask debug mode and other security issues in Flask apps.
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional
+
+from .base import Step, StepResult
+
+
+class FlaskDebuggingStep(Step):
+    """Detect Flask debug mode and security issues."""
+
+    name = "flask debugging"
+
+    def run(self, ctx: "BundleContext") -> StepResult:  # type: ignore[name-defined]
+        """Check Flask debugging configuration."""
+        import time
+
+        start = time.time()
+
+        root = ctx.root
+
+        # Find Flask app
+        flask_info = self._find_flask_app(root)
+        if not flask_info:
+            elapsed = int(time.time() - start)
+            return StepResult(
+                self.name, "SKIP", elapsed, "No Flask application found"
+            )
+
+        # Analyze Flask configuration
+        config_issues = self._analyze_flask_config(root, flask_info)
+
+        # Generate report
+        lines = [
+            "=" * 80,
+            "FLASK SECURITY & DEBUGGING REPORT",
+            "=" * 80,
+            "",
+        ]
+
+        lines.extend(
+            [
+                "SUMMARY",
+                "=" * 80,
+                f"Flask app location: {flask_info['file']}:{flask_info['name']}",
+                "",
+            ]
+        )
+
+        # Configuration issues
+        lines.extend(
+            [
+                "SECURITY ISSUES",
+                "=" * 80,
+                "",
+            ]
+        )
+
+        if config_issues:
+            for level, issue, detail in config_issues:
+                icon = "✗" if level == "ERROR" else "⚠"
+                lines.append(f"{icon} [{level}] {issue}")
+                if detail:
+                    lines.append(f"    {detail}")
+            lines.append("")
+        else:
+            lines.append("✓ No critical security issues detected")
+            lines.append("")
+
+        # Debug mode analysis
+        lines.extend(
+            [
+                "DEBUG MODE ANALYSIS",
+                "-" * 80,
+                "",
+            ]
+        )
+
+        debug_findings = self._check_debug_mode(root, flask_info)
+        for finding in debug_findings:
+            lines.append(f"  • {finding}")
+
+        lines.append("")
+
+        # Routes analysis
+        lines.extend(
+            [
+                "ROUTES ANALYSIS",
+                "=" * 80,
+                "",
+            ]
+        )
+
+        routes = self._extract_routes(root, flask_info)
+        if routes:
+            lines.append(f"Found {len(routes)} route(s):")
+            lines.append("")
+            for method, path, handler in routes:
+                lines.append(f"  {method:6} {path:40} -> {handler}")
+        else:
+            lines.append("  ℹ No routes found via static analysis")
+
+        lines.append("")
+
+        # Recommendations
+        lines.extend(
+            [
+                "=" * 80,
+                "FLASK DEPLOYMENT BEST PRACTICES",
+                "=" * 80,
+                "",
+                "1. DEBUG MODE",
+                "   ✗ NEVER use DEBUG=True in production",
+                "   ✓ Use environment variables to control debug mode",
+                "   ✓ Set DEBUG=False in production configuration",
+                "   ✓ Use app.config.from_object('config.Production')",
+                "",
+                "2. SECRET KEY",
+                "   ✓ Use strong, random SECRET_KEY (os.urandom(24))",
+                "   ✓ Store SECRET_KEY in environment variables",
+                "   ✓ Never hardcode secrets in source code",
+                "   ✓ Rotate SECRET_KEY regularly in production",
+                "",
+                "3. SESSION SECURITY",
+                "   ✓ Set SESSION_COOKIE_SECURE=True",
+                "   ✓ Set SESSION_COOKIE_HTTPONLY=True",
+                "   ✓ Set SESSION_COOKIE_SAMESITE='Lax' or 'Strict'",
+                "   ✓ Use secure session backends (Redis, database)",
+                "",
+                "4. CORS & HEADERS",
+                "   ✓ Use Flask-CORS with restricted origins",
+                "   ✓ Set X-Frame-Options: DENY",
+                "   ✓ Set X-Content-Type-Options: nosniff",
+                "   ✓ Set X-XSS-Protection: 1; mode=block",
+                "   ✓ Set Strict-Transport-Security (HSTS)",
+                "",
+                "5. ERROR HANDLING",
+                "   ✓ Implement custom 404, 500 error handlers",
+                "   ✓ Log errors securely (no sensitive data)",
+                "   ✓ Hide stack traces in production",
+                "   ✓ Return generic error messages to users",
+                "",
+                "6. DEPENDENCIES",
+                "   ✓ Use pip-audit to check for vulnerabilities",
+                "   ✓ Keep Flask and extensions updated",
+                "   ✓ Review security advisories regularly",
+                "",
+                "7. DEPLOYMENT",
+                "   ✓ Use WSGI server (Gunicorn, uWSGI, Waitress)",
+                "   ✓ Run behind reverse proxy (Nginx, Apache)",
+                "   ✓ Use HTTPS with valid certificate",
+                "   ✓ Enable security headers in reverse proxy",
+                "",
+            ]
+        )
+
+        # Write report
+        output = "\n".join(lines)
+        dest = ctx.workdir / "logs" / "151_flask_checks.txt"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(output, encoding="utf-8")
+
+        elapsed = int(time.time() - start)
+        return StepResult(self.name, "OK", elapsed, "")
+
+    def _find_flask_app(self, root: Path) -> Optional[Dict[str, str]]:
+        """Find Flask app instance."""
+        python_files = list(root.rglob("*.py"))
+
+        for py_file in python_files:
+            if any(
+                part in py_file.parts
+                for part in ["venv", ".venv", "env", "__pycache__", "site-packages"]
+            ):
+                continue
+
+            try:
+                source = py_file.read_text(encoding="utf-8", errors="ignore")
+
+                # Look for Flask imports and app creation
+                if "from flask import" in source or "import flask" in source:
+                    if "Flask(" in source:
+                        # Extract app variable name
+                        match = re.search(r"(\w+)\s*=\s*Flask\(", source)
+                        if match:
+                            return {
+                                "file": str(py_file.relative_to(root)),
+                                "name": match.group(1),
+                            }
+            except (OSError, UnicodeDecodeError):
+                continue
+
+        return None
+
+    def _analyze_flask_config(
+        self, root: Path, flask_info: Dict[str, str]
+    ) -> List[Tuple[str, str, str]]:
+        """Analyze Flask configuration for security issues."""
+        issues = []
+
+        # Check for hardcoded secrets
+        python_files = list(root.rglob("*.py"))
+        for py_file in python_files:
+            if any(
+                part in py_file.parts
+                for part in ["venv", ".venv", "env", "__pycache__", "site-packages"]
+            ):
+                continue
+
+            try:
+                source = py_file.read_text(encoding="utf-8", errors="ignore")
+
+                # Check for hardcoded SECRET_KEY
+                if re.search(
+                    r"['\"]SECRET_KEY['\"]?\s*[:=]\s*['\"](?!<|{{)", source
+                ):
+                    issues.append(
+                        (
+                            "ERROR",
+                            "Hardcoded SECRET_KEY detected",
+                            f"File: {py_file.relative_to(root)}",
+                        )
+                    )
+
+                # Check for DEBUG=True in code
+                if re.search(r"DEBUG\s*=\s*True", source):
+                    issues.append(
+                        (
+                            "ERROR",
+                            "DEBUG=True found in code",
+                            f"File: {py_file.relative_to(root)} - Use environment variables instead",
+                        )
+                    )
+
+            except (OSError, UnicodeDecodeError):
+                continue
+
+        return issues
+
+    def _check_debug_mode(self, root: Path, flask_info: Dict[str, str]) -> List[str]:
+        """Check debug mode configuration."""
+        findings = []
+
+        app_file = root / flask_info["file"]
+        if app_file.exists():
+            try:
+                source = app_file.read_text(encoding="utf-8", errors="ignore")
+
+                if "app.run(debug=True)" in source:
+                    findings.append(
+                        "⚠ app.run(debug=True) found - ensure this is only in development"
+                    )
+
+                if "FLASK_ENV" in source:
+                    findings.append(
+                        "✓ FLASK_ENV environment variable is used"
+                    )
+
+                if "os.getenv('DEBUG')" in source or "os.environ.get('DEBUG')" in source:
+                    findings.append(
+                        "✓ DEBUG mode controlled via environment variable"
+                    )
+
+                if not any(
+                    pattern in source
+                    for pattern in ["debug=", "FLASK_ENV", "DEBUG", "app.run()"]
+                ):
+                    findings.append(
+                        "ℹ No explicit debug configuration found - verify Flask configuration chain"
+                    )
+
+            except (OSError, UnicodeDecodeError):
+                pass
+
+        return findings
+
+    def _extract_routes(self, root: Path, flask_info: Dict[str, str]) -> List[Tuple[str, str, str]]:
+        """Extract Flask routes."""
+        routes = []
+
+        app_file = root / flask_info["file"]
+        if not app_file.exists():
+            return routes
+
+        try:
+            source = app_file.read_text(encoding="utf-8", errors="ignore")
+            lines = source.split("\n")
+
+            # Pattern: @app.route or @app.get, @app.post, etc.
+            for i, line in enumerate(lines):
+                route_match = re.search(r"@(?:app|blueprint)\.(route|get|post|put|delete)\(['\"]([^'\"]+)", line)
+                if route_match:
+                    method = route_match.group(1).upper()
+                    path = route_match.group(2)
+
+                    # Find handler function
+                    for j in range(i + 1, min(i + 3, len(lines))):
+                        func_match = re.search(r"def\s+(\w+)\s*\(", lines[j])
+                        if func_match:
+                            handler = func_match.group(1)
+                            routes.append((method, path, handler))
+                            break
+
+        except Exception:
+            pass
+
+        return routes