backend-guard 1.0.0__py3-none-any.whl

auditor/__init__.py

@@ -0,0 +1,10 @@
+"""Universal Backend Codebase Auditor (Backend Guard).
+
+A production-grade, extensible static analysis and architecture auditing tool
+for modern backend systems.
+"""
+
+__version__ = "1.0.0"
+__tool_name__ = "backend-guard"
+__project_name__ = "Universal Backend Auditor"
+

auditor/analyzers/__init__.py

@@ -0,0 +1,27 @@
+# ruff: noqa: F401, I001
+"""Analyzer initialization and dynamic discovery loader."""
+
+import auditor.analyzers.universal.architecture
+import auditor.analyzers.universal.solid
+import auditor.analyzers.universal.dependency
+import auditor.analyzers.universal.complexity
+import auditor.analyzers.universal.duplication
+import auditor.analyzers.universal.security
+import auditor.analyzers.universal.error_handling
+import auditor.analyzers.universal.logging
+import auditor.analyzers.universal.configuration
+import auditor.analyzers.universal.database_design
+import auditor.analyzers.universal.api_design
+import auditor.analyzers.universal.testing
+import auditor.analyzers.universal.production_readiness
+import auditor.analyzers.languages.python.rules
+import auditor.analyzers.languages.javascript.rules
+import auditor.analyzers.languages.typescript.rules
+import auditor.analyzers.frameworks.fastapi
+import auditor.analyzers.frameworks.express
+import auditor.analyzers.frameworks.nestjs
+
+
+def ensure_analyzers_loaded() -> None:
+    """Ensure all analyzer and rule modules are imported and registered."""
+    pass

auditor/analyzers/frameworks/express/__init__.py

@@ -0,0 +1,145 @@
+"""Express framework analyzer and rules."""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+from auditor.analyzers.languages.javascript.parser import parse_js_file
+from auditor.core.analyzer import BaseAnalyzer
+from auditor.core.context import AnalysisContext
+from auditor.core.rule import BaseRule, RuleMetadata
+from auditor.core.severity import Category, Confidence, Severity
+from auditor.models import Finding
+from auditor.registry import register_analyzer, register_rule
+
+
+@register_rule
+class ExpressMissingErrorMiddlewareRule(BaseRule):
+    """Detects Express applications missing standard 4-argument error handling middleware."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            RuleMetadata(
+                rule_id="EXPRESS-001",
+                title="Missing global error handling middleware in Express",
+                category=Category.ERROR_HANDLING,
+                severity=Severity.HIGH,
+                confidence=Confidence.HIGH,
+                description="Express server registers routes but contains no 4-argument error-handling middleware (err, req, res, next).",
+                impact="Uncaught errors fall back to default HTML error pages, leaking internal stack traces or hanging client requests.",
+                recommendation="Register a centralized 4-parameter error handler at the end of the middleware chain.",
+                suggested_fix="app.use((err, req, res, next) => { logger.error(err); res.status(500).json({ error: 'Internal Server Error' }); });",
+                framework="express",
+                language="javascript",
+            )
+        )
+
+    def evaluate(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        js_files = context.get_files_for_language("javascript") + context.get_files_for_language(
+            "typescript"
+        )
+
+        has_routes = False
+        has_error_middleware = False
+        server_entry_file = None
+
+        for f in js_files:
+            data = context.get_js_structure(f) or parse_js_file(f)
+            context.set_js_structure(f, data)
+
+            if data.get("expressRoutes"):
+                has_routes = True
+            if data.get("expressErrorMiddleware"):
+                has_error_middleware = True
+
+            rel = context.get_relative_path(f).lower()
+            if any(
+                term in rel
+                for term in ["app.js", "server.js", "index.js", "app.ts", "server.ts", "index.ts"]
+            ):
+                server_entry_file = f
+
+        if has_routes and not has_error_middleware:
+            target_path = server_entry_file or (js_files[0] if js_files else context.root_path)
+            findings.append(
+                self.create_finding(
+                    file=context.get_relative_path(target_path),
+                    line=1,
+                    description="Express application defines routes but lacks a centralized (err, req, res, next) error handler.",
+                    evidence="No 4-parameter middleware registered across application files",
+                )
+            )
+        return findings
+
+
+@register_rule
+class ExpressAsyncRouteWithoutTryCatchRule(BaseRule):
+    """Detects async Express route handlers without try/catch or async handler wrapper."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            RuleMetadata(
+                rule_id="EXPRESS-003",
+                title="Async Express route handler without error handling",
+                category=Category.ERROR_HANDLING,
+                severity=Severity.HIGH,
+                confidence=Confidence.HIGH,
+                description="Express 4 async route handlers do not catch promise rejections automatically; unhandled errors hang connections indefinitely.",
+                impact="A thrown exception inside an async route handler leaves the client request hanging until socket timeout, exhausting server sockets.",
+                recommendation="Wrap the async handler with express-async-handler or enclose the body in try/catch calling next(err).",
+                suggested_fix="Wrap the handler with asyncHandler(async (req, res) => { ... }) or add try/catch.",
+                framework="express",
+                language="javascript",
+            )
+        )
+
+    def evaluate(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        js_files = context.get_files_for_language("javascript") + context.get_files_for_language(
+            "typescript"
+        )
+
+        for f in js_files:
+            lines = context.get_lines(f)
+            rel_file = context.get_relative_path(f)
+
+            for idx, line in enumerate(lines, start=1):
+                # Detect async handler registered directly on router or app
+                if re.search(
+                    r"""\b(?:app|router)\.(?:get|post|put|delete|patch)\s*\(\s*['"][^'"]+['"]\s*,\s*async\s*\(""",
+                    line,
+                ):
+                    # Check next 15 lines for try {
+                    next_lines = "".join(lines[idx : min(idx + 15, len(lines))])
+                    if "try" not in next_lines and "asyncHandler" not in line:
+                        findings.append(
+                            self.create_finding(
+                                file=rel_file,
+                                line=idx,
+                                description="Async route handler lacks try/catch or asyncHandler wrapper; unhandled rejections will hang requests.",
+                                evidence=line.strip(),
+                            )
+                        )
+        return findings
+
+
+@register_analyzer
+class ExpressFrameworkAnalyzer(BaseAnalyzer):
+    name = "express-framework"
+    description = "Framework analysis for Express.js: error middleware, async route safety, and middleware ordering"
+    framework = "express"
+
+    def get_rules(self) -> List[BaseRule]:
+        return [
+            ExpressMissingErrorMiddlewareRule(),
+            ExpressAsyncRouteWithoutTryCatchRule(),
+        ]
+
+    def analyze(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        for rule in self.get_rules():
+            if context.config.is_rule_enabled(rule.rule_id):
+                findings.extend(rule.evaluate(context))
+        return findings

auditor/analyzers/frameworks/fastapi/__init__.py

@@ -0,0 +1,160 @@
+"""FastAPI framework analyzer and rules."""
+
+from __future__ import annotations
+
+import ast
+from typing import List
+
+from auditor.core.analyzer import BaseAnalyzer
+from auditor.core.context import AnalysisContext
+from auditor.core.rule import BaseRule, RuleMetadata
+from auditor.core.severity import Category, Confidence, Severity
+from auditor.models import Finding
+from auditor.registry import register_analyzer, register_rule
+
+
+@register_rule
+class FastApiRawSqlInRouteRule(BaseRule):
+    """Detects direct raw SQL execution inside FastAPI route endpoints."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            RuleMetadata(
+                rule_id="FASTAPI-001",
+                title="Direct raw SQL execution inside route endpoint",
+                category=Category.ARCHITECTURE,
+                severity=Severity.HIGH,
+                confidence=Confidence.HIGH,
+                description="FastAPI endpoint directly executes raw SQL query strings instead of delegating to a repository or ORM service.",
+                impact="Violates separation of concerns, mixes HTTP transport with database schemas, and makes unit testing endpoints difficult.",
+                recommendation="Move database queries into a dedicated repository or service class injected via Depends().",
+                suggested_fix="Create a UserRepository and inject it into the route handler via Depends(get_user_repo).",
+                framework="fastapi",
+                language="python",
+            )
+        )
+
+    def evaluate(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        for py_file in context.get_files_for_language("python"):
+            tree = context.get_python_ast(py_file)
+            if not tree:
+                continue
+
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    # Check if decorated as router endpoint: @router.get/post/etc.
+                    is_endpoint = False
+                    for dec in node.decorator_list:
+                        if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute):
+                            if dec.func.attr in (
+                                "get",
+                                "post",
+                                "put",
+                                "delete",
+                                "patch",
+                                "api_route",
+                            ):
+                                is_endpoint = True
+                                break
+
+                    if is_endpoint:
+                        for child in ast.walk(node):
+                            if isinstance(child, ast.Call) and isinstance(
+                                child.func, ast.Attribute
+                            ):
+                                if child.func.attr in ("execute", "raw"):
+                                    if child.args:
+                                        first_arg = child.args[0]
+                                        is_raw_sql = False
+                                        if isinstance(
+                                            first_arg, (ast.Constant, ast.JoinedStr, ast.BinOp)
+                                        ):
+                                            is_raw_sql = True
+                                        elif isinstance(first_arg, ast.Name):
+                                            # Variable named query or sql, or lookup in function scope
+                                            if any(
+                                                term in first_arg.id.lower()
+                                                for term in ["query", "sql"]
+                                            ):
+                                                is_raw_sql = True
+                                        if is_raw_sql:
+                                            rel_file = context.get_relative_path(py_file)
+                                            findings.append(
+                                                self.create_finding(
+                                                    file=rel_file,
+                                                    line=child.lineno,
+                                                    description=f"Raw SQL execution inside route '{node.name}'.",
+                                                    evidence=f"db.{child.func.attr}(...) in @router endpoint",
+                                                )
+                                            )
+        return findings
+
+
+@register_rule
+class FastApiMissingResponseModelRule(BaseRule):
+    """Detects mutating route endpoints without response_model or status_code."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            RuleMetadata(
+                rule_id="FASTAPI-002",
+                title="Missing response_model on route endpoint",
+                category=Category.API_DESIGN,
+                severity=Severity.LOW,
+                confidence=Confidence.HIGH,
+                description="FastAPI route endpoint does not declare a response_model, bypassing automatic schema filtering and OpenAPI documentation.",
+                impact="Internal model fields (like hashed passwords or internal IDs) can be accidentally leaked to clients in responses.",
+                recommendation="Explicitly specify response_model=UserResponse in the router decorator.",
+                suggested_fix="@router.post('/users', response_model=UserResponse, status_code=201)",
+                framework="fastapi",
+                language="python",
+            )
+        )
+
+    def evaluate(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        for py_file in context.get_files_for_language("python"):
+            tree = context.get_python_ast(py_file)
+            if not tree:
+                continue
+
+            for node in ast.walk(tree):
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    for dec in node.decorator_list:
+                        if isinstance(dec, ast.Call) and isinstance(dec.func, ast.Attribute):
+                            if dec.func.attr in ("post", "put"):
+                                has_response_model = any(
+                                    kw.arg == "response_model" for kw in dec.keywords
+                                )
+                                if not has_response_model:
+                                    rel_file = context.get_relative_path(py_file)
+                                    findings.append(
+                                        self.create_finding(
+                                            file=rel_file,
+                                            line=node.lineno,
+                                            description=f"FastAPI mutating endpoint '{node.name}' has no response_model declared.",
+                                            evidence=f"@{dec.func.attr}(...) without response_model",
+                                        )
+                                    )
+        return findings
+
+
+@register_analyzer
+class FastApiFrameworkAnalyzer(BaseAnalyzer):
+    name = "fastapi-framework"
+    description = (
+        "Framework analysis for FastAPI: route boundaries, response models, and async hygiene"
+    )
+    framework = "fastapi"
+    language = "python"
+
+    def get_rules(self) -> List[BaseRule]:
+        return [FastApiRawSqlInRouteRule(), FastApiMissingResponseModelRule()]
+
+    def analyze(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        for rule in self.get_rules():
+            if context.config.is_rule_enabled(rule.rule_id):
+                findings.extend(rule.evaluate(context))
+        return findings

auditor/analyzers/frameworks/nestjs/__init__.py

@@ -0,0 +1,127 @@
+"""NestJS framework analyzer and rules."""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+from auditor.core.analyzer import BaseAnalyzer
+from auditor.core.context import AnalysisContext
+from auditor.core.rule import BaseRule, RuleMetadata
+from auditor.core.severity import Category, Confidence, Severity
+from auditor.models import Finding
+from auditor.registry import register_analyzer, register_rule
+
+
+@register_rule
+class NestJsMissingInjectableRule(BaseRule):
+    """Detects service classes in NestJS missing the @Injectable() decorator."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            RuleMetadata(
+                rule_id="NEST-001",
+                title="Service class missing @Injectable() decorator",
+                category=Category.PATTERNS,
+                severity=Severity.HIGH,
+                confidence=Confidence.HIGH,
+                description="NestJS service class is not decorated with @Injectable(), preventing the IoC container from managing its lifecycle.",
+                impact="NestJS cannot inject dependencies into this class or provide it to controllers, resulting in runtime DI resolution errors.",
+                recommendation="Add @Injectable() decorator above the service class declaration.",
+                suggested_fix="@Injectable()\nexport class UserService { ... }",
+                framework="nestjs",
+                language="typescript",
+            )
+        )
+
+    def evaluate(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        ts_files = context.get_files_for_language("typescript")
+
+        for f in ts_files:
+            rel_file = context.get_relative_path(f)
+            if not rel_file.endswith(".service.ts"):
+                continue
+
+            lines = context.get_lines(f)
+            has_injectable = any("@Injectable()" in line for line in lines)
+
+            for idx, line in enumerate(lines, start=1):
+                if re.search(r"""export\s+class\s+[a-zA-Z0-9_]+Service\b""", line):
+                    if not has_injectable:
+                        findings.append(
+                            self.create_finding(
+                                file=rel_file,
+                                line=idx,
+                                description=f"NestJS service in '{rel_file}' is missing @Injectable() decorator.",
+                                evidence=line.strip(),
+                            )
+                        )
+        return findings
+
+
+@register_rule
+class NestJsDirectDbInControllerRule(BaseRule):
+    """Detects direct database queries executed in NestJS @Controller()."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            RuleMetadata(
+                rule_id="NEST-002",
+                title="Direct database access inside NestJS controller",
+                category=Category.ARCHITECTURE,
+                severity=Severity.HIGH,
+                confidence=Confidence.HIGH,
+                description="NestJS controller directly accesses database models or ORM repositories rather than delegating to an injected service.",
+                impact="Breaks NestJS modular architecture, makes controllers tightly coupled to the database schema, and hampers testing.",
+                recommendation="Delegate database operations to an injected service class.",
+                suggested_fix="Inject UserService in the constructor and call this.userService.getUserById(id).",
+                framework="nestjs",
+                language="typescript",
+            )
+        )
+
+    def evaluate(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        ts_files = context.get_files_for_language("typescript")
+
+        for f in ts_files:
+            rel_file = context.get_relative_path(f)
+            if not rel_file.endswith(".controller.ts"):
+                continue
+
+            lines = context.get_lines(f)
+            for idx, line in enumerate(lines, start=1):
+                if re.search(
+                    r"""\b(?:this\.(?:repository|repo|prisma|dataSource)\.[a-zA-Z0-9_]+\s*\()""",
+                    line,
+                ):
+                    findings.append(
+                        self.create_finding(
+                            file=rel_file,
+                            line=idx,
+                            description=f"Direct database / ORM access inside controller in '{rel_file}'.",
+                            evidence=line.strip(),
+                        )
+                    )
+        return findings
+
+
+@register_analyzer
+class NestJsFrameworkAnalyzer(BaseAnalyzer):
+    name = "nestjs-framework"
+    description = (
+        "Framework analysis for NestJS: dependency injection, modules, and controller boundaries"
+    )
+    framework = "nestjs"
+    language = "typescript"
+
+    def get_rules(self) -> List[BaseRule]:
+        return [NestJsMissingInjectableRule(), NestJsDirectDbInControllerRule()]
+
+    def analyze(self, context: AnalysisContext) -> List[Finding]:
+        findings: List[Finding] = []
+        for rule in self.get_rules():
+            if context.config.is_rule_enabled(rule.rule_id):
+                findings.extend(rule.evaluate(context))
+        return findings

auditor/analyzers/languages/javascript/imports.py

@@ -0,0 +1,45 @@
+"""JavaScript and TypeScript import dependency graph populator."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict
+
+from auditor.analyzers.languages.javascript.parser import parse_js_file
+from auditor.core.context import AnalysisContext
+
+
+def populate_js_dependency_graph(context: AnalysisContext) -> None:
+    """Populate DependencyGraph using parsed JS and TS files."""
+    files = context.get_files_for_language("javascript") + context.get_files_for_language(
+        "typescript"
+    )
+
+    mod_to_file: Dict[str, Path] = {}
+    for f in files:
+        rel = context.get_relative_path(f)
+        # Normalize without extension
+        base_mod = rel
+        for ext in (".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"):
+            if base_mod.endswith(ext):
+                base_mod = base_mod[: -len(ext)]
+                break
+        mod_to_file[base_mod] = f
+        context.dependency_graph.get_or_create_node(base_mod, f, "javascript")
+
+    for base_mod, f in mod_to_file.items():
+        data = context.get_js_structure(f)
+        if not data:
+            data = parse_js_file(f)
+            context.set_js_structure(f, data)
+
+        for imp in data.get("imports", []):
+            mod_target = imp.get("module", "")
+            if mod_target.startswith("."):
+                # Relative import resolution
+                resolved = (f.parent / mod_target).resolve()
+                rel_resolved = context.get_relative_path(resolved)
+                for candidate_mod in mod_to_file.keys():
+                    if rel_resolved.startswith(candidate_mod):
+                        context.dependency_graph.add_dependency(base_mod, candidate_mod)
+                        break

auditor/analyzers/languages/javascript/parser.py

@@ -0,0 +1,113 @@
+"""JavaScript and TypeScript parsing bridge via Node.js helper with fallback."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Dict
+
+PARSER_SCRIPT = Path(__file__).parent / "js_ast_parser.js"
+
+
+def parse_js_file(file_path: Path) -> Dict[str, Any]:
+    """Parse JavaScript or TypeScript file into structured AST metadata."""
+    node_bin = shutil.which("node")
+    if node_bin and PARSER_SCRIPT.is_file():
+        try:
+            res = subprocess.run(
+                [node_bin, str(PARSER_SCRIPT), str(file_path.resolve())],
+                capture_output=True,
+                text=True,
+                timeout=8,
+                check=False,
+            )
+            if res.returncode == 0 and res.stdout.strip():
+                return json.loads(res.stdout)
+        except Exception:
+            pass
+
+    # High-fidelity fallback parser in pure Python
+    return _fallback_js_parser(file_path)
+
+
+def _fallback_js_parser(file_path: Path) -> Dict[str, Any]:
+    """Pure Python fallback parser extracting JS/TS structure."""
+    import re
+
+    result: Dict[str, Any] = {
+        "file": str(file_path),
+        "totalLines": 0,
+        "imports": [],
+        "exports": [],
+        "functions": [],
+        "blockingCalls": [],
+        "evalCalls": [],
+        "unhandledPromises": [],
+        "anyTypes": [],
+        "expressRoutes": [],
+        "expressErrorMiddleware": [],
+    }
+
+    try:
+        lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+        result["totalLines"] = len(lines)
+        for idx, line in enumerate(lines, start=1):
+            trimmed = line.strip()
+            if trimmed.startswith("//") or trimmed.startswith("/*") or trimmed.startswith("*"):
+                continue
+
+            # Imports
+            esm = re.search(r"""import\s+(?:(?:[\w*\s{},]+)\s+from\s+)?['"]([^'"]+)['"]""", line)
+            if esm:
+                result["imports"].append({"module": esm.group(1), "line": idx})
+            cjs = re.search(r"""require\s*\(\s*['"]([^'"]+)['"]\s*\)""", line)
+            if cjs:
+                result["imports"].append({"module": cjs.group(1), "line": idx})
+
+            # Blocking calls
+            if re.search(
+                r"""\b(?:fs\.readFileSync|fs\.writeFileSync|fs\.existsSync|crypto\.pbkdf2Sync|child_process\.execSync)\b""",
+                line,
+            ):
+                result["blockingCalls"].append({"line": idx, "text": trimmed})
+
+            # Eval calls
+            if re.search(r"""\b(?:eval\s*\(|new\s+Function\s*\()""", line):
+                result["evalCalls"].append({"line": idx, "text": trimmed})
+
+            # Any types
+            if re.search(r"""(?::\s*any\b|<any>|as\s+any\b)""", line):
+                result["anyTypes"].append({"line": idx, "text": trimmed})
+
+            # Unhandled promise
+            if re.search(r"""\.then\s*\(""", line) and ".catch" not in line:
+                result["unhandledPromises"].append({"line": idx, "text": trimmed})
+
+            # Express routes
+            route_m = re.search(
+                r"""\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]\s*,\s*(?:async\s*)?(?:\(([^)]*)\)|([a-zA-Z0-9_]+))""",
+                line,
+            )
+            if route_m:
+                result["expressRoutes"].append(
+                    {
+                        "method": route_m.group(1),
+                        "path": route_m.group(2),
+                        "isAsync": "async" in line,
+                        "line": idx,
+                    }
+                )
+
+            # Express 4-argument error middleware: (err, req, res, next)
+            if re.search(
+                r"""\b(?:app|router)\.use\s*\(\s*(?:async\s*)?\(\s*[\w$]+\s*,\s*[\w$]+\s*,\s*[\w$]+\s*,\s*[\w$]+\s*\)""",
+                line,
+            ):
+                result["expressErrorMiddleware"].append({"line": idx, "text": trimmed})
+
+    except Exception:
+        pass
+
+    return result