qaudit 1.0.0__py3-none-any.whl

qaudit/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.0"
+__author__ = "tsmishra"

qaudit/__main__.py

@@ -0,0 +1,4 @@
+from qaudit.cli import main
+
+if __name__ == "__main__":
+    main()

qaudit/ast_taint.py

@@ -0,0 +1,475 @@
+"""
+Intra-function taint analysis for Python using only stdlib ast.
+
+Algorithm
+---------
+For every FunctionDef / AsyncFunctionDef in a module:
+  1. Seed tainted variables from:
+       - function parameters (all args — positional, keyword, *args, **kwargs)
+       - assignments where the RHS is a known source expression
+       - extra_tainted set injected by the inter-procedural engine
+  2. Propagate taint through assignments (ordered statement walk):
+       - if any name on the RHS is tainted → LHS target is tainted
+       - if any name on the RHS is tainted AND the RHS contains a string
+         construction operation (BinOp +, JoinedStr f-string, % format,
+         .format(), str()) → LHS is also added to str_tainted
+  3. Flag when a tainted name reaches a sink call.
+
+.execute() — two-track SQL injection detection
+----------------------------------------------
+SQL injection requires a *string* to be the query argument (arg[0]).
+Two severity levels based on observed evidence:
+
+  HIGH   — tainted variable reached .execute() arg[0] AND passed through a
+            string construction op (concat, f-string, % format, .format(),
+            str()). This is proven SQL injection.
+
+  MEDIUM — tainted variable reached .execute() arg[0] with NO observed string
+            construction. The variable may be a raw string from user input
+            (still dangerous) but we have less evidence — worth investigating.
+
+  silent — tainted variable only appears in .execute() arg[1+] (the params
+            tuple). This is the correct parameterised query pattern; no finding.
+
+Sources (RHS patterns that seed taint)
+  - request.args.get / request.form.get / request.json / request.data
+  - request.GET.get / request.POST.get  (Django)
+  - os.environ.get / os.getenv
+  - input()
+  - sys.argv
+
+Sinks (calls / expressions that are dangerous with tainted input)
+  - eval(...)
+  - exec(...)
+  - os.system(...)
+  - os.popen(...)
+  - subprocess.call / run / Popen / check_output / check_call (any arg)
+  - .execute() — SQL injection (two-track, see above)
+  - compile(...)
+  - importlib.import_module(...)
+  - __import__(...)
+
+The engine returns a list of TaintFinding objects.
+"""
+from __future__ import annotations
+__author__ = "tsmishra"
+
+import ast
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Set
+
+
+@dataclass
+class TaintFinding:
+    file_path:    str
+    line_number:  int
+    sink:         str          # e.g. "eval()", "os.system()"
+    source_vars:  List[str]    # tainted variable names that reached the sink
+    code_snippet: str
+    confidence:   str = "high" # "high" | "medium" — used by .execute() two-track logic
+
+
+# ---------------------------------------------------------------------------
+# Source detection helpers
+# ---------------------------------------------------------------------------
+
+_SOURCE_CALLS: Set[str] = {
+    "input",
+    "request.args.get",
+    "request.form.get",
+    "request.json",
+    "request.data",
+    "request.GET.get",
+    "request.POST.get",
+    "os.environ.get",
+    "os.getenv",
+    "sys.argv",
+}
+
+
+def _attr_chain(node: ast.expr) -> str:
+    """
+    Return dotted attribute chain for simple Name/Attribute trees, else ''.
+
+    Author: tsmishra
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parent = _attr_chain(node.value)
+        if parent:
+            return f"{parent}.{node.attr}"
+    return ""
+
+
+def _is_source(node: ast.expr) -> bool:
+    """
+    True if the expression looks like a known taint source.
+
+    Author: tsmishra
+    """
+    chain = _attr_chain(node)
+    if chain in _SOURCE_CALLS:
+        return True
+    if isinstance(node, ast.Call):
+        return _is_source(node.func)
+    if isinstance(node, ast.Subscript):
+        return _is_source(node.value)
+    return False
+
+
+# ---------------------------------------------------------------------------
+# String-construction detection
+# ---------------------------------------------------------------------------
+
+def _is_string_construction(node: ast.expr, tainted: Set[str]) -> bool:
+    """
+    True if *node* builds a string that incorporates at least one tainted variable.
+
+    Detected patterns:
+      tainted + "literal"          BinOp with Add
+      f"...{tainted}..."           JoinedStr (f-string)
+      "literal" % tainted          BinOp with Mod
+      "literal".format(tainted)    Call to .format()
+      str(tainted)                 Call to str()
+
+    Author: tsmishra
+    """
+    if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Add, ast.Mod)):
+        return _expr_contains_tainted(node, tainted)
+
+    if isinstance(node, ast.JoinedStr):
+        return _expr_contains_tainted(node, tainted)
+
+    if isinstance(node, ast.Call):
+        func = node.func
+        # "...".format(tainted_var)
+        if isinstance(func, ast.Attribute) and func.attr == "format":
+            return any(_expr_contains_tainted(a, tainted) for a in node.args) or \
+                   any(_expr_contains_tainted(kw.value, tainted) for kw in node.keywords if kw.value)
+        # str(tainted_var)
+        if isinstance(func, ast.Name) and func.id == "str":
+            return any(_expr_contains_tainted(a, tainted) for a in node.args)
+
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Sink detection helpers
+# ---------------------------------------------------------------------------
+
+_SINK_NAMES: Dict[str, str] = {
+    "eval":       "eval()",
+    "exec":       "exec()",
+    "compile":    "compile()",
+    "__import__": "__import__()",
+}
+
+_SINK_ATTR_CHAINS: Dict[str, str] = {
+    "os.system":                "os.system()",
+    "os.popen":                 "os.popen()",
+    "subprocess.call":          "subprocess.call()",
+    "subprocess.run":           "subprocess.run()",
+    "subprocess.Popen":         "subprocess.Popen()",
+    "subprocess.check_output":  "subprocess.check_output()",
+    "subprocess.check_call":    "subprocess.check_call()",
+    "importlib.import_module":  "importlib.import_module()",
+}
+
+_SINK_METHOD_NAMES: Set[str] = {"execute"}
+
+
+def _sink_label(call_node: ast.Call) -> Optional[str]:
+    """Return human-readable sink label if this call is a known sink, else None."""
+    func = call_node.func
+    chain = _attr_chain(func)
+    if chain in _SINK_ATTR_CHAINS:
+        return _SINK_ATTR_CHAINS[chain]
+    if isinstance(func, ast.Name) and func.id in _SINK_NAMES:
+        return _SINK_NAMES[func.id]
+    if isinstance(func, ast.Attribute) and func.attr in _SINK_METHOD_NAMES:
+        return f".{func.attr}()"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Name collection helpers
+# ---------------------------------------------------------------------------
+
+def _names_in_expr(node: ast.expr) -> Set[str]:
+    """Collect all Name ids referenced in an expression."""
+    names: Set[str] = set()
+    for child in ast.walk(node):
+        if isinstance(child, ast.Name):
+            names.add(child.id)
+    return names
+
+
+def _expr_contains_tainted(node: ast.expr, tainted: Set[str]) -> bool:
+    return bool(_names_in_expr(node) & tainted)
+
+
+# ---------------------------------------------------------------------------
+# Core: ordered single-pass walk of one function body
+# ---------------------------------------------------------------------------
+
+def _walk_stmts_ordered(stmts: list) -> List[ast.stmt]:
+    """
+    Flatten a statement list into order-preserving depth-first sequence.
+
+    Author: tsmishra
+    """
+    result: List[ast.stmt] = []
+    for stmt in stmts:
+        result.append(stmt)
+        # Recurse into compound statement bodies to preserve order
+        for child_stmts in _child_stmt_lists(stmt):
+            result.extend(_walk_stmts_ordered(child_stmts))
+    return result
+
+
+def _child_stmt_lists(stmt: ast.stmt) -> List[list]:
+    """Return the child statement lists of a compound statement."""
+    out: List[list] = []
+    for attr in ("body", "orelse", "handlers", "finalbody"):
+        val = getattr(stmt, attr, None)
+        if val and isinstance(val, list):
+            # handlers are ExceptHandler nodes, not stmt lists
+            for item in val:
+                if isinstance(item, ast.ExceptHandler):
+                    out.append(item.body)
+                elif isinstance(item, ast.stmt):
+                    out.append([item])
+                elif isinstance(item, list):
+                    out.append(item)
+            if all(isinstance(item, ast.stmt) for item in val):
+                out.append(val)
+    return out
+
+
+def _propagate(
+    func_ast: ast.FunctionDef | ast.AsyncFunctionDef,
+    tainted: Set[str],
+    source_lines: List[str],
+    file_path: str,
+) -> List[TaintFinding]:
+    """
+    Single-pass ordered walk of func_ast.body.
+    Mutates *tainted* in place (general taint propagation).
+    Also maintains *str_tainted*: variables that are tainted AND have passed
+    through a string construction operation — used for .execute() HIGH vs MEDIUM.
+    Returns TaintFinding list.
+
+    Author: tsmishra
+    """
+    findings: List[TaintFinding] = []
+    str_tainted: Set[str] = set()
+
+    for stmt in _walk_stmts_ordered(func_ast.body):
+        # ------------------------------------------------------------------
+        # Assignment propagation
+        # ------------------------------------------------------------------
+        if isinstance(stmt, ast.Assign):
+            rhs_tainted = _expr_contains_tainted(stmt.value, tainted) or _is_source(stmt.value)
+            if rhs_tainted:
+                is_str_op = _is_string_construction(stmt.value, tainted)
+                for target in stmt.targets:
+                    for n in ast.walk(target):
+                        if isinstance(n, ast.Name):
+                            tainted.add(n.id)
+                            if is_str_op:
+                                str_tainted.add(n.id)
+            # Sink inside RHS call: x = eval(tainted)
+            if isinstance(stmt.value, ast.Call):
+                _check_call(stmt.value, tainted, str_tainted, findings, source_lines, file_path)
+
+        elif isinstance(stmt, ast.AnnAssign):
+            if stmt.value:
+                rhs_tainted = _expr_contains_tainted(stmt.value, tainted) or _is_source(stmt.value)
+                if rhs_tainted and isinstance(stmt.target, ast.Name):
+                    tainted.add(stmt.target.id)
+                    if _is_string_construction(stmt.value, tainted):
+                        str_tainted.add(stmt.target.id)
+                if isinstance(stmt.value, ast.Call):
+                    _check_call(stmt.value, tainted, str_tainted, findings, source_lines, file_path)
+
+        elif isinstance(stmt, ast.AugAssign):
+            if _expr_contains_tainted(stmt.value, tainted):
+                if isinstance(stmt.target, ast.Name):
+                    tainted.add(stmt.target.id)
+                    if _is_string_construction(stmt.value, tainted):
+                        str_tainted.add(stmt.target.id)
+
+        # ------------------------------------------------------------------
+        # Sink calls as expression statements
+        # ------------------------------------------------------------------
+        elif isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+            _check_call(stmt.value, tainted, str_tainted, findings, source_lines, file_path)
+
+        # Sink inside return expr: return eval(tainted)
+        elif isinstance(stmt, ast.Return) and stmt.value:
+            if isinstance(stmt.value, ast.Call):
+                _check_call(stmt.value, tainted, str_tainted, findings, source_lines, file_path)
+
+    return findings
+
+
+def _check_call(
+    call_node: ast.Call,
+    tainted: Set[str],
+    str_tainted: Set[str],
+    findings: List[TaintFinding],
+    source_lines: List[str],
+    file_path: str,
+) -> None:
+    label = _sink_label(call_node)
+    if label is None:
+        return
+
+    is_execute = label == ".execute()"
+
+    if is_execute:
+        # SQL injection logic — only flag when string construction is provably observed.
+        #
+        # arg[0] is the query position. arg[1+] is the params slot (safe pattern).
+        #
+        # HIGH — string construction evidence exists:
+        #   (a) arg[0] itself IS a string construction expression (inline f-string,
+        #       concat, %-format, .format(), str()) that incorporates a tainted var.
+        #   (b) arg[0] is a variable that was previously assigned via string
+        #       construction from a tainted source (tracked in str_tainted).
+        #
+        # silent — no string construction evidence, OR taint only in arg[1+].
+        #
+        # Rationale: .execute() is a common method name (Chain of Responsibility,
+        # command patterns, task runners, workflow engines). Without type inference
+        # we cannot know if the receiver is a DB cursor. Requiring string construction
+        # evidence eliminates false positives from non-SQL .execute() calls while
+        # still catching the dangerous patterns that matter.
+        query_arg = call_node.args[0] if call_node.args else None
+        if query_arg is None:
+            return
+
+        arg0_names = _names_in_expr(query_arg)
+
+        # (a) inline string construction in arg[0] itself
+        inline_str_construction = _is_string_construction(query_arg, tainted)
+        # (b) arg[0] names a variable built via string construction earlier
+        prior_str_tainted = arg0_names & str_tainted
+
+        if inline_str_construction:
+            tainted_args = sorted(arg0_names & tainted)
+        elif prior_str_tainted:
+            tainted_args = sorted(prior_str_tainted)
+        else:
+            return  # no string construction evidence — silent
+
+        confidence = "high"
+
+    else:
+        # All other sinks: flag any tainted arg in any position
+        tainted_args: List[str] = []
+        for arg in call_node.args:
+            hits = _names_in_expr(arg) & tainted
+            tainted_args.extend(sorted(hits))
+        for kw in call_node.keywords:
+            if kw.value:
+                hits = _names_in_expr(kw.value) & tainted
+                tainted_args.extend(sorted(hits))
+        if not tainted_args:
+            return
+        confidence = "high"
+
+    lineno = call_node.lineno
+    snippet = source_lines[lineno - 1].rstrip() if lineno <= len(source_lines) else ""
+    findings.append(TaintFinding(
+        file_path=file_path,
+        line_number=lineno,
+        sink=label,
+        source_vars=list(dict.fromkeys(tainted_args)),
+        code_snippet=snippet,
+        confidence=confidence,
+    ))
+
+
+# ---------------------------------------------------------------------------
+# Public: analyse a single function AST node with optional extra taint seeds
+# ---------------------------------------------------------------------------
+
+def analyse_function_ast(
+    func_ast: ast.FunctionDef | ast.AsyncFunctionDef,
+    source_lines: List[str],
+    file_path: str,
+    extra_tainted: Optional[Set[str]] = None,
+) -> tuple[List[TaintFinding], Set[str]]:
+    """
+    Analyse *func_ast* and return (findings, final_tainted_set).
+
+    extra_tainted: additional variable names to pre-seed as tainted.
+    The returned tainted set is used by the inter-procedural engine to
+    determine whether a `return` propagates taint to the caller.
+
+    Author: tsmishra
+    """
+    args = func_ast.args
+    tainted: Set[str] = set()
+    for arg in args.args + args.posonlyargs + args.kwonlyargs:
+        tainted.add(arg.arg)
+    if args.vararg:
+        tainted.add(args.vararg.arg)
+    if args.kwarg:
+        tainted.add(args.kwarg.arg)
+    if extra_tainted:
+        tainted.update(extra_tainted)
+
+    findings = _propagate(func_ast, tainted, source_lines, file_path)
+    return findings, tainted
+
+
+def can_return_tainted(
+    func_ast: ast.FunctionDef | ast.AsyncFunctionDef,
+    tainted: Set[str],
+) -> bool:
+    """
+    True if any `return <expr>` in the function references a tainted variable.
+    Used by the inter-procedural engine to propagate taint through return values.
+
+    Author: tsmishra
+    """
+    for node in ast.walk(func_ast):
+        if isinstance(node, ast.Return) and node.value is not None:
+            if _expr_contains_tainted(node.value, tainted):
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Public: analyse a single file (intra-function only — legacy entry point)
+# ---------------------------------------------------------------------------
+
+def analyse_file(file_path: str) -> List[TaintFinding]:
+    """
+    Parse *file_path* and return all intra-function taint findings.
+
+    Author: tsmishra
+    """
+    try:
+        with open(file_path, encoding="utf-8", errors="replace") as fh:
+            source = fh.read()
+    except OSError:
+        return []
+
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return []
+
+    source_lines = source.splitlines()
+    findings: List[TaintFinding] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            fn_findings, _ = analyse_function_ast(node, source_lines, file_path)
+            findings.extend(fn_findings)
+
+    return findings