fenceline 1.0.2__py3-none-any.whl

fenceline/__init__.py

@@ -0,0 +1,12 @@
+"""Zero-day security scanner for the Boti workspace.
+
+Maps findings to the CWE Top 25 (2025), OWASP Top 10:2025, and known Python
+zero-day exploit patterns. See :mod:`fenceline.cli` for the CLI entry point
+and :mod:`fenceline.checks` for the check registry.
+"""
+
+from __future__ import annotations
+
+from fenceline.cli import main
+
+__all__ = ["main"]

fenceline/ast_helpers.py

@@ -0,0 +1,174 @@
+"""AST and text-matching helpers shared by the check functions in
+:mod:`fenceline.checks`.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+
+__all__ = [
+    "_LOGGING_METHOD_NAMES",
+    "_LOG_METHOD_CALL_RE",
+    "_LOG_METHOD_CALL_ANY_RE",
+    "_LOG_NAME_TOKENS",
+    "_NESTED_SCOPE_TYPES",
+    "_call_name",
+    "_full_attr",
+    "_is_re_compile",
+    "_is_sqlalchemy_compile",
+    "_has_dynamic_arg",
+    "_node_line",
+    "_has_log_like_token",
+    "_walk_skip_nested_scopes",
+    "_handler_has_diagnostic",
+    "_skip",
+]
+
+# Logging method names shared by every check that needs to recognize a
+# logging call (CWE-778 diagnostic detection, CWE-117 log injection,
+# CWE-532 log secrets). Defined once so these checks can never independently
+# drift out of sync with each other on which method names count as logging.
+_LOGGING_METHOD_NAMES = frozenset(
+    {"debug", "info", "warning", "warn", "error", "critical", "exception", "log"}
+)
+
+# Derived from _LOGGING_METHOD_NAMES (not a second hand-typed list) — matches
+# a logging call whose argument is an f-string, e.g. `logger.error(f"...")`.
+_LOG_METHOD_CALL_RE = re.compile(
+    r"\.(?:" + "|".join(re.escape(name) for name in _LOGGING_METHOD_NAMES) + r')\s*\(\s*f["\']'
+)
+
+# Same method-name set, without the f-string requirement — for checks (e.g.
+# check_log_secrets) that need to detect any logging call regardless of the
+# argument's literal form.
+_LOG_METHOD_CALL_ANY_RE = re.compile(
+    r"\.(?:" + "|".join(re.escape(name) for name in _LOGGING_METHOD_NAMES) + r")\s*\("
+)
+
+# Word-level tokens (not raw substrings) that mark a bare function call as
+# logging-related, e.g. `_log(logger, "debug", ...)` or `log_error(...)`.
+# Matching on whole '.'/'_'-delimited tokens rather than a raw substring test
+# avoids false positives on unrelated names that merely end in "...log" with
+# no delimiter — `catalog.get()`, `dialog.close()`, `backlog.append()`, and
+# `analog_signal.process()` all contain the substring "log" but are not
+# logging calls; none of them tokenize to a standalone "log"-family word.
+_LOG_NAME_TOKENS = frozenset({"log", "logs", "logger", "logging"})
+
+# AST node types that introduce a new, separately-executed scope. A statement
+# merely *defined* inside one of these (a nested function/lambda/class body)
+# does not run when the enclosing except block runs, so diagnostics found
+# there don't count as the handler having one.
+_NESTED_SCOPE_TYPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
+
+
+def _call_name(node: ast.Call) -> str:
+    if isinstance(node.func, ast.Name):
+        return node.func.id
+    if isinstance(node.func, ast.Attribute):
+        return node.func.attr
+    return ""
+
+
+def _full_attr(node: ast.Call) -> str:
+    parts: list[str] = []
+    cur = node.func
+    while isinstance(cur, ast.Attribute):
+        parts.append(cur.attr)
+        cur = cur.value
+    if isinstance(cur, ast.Name):
+        parts.append(cur.id)
+    parts.reverse()
+    return ".".join(parts)
+
+
+def _is_re_compile(node: ast.Call) -> bool:
+    name = _full_attr(node)
+    return (
+        name
+        in (
+            "re.compile",
+            "re.compile",
+        )
+        or _call_name(node) == "compile"
+        and isinstance(node.func, ast.Attribute)
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "re"
+    )
+
+
+def _is_sqlalchemy_compile(node: ast.Call) -> bool:
+    name = _full_attr(node)
+    return "compile" in name and any(x in name for x in ("statement", "query", "select", "sql"))
+
+
+def _has_dynamic_arg(node: ast.Call) -> bool:
+    """Check if any positional or keyword argument to a call is dynamic (not a constant)."""
+    for arg in node.args:
+        if not isinstance(arg, (ast.Constant, ast.Str, ast.Num, ast.NameConstant)):
+            return True
+    for kw in node.keywords:
+        if not isinstance(kw.value, (ast.Constant, ast.Str, ast.Num, ast.NameConstant)):
+            return True
+    return False
+
+
+def _node_line(node: ast.AST) -> int:
+    return getattr(node, "lineno", 0)
+
+
+def _has_log_like_token(full_name: str) -> bool:
+    """True if any ``.``/``_``-delimited token in *full_name* is a
+    logging-related word, e.g. ``"log"`` or ``"logger"`` — not merely present
+    as a substring somewhere inside a longer, unrelated word.
+    """
+    tokens = re.split(r"[._]+", full_name.lower())
+    return any(tok in _LOG_NAME_TOKENS for tok in tokens if tok)
+
+
+def _walk_skip_nested_scopes(node: ast.AST):
+    """Like ``ast.walk()``, but does not descend into nested function/lambda/
+    class bodies — see ``_NESTED_SCOPE_TYPES`` for why.
+
+    Checks *node itself* (not just its children) against ``_NESTED_SCOPE_TYPES``
+    before recursing, so this is correct both when a scope-creating node is
+    reached via recursion from a wrapping statement (e.g. a ``Lambda`` inside
+    an ``Assign``) and when it *is* the starting node passed in directly (e.g.
+    a top-level ``def`` statement in the handler body being walked itself).
+    """
+    yield node
+    if isinstance(node, _NESTED_SCOPE_TYPES):
+        return
+    for child in ast.iter_child_nodes(node):
+        yield from _walk_skip_nested_scopes(child)
+
+
+def _handler_has_diagnostic(handler: ast.ExceptHandler) -> bool:
+    """True if an ``except`` block logs, re-raises, or otherwise surfaces the
+    exception rather than silently swallowing it.
+
+    Looks for: a call whose attribute name is a logging method (``logger.debug(...)``,
+    ``self.logger.error(...)``); a bare function call whose name tokenizes to a
+    logging-related word (catches helper wrappers like ``_log(logger, "debug", ...)``
+    without false-positiving on unrelated names like ``catalog``/``dialog``); ``warnings.warn(...)``;
+    or a ``raise`` statement anywhere in the block (including nested ``if``/``try``,
+    but not inside a nested function/lambda/class body — code merely defined there
+    doesn't run as part of this handler). Walks the whole subtree, not just
+    top-level statements, so a diagnostic inside a nested block still counts.
+    """
+    for stmt in handler.body:
+        for node in _walk_skip_nested_scopes(stmt):
+            if isinstance(node, ast.Raise):
+                return True
+            if not isinstance(node, ast.Call):
+                continue
+            if isinstance(node.func, ast.Attribute) and node.func.attr in _LOGGING_METHOD_NAMES:
+                return True
+            full = _full_attr(node)
+            if full == "warnings.warn" or _has_log_like_token(full):
+                return True
+    return False
+
+
+def _skip(line: str) -> bool:
+    return line.strip().startswith("#")

fenceline/baseline.py

@@ -0,0 +1,48 @@
+"""Baseline support: snapshot current findings so a later scan only reports
+and fails on *new* findings, letting an existing codebase adopt fenceline
+without having to fix every pre-existing finding on day one.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fenceline.models import Finding
+
+__all__ = ["write_baseline", "load_baseline", "split_by_baseline"]
+
+Fingerprint = tuple[str, str, str]
+
+
+def _fingerprint(f: Finding) -> Fingerprint:
+    # (cwe_id, file, code_snippet) -- deliberately not line number, so the
+    # baseline still matches after unrelated edits elsewhere in the file
+    # shift line numbers.
+    return (f.cwe_id, f.file, f.code_snippet)
+
+
+def write_baseline(findings: list[Finding], path: Path) -> None:
+    fingerprints = sorted({_fingerprint(f) for f in findings})
+    data = {"fingerprints": [list(fp) for fp in fingerprints]}
+    path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def load_baseline(path: Path) -> set[Fingerprint]:
+    data = json.loads(path.read_text())
+    return {tuple(fp) for fp in data.get("fingerprints", [])}
+
+
+def split_by_baseline(
+    findings: list[Finding], baseline: set[Fingerprint]
+) -> tuple[list[Finding], int]:
+    """Returns ``(new_findings, suppressed_count)`` -- a finding whose
+    fingerprint is already in *baseline* is pre-existing debt, not new."""
+    new: list[Finding] = []
+    suppressed = 0
+    for f in findings:
+        if _fingerprint(f) in baseline:
+            suppressed += 1
+        else:
+            new.append(f)
+    return new, suppressed

fenceline/checks/__init__.py

@@ -0,0 +1,177 @@
+"""Aggregates every check function into a single ordered CHECKS registry.
+
+Each entry is ``(display_name, check_fn)``; ``check_fn`` receives
+``(path, lines, tree)`` and returns ``list[Finding]``. See
+:mod:`fenceline.checks.ast_checks`, :mod:`fenceline.checks.text_checks`,
+and :mod:`fenceline.checks.manifest_checks` for the implementations.
+
+Third-party packages can register additional checks without touching this
+file, by declaring an entry point in the ``fenceline.checks`` group in their
+own ``pyproject.toml``::
+
+    [project.entry-points."fenceline.checks"]
+    "My Custom Check (CWE-000)" = "my_package.checks:my_check_function"
+
+The entry point's own name is used as the check's display name; the object
+it loads must be a check function with the same ``(path, lines, tree) ->
+list[Finding]`` signature every built-in check has. Built-in checks are
+*not* themselves routed through entry points -- there's no benefit to
+indirecting checks fenceline ships with itself through a discovery
+mechanism meant for external extension, the same way pytest's own built-in
+behavior isn't implemented as a "plugin" of itself even though third-party
+pytest plugins use exactly that mechanism.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from importlib.metadata import entry_points
+
+from fenceline.checks.ast_checks import (
+    check_decode_exec_chains,
+    check_eval_exec,
+    check_except_pass,
+    check_format_string,
+    check_huggingface_unsafe_download,
+    check_insecure_default,
+    check_insecure_random,
+    check_insufficient_logging,
+    check_numpy_load,
+    check_pandas_eval,
+    check_parquet_arrow_deserialize,
+    check_request_timeout,
+    check_torch_load,
+)
+from fenceline.checks.manifest_checks import (
+    check_dependency_cve,
+    check_unbounded_pins,
+)
+from fenceline.checks.text_checks import (
+    check_arbitrary_write,
+    check_assert_security,
+    check_bind_all_interfaces,
+    check_command_injection,
+    check_crlf,
+    check_debug_mode,
+    check_exec_driver_sql,
+    check_hardcoded_secrets,
+    check_hardcoded_tokens,
+    check_ldap,
+    check_legacy_pycrypto,
+    check_log_injection,
+    check_log_secrets,
+    check_model_file_load,
+    check_null_byte,
+    check_numpy_load_lib,
+    check_open_redirect,
+    check_pandas_pickle,
+    check_pandas_xml_xxe,
+    check_path_traversal,
+    check_pickle,
+    check_pth_startup_hooks,
+    check_redos,
+    check_resource_limits,
+    check_sensitive_exposure,
+    check_sql_injection,
+    check_ssh_host_key,
+    check_ssrf,
+    check_ssti,
+    check_supply_chain,
+    check_symlink,
+    check_tempfile,
+    check_timing_attack,
+    check_tls_verify,
+    check_trojan_source,
+    check_weak_crypto,
+    check_weak_hash,
+    check_weak_tls_version,
+    check_xxe,
+    check_yaml_deserialize,
+    check_zipslip,
+)
+from fenceline.models import Finding
+
+__all__ = ["CHECKS"]
+
+CheckFn = Callable[..., list[Finding]]
+
+_BUILTIN_CHECKS: list[tuple[str, CheckFn]] = [
+    ("Pickle Deserialization (CWE-502)", check_pickle),
+    ("eval/exec/compile Injection (CWE-94)", check_eval_exec),
+    ("Command Injection (CWE-78)", check_command_injection),
+    ("SQL Injection (CWE-89)", check_sql_injection),
+    ("Path Traversal (CWE-22)", check_path_traversal),
+    ("Hardcoded Secrets (CWE-798)", check_hardcoded_secrets),
+    ("YAML Unsafe Deserialization (CWE-502)", check_yaml_deserialize),
+    ("XXE (CWE-611)", check_xxe),
+    ("SSRF (CWE-918)", check_ssrf),
+    ("Insecure Temp File (CWE-377)", check_tempfile),
+    ("Symlink Following (CWE-61)", check_symlink),
+    ("ReDoS (CWE-1333)", check_redos),
+    ("Assert Security (CWE-617/670)", check_assert_security),
+    ("exec_driver_sql Safety (CWE-89)", check_exec_driver_sql),
+    ("Supply Chain Dep Confusion (CWE-1104)", check_supply_chain),
+    ("Active Debug Code (CWE-489)", check_debug_mode),
+    ("Insufficient Logging (CWE-778)", check_insufficient_logging),
+    ("Timing Attack (CWE-208)", check_timing_attack),
+    ("Sensitive Exposure (CWE-200)", check_sensitive_exposure),
+    ("NUL Byte Injection (CWE-158)", check_null_byte),
+    ("Resource Limits (CWE-770)", check_resource_limits),
+    ("Insecure Random (CWE-338)", check_insecure_random),
+    ("SSTI (CWE-1336)", check_ssti),
+    ("CRLF Injection (CWE-93)", check_crlf),
+    ("LDAP Injection (CWE-90)", check_ldap),
+    ("Weak Hash (CWE-328)", check_weak_hash),
+    ("Open Redirect (CWE-601)", check_open_redirect),
+    ("Log Injection (CWE-117)", check_log_injection),
+    ("Format String (CWE-134)", check_format_string),
+    ("Arbitrary File Write (CWE-73)", check_arbitrary_write),
+    ("Insecure Default (CWE-453)", check_insecure_default),
+    ("Log Secrets (CWE-532)", check_log_secrets),
+    ("Disabled TLS Verify (CWE-295)", check_tls_verify),
+    ("ZipSlip / TarSlip (CWE-22)", check_zipslip),
+    ("Hardcoded API Keys (CWE-798)", check_hardcoded_tokens),
+    ("Weak Crypto (CWE-327)", check_weak_crypto),
+    ("Dependency CVE Scan (CWE-1104)", check_dependency_cve),
+    ("Trojan Source (CWE-1007)", check_trojan_source),
+    ("HTTP Request Timeout (CWE-1088)", check_request_timeout),
+    ("torch.load weights_only (CWE-502)", check_torch_load),
+    ("SSH Host Key Verification (CWE-322)", check_ssh_host_key),
+    ("except:pass/continue (CWE-391)", check_except_pass),
+    ("pandas eval/query Code Injection (CWE-94)", check_pandas_eval),
+    ("numpy.load allow_pickle (CWE-502)", check_numpy_load),
+    ("pandas.read_pickle (CWE-502)", check_pandas_pickle),
+    ("numpy.load library injection (CWE-114)", check_numpy_load_lib),
+    ("pandas.read_xml XXE (CWE-611)", check_pandas_xml_xxe),
+    (".pth Startup Hooks (CWE-829 / T1546.018)", check_pth_startup_hooks),
+    ("Parquet Arrow Deserialization (CWE-502 / CVE-2026-41486)", check_parquet_arrow_deserialize),
+    ("Unbounded Dependency Pins (CWE-1104)", check_unbounded_pins),
+    ("ML Model File Loading (OWASP ML06 / CWE-502)", check_model_file_load),
+    ("Decode-then-Execute Chains (CWE-94)", check_decode_exec_chains),
+    ("Binding to All Interfaces (CWE-1327)", check_bind_all_interfaces),
+    ("Weak TLS Protocol Version (CWE-326)", check_weak_tls_version),
+    ("Legacy PyCrypto Import (CWE-1104)", check_legacy_pycrypto),
+    ("HuggingFace Unsafe Download (OWASP ML06 / B615)", check_huggingface_unsafe_download),
+]
+
+_PLUGIN_GROUP = "fenceline.checks"
+
+
+def _discover_plugin_checks() -> list[tuple[str, CheckFn]]:
+    """Loads third-party checks registered under the ``fenceline.checks``
+    entry-point group. A plugin that fails to import is skipped with a
+    warning rather than crashing the whole tool -- one broken third-party
+    package shouldn't take down scanning for everyone else."""
+    discovered: list[tuple[str, CheckFn]] = []
+    for ep in entry_points(group=_PLUGIN_GROUP):
+        try:
+            check_fn = ep.load()
+        except Exception as exc:
+            print(f"  ⚠ fenceline: failed to load plugin check {ep.name!r}: {exc}", file=sys.stderr)
+            continue
+        discovered.append((ep.name, check_fn))
+    return discovered
+
+
+CHECKS: list[tuple[str, CheckFn]] = _BUILTIN_CHECKS + _discover_plugin_checks()