hackscan 0.1.0__py3-none-any.whl

hackscan/__init__.py

@@ -0,0 +1,3 @@
+"""HackScan: Python SAST orchestrator and verifier."""
+
+__version__ = "0.1.0"

hackscan/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Analysis passes."""

hackscan/analyzers/ast_pass.py

@@ -0,0 +1,154 @@
+"""Pass 1: run AST rule plugins over a file and emit candidate findings."""
+
+from __future__ import annotations
+
+import ast
+import io
+import tokenize
+import warnings
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from hackscan.analyzers.suppressions import apply_inline_suppressions
+from hackscan.analyzers.taint_pass import apply_taint
+from hackscan.core.models import OWN_SOURCE, Evidence, Finding, Region
+from hackscan.core.taxonomy import classify
+from hackscan.plugins.base import FileContext, Match, RulePlugin
+
+PRODUCER = "ast"
+
+
+@dataclass
+class FileResult:
+    path: str
+    findings: list[Finding] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def analyze_source(
+    source: str, rel_path: str, plugins: Sequence[RulePlugin], *, taint: bool = True
+) -> FileResult:
+    """Parse `source`, run every plugin (pass 1), then taint (pass 2) and inline
+    suppressions. Parse and plugin errors are reported, not raised."""
+    result = FileResult(path=rel_path)
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", SyntaxWarning)  # e.g. invalid escapes in scanned code
+            tree = ast.parse(source, filename=rel_path, type_comments=False)
+    except (SyntaxError, ValueError) as exc:
+        result.errors.append(f"{rel_path}: cannot parse: {exc}")
+        return result
+
+    ctx = FileContext(path=rel_path, source=source, tree=tree)
+    by_type: dict[type[ast.AST], list[RulePlugin]] = {}
+    for plugin in plugins:
+        for node_type in plugin.node_types:
+            by_type.setdefault(node_type, []).append(plugin)
+
+    qualnames = _qualnames(tree)
+    candidates: list[tuple[Finding, Match]] = []
+    for node in ast.walk(tree):
+        for plugin in by_type.get(type(node), ()):
+            try:
+                matches = list(plugin.check(node, ctx))
+            except Exception as exc:  # a broken rule must not abort the scan
+                line = getattr(node, "lineno", "?")
+                result.errors.append(f"{rel_path}:{line}: rule {plugin.rule_id} failed: {exc}")
+                continue
+            for match in matches:
+                try:
+                    candidates.append((_to_finding(match, plugin, ctx, qualnames), match))
+                except Exception as exc:  # malformed match from a (user) plugin
+                    line = getattr(node, "lineno", "?")
+                    result.errors.append(
+                        f"{rel_path}:{line}: rule {plugin.rule_id} returned a bad match: {exc}"
+                    )
+    findings = [f for f, _ in candidates]
+    if taint:
+        try:
+            findings = apply_taint(ctx, candidates)
+        except RecursionError:  # pathological nesting: keep pass-1 candidates
+            result.errors.append(f"{rel_path}: taint analysis skipped (nesting too deep)")
+    findings = apply_inline_suppressions(findings, ctx)
+    result.findings = sorted(findings, key=Finding.sort_key)
+    return result
+
+
+def analyze_file(
+    path: Path, root: Path, plugins: Sequence[RulePlugin], *, taint: bool = True
+) -> FileResult:
+    rel_path = path.relative_to(root).as_posix()
+    try:
+        data = path.read_bytes()
+        # Honors PEP 263 coding declarations and BOMs, defaulting to UTF-8.
+        encoding, _ = tokenize.detect_encoding(io.BytesIO(data).readline)
+        source = data.decode(encoding)
+    except (OSError, SyntaxError, UnicodeDecodeError, LookupError) as exc:
+        return FileResult(path=rel_path, errors=[f"{rel_path}: cannot read: {exc}"])
+    return analyze_source(source, rel_path, plugins, taint=taint)
+
+
+def _to_finding(
+    match: Match, plugin: RulePlugin, ctx: FileContext, qualnames: dict[int, str]
+) -> Finding:
+    node = match.node
+    if not isinstance(node, ast.AST) or not hasattr(node, "lineno"):
+        raise TypeError(f"match node must be a located AST node, got {type(node).__name__}")
+    start_line = node.lineno
+    end_line = node.end_lineno or start_line
+    region = Region(
+        path=ctx.path,
+        start_line=start_line,
+        start_column=ctx.char_column(start_line, node.col_offset),
+        end_line=end_line,
+        end_column=(
+            ctx.char_column(end_line, node.end_col_offset)
+            if node.end_col_offset is not None
+            else None
+        ),
+    )
+    func = ctx.enclosing_function(node)
+    sink = ctx.segment(node)
+    return Finding(
+        id="",
+        vuln_class=classify(plugin.rule_id, plugin.cwe),
+        rule_id=plugin.rule_id,
+        severity=plugin.severity,
+        location=region,
+        message=match.message,
+        snippet=_line_snippet(ctx, start_line, end_line),
+        sink=sink,
+        function=qualnames.get(id(func)) if func is not None else None,
+        cwe=plugin.cwe,
+        sources=(OWN_SOURCE,),
+        confidence=match.confidence if match.confidence is not None else plugin.default_confidence,
+        evidence=(Evidence(PRODUCER, "rule_match", f"{plugin.name}: {match.message}"),),
+    )
+
+
+def _line_snippet(ctx: FileContext, start: int, end: int, max_lines: int = 5) -> str:
+    lines = ctx.lines[start - 1 : min(end, start + max_lines - 1)]
+    return "\n".join(lines)
+
+
+def _qualnames(tree: ast.Module) -> dict[int, str]:
+    """Map id(function node) -> dotted qualname (`Class.method`, `outer.<locals>.inner`)."""
+    names: dict[int, str] = {}
+
+    def visit(node: ast.AST, prefix: str) -> None:
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                qual = f"{prefix}{child.name}"
+                names[id(child)] = qual
+                visit(child, f"{qual}.<locals>.")
+            elif isinstance(child, ast.ClassDef):
+                visit(child, f"{prefix}{child.name}.")
+            elif isinstance(child, ast.Lambda):
+                names[id(child)] = f"{prefix}<lambda>"
+                visit(child, prefix)
+            else:
+                visit(child, prefix)
+
+    visit(tree, "")
+    return names

hackscan/analyzers/suppressions.py

@@ -0,0 +1,63 @@
+"""Inline suppressions: `# hackscan: ignore` or `# hackscan: ignore[RULE, ...]`.
+
+The comment may sit on any line of the finding's region (start line for single-line
+calls, closing line for multi-line ones). Suppressed findings are kept, with
+`suppression = "inline:hackscan-ignore"`.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import tokenize
+from dataclasses import replace
+
+from hackscan.core.models import Evidence, Finding, Status
+from hackscan.plugins.base import FileContext
+
+INLINE = "inline:hackscan-ignore"
+_DIRECTIVE_RE = re.compile(r"#\s*hackscan:\s*ignore(?:\[(?P<rules>[^\]]*)\])?", re.IGNORECASE)
+
+
+def directives(source: str) -> dict[int, frozenset[str] | None]:
+    """Line -> rule ids to ignore (None = all rules). Only real comments count."""
+    out: dict[int, frozenset[str] | None] = {}
+    try:
+        tokens = tokenize.generate_tokens(io.StringIO(source).readline)
+        for tok in tokens:
+            if tok.type != tokenize.COMMENT:
+                continue
+            match = _DIRECTIVE_RE.search(tok.string)
+            if not match:
+                continue
+            rules = match.group("rules")
+            line = tok.start[0]
+            if rules is None:
+                out[line] = None
+            elif out.get(line, frozenset()) is not None:
+                parsed = frozenset(r.strip() for r in rules.split(",") if r.strip())
+                out[line] = (out.get(line) or frozenset()) | parsed
+    except (tokenize.TokenError, SyntaxError):
+        pass  # unparseable files have no findings anyway
+    return out
+
+
+def apply_inline_suppressions(findings: list[Finding], ctx: FileContext) -> list[Finding]:
+    marks = directives(ctx.source)
+    if not marks:
+        return findings
+    out = []
+    for f in findings:
+        lines = range(f.location.start_line, f.location.end_line + 1)
+        hit = any(
+            line in marks and (marks[line] is None or f.rule_id in marks[line]) for line in lines
+        )
+        if hit and f.status is not Status.SUPPRESSED:
+            f = replace(
+                f,
+                status=Status.SUPPRESSED,
+                suppression=INLINE,
+                evidence=(*f.evidence, Evidence("inline", "suppression", "Ignored by comment.")),
+            )
+        out.append(f)
+    return out