fenceline 1.0.2__tar.gz

fenceline-1.0.2/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: fenceline
+Version: 1.0.2
+Summary: Zero-day security scanner for the Boti workspace
+Author: Luis Valverde
+Maintainer-email: Luis Valverde <lvalverdeb@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lvalverdeb/fenceline
+Project-URL: Repository, https://github.com/lvalverdeb/fenceline
+Project-URL: Documentation, https://github.com/lvalverdeb/fenceline#readme
+Project-URL: Issues, https://github.com/lvalverdeb/fenceline/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: boti>=1.0.0
+
+# fenceline
+
+Zero-day security scanner for the Boti workspace.
+
+## Installation
+
+```bash
+uv add fenceline
+```
+
+Maps every finding to a CWE from the 2025 CWE Top 25, OWASP Top 10:2025, and known
+Python zero-day exploit patterns (pickle bypass CVE-2026-56315, PyYAML shadow
+vulnerability CVE-2026-24009, LangChain SSTI CVE-2025-68664, dependency confusion
+CVE-2025-61774, and more — see the CWE reference printed at the end of every
+text-mode report). 56 checks total: most are AST-based (won't false-positive on a
+dangerous call mentioned in a docstring or comment); the rest are line-regex checks
+for surface-syntax patterns that don't need full parsing.
+
+## Usage
+
+```bash
+uv run fenceline
+uv run fenceline --json > report.json
+uv run fenceline -q
+uv run fenceline --fail-on critical
+uv run fenceline --package my-lib=my-lib/src/my_lib
+```
+
+Exit codes: `0` (no findings at or above `--fail-on`), `1` (one or more).
+
+### Options
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--json` | off | Machine-readable output |
+| `--quiet` / `-q` | off | Suppress the banner |
+| `--fail-on` | `high` | Severity threshold (`critical`\|`high`\|`medium`\|`low`\|`info`) for the exit code |
+| `--confidence-min` | `low` | Drop findings below this confidence (`high`\|`medium`\|`low`) |
+| `--package NAME=PATH` | — | Add or override a scan target package (repeatable) |
+| `--baseline PATH` | — | Only report/fail on findings not already present in this baseline |
+| `--write-baseline PATH` | — | Snapshot current findings to PATH and exit 0 |
+
+By default, fenceline scans `boti`, `boti-data`, `boti-dask`, and itself.
+
+### Severity vs. confidence
+
+Every finding carries two independent ratings, the same distinction Bandit
+makes: **severity** is how bad it would be if the finding is real; **confidence**
+is how sure the check is that it *is* real. An AST-based check that matched a
+real `Call` node is `HIGH` confidence; a line-regex check that can't fully
+rule out a docstring or string-literal mention is `MEDIUM`; a handful of
+inherently heuristic checks (timing-attack keyword proximity, ReDoS
+backtracking-risk judgment, `debug=True` pattern matching) are `LOW`. Use
+`--confidence-min medium` to cut noise from the fuzzier checks without
+raising your severity bar.
+
+### Baselining an existing codebase
+
+Adopting fenceline on a codebase with existing findings doesn't mean fixing
+all of them before CI can pass:
+
+```bash
+uv run fenceline --write-baseline fenceline-baseline.json   # snapshot today's findings
+uv run fenceline --baseline fenceline-baseline.json          # only new findings fail CI
+```
+
+A finding is matched against the baseline by `(cwe_id, file, code_snippet)`,
+not line number, so it keeps matching across unrelated edits that shift line
+numbers elsewhere in the file. Re-run `--write-baseline` periodically (or
+whenever a baselined finding is deliberately fixed) to keep it current.
+
+### Suppressing a specific finding
+
+`# nosec` (bare) suppresses every finding on that line; `# nosec CWE-502`
+suppresses only that CWE, leaving any other finding on the same line intact
+— the same convention Bandit uses, with CWE IDs instead of Bandit's own
+B-numbers:
+
+```python
+pickle.loads(data)  # nosec CWE-502 -- trusted internal cache, not user input
+```
+
+### Extending fenceline with your own checks
+
+Built-in checks aren't dynamically discovered — they're a fixed list. Your
+own checks are, via a `fenceline.checks` entry point in *your own*
+`pyproject.toml`:
+
+```toml
+[project.entry-points."fenceline.checks"]
+"My Custom Check (CWE-000)" = "my_package.checks:my_check_function"
+```
+
+The entry point's own name becomes the check's display name; the object it
+points at must be a function with the same `(path, lines, tree) ->
+list[Finding]` signature every built-in check has. A plugin that fails to
+import is skipped with a warning rather than crashing the whole scan.
+
+## Design
+
+- `fenceline.models` — the `Finding` dataclass, severity ordering, and confidence ordering.
+- `fenceline.config` — workspace-root discovery and the default package registry.
+- `fenceline.ast_helpers` — shared AST/text-matching helpers used across checks.
+- `fenceline.scanner` — file discovery and reading.
+- `fenceline.checks` — the built-in check registry, plus `fenceline.checks`
+  entry-point discovery for third-party checks.
+- `fenceline.checks.ast_checks` — checks that walk the parsed AST (won't match
+  a dangerous call mentioned in a docstring or string literal).
+- `fenceline.checks.text_checks` — checks that scan raw source lines for
+  surface-syntax patterns.
+- `fenceline.checks.manifest_checks` — checks over dependency manifests
+  (`pyproject.toml`, `requirements.txt`, etc.), not Python source.
+- `fenceline.suppression` — `# nosec` inline-suppression parsing.
+- `fenceline.baseline` — baseline snapshot/diff for adopting fenceline on an existing codebase.
+- `fenceline.reporting` — text/JSON report rendering.
+- `fenceline.cli` — argument parsing and the scan loop.

fenceline-1.0.2/README.md

@@ -0,0 +1,116 @@
+# fenceline
+
+Zero-day security scanner for the Boti workspace.
+
+## Installation
+
+```bash
+uv add fenceline
+```
+
+Maps every finding to a CWE from the 2025 CWE Top 25, OWASP Top 10:2025, and known
+Python zero-day exploit patterns (pickle bypass CVE-2026-56315, PyYAML shadow
+vulnerability CVE-2026-24009, LangChain SSTI CVE-2025-68664, dependency confusion
+CVE-2025-61774, and more — see the CWE reference printed at the end of every
+text-mode report). 56 checks total: most are AST-based (won't false-positive on a
+dangerous call mentioned in a docstring or comment); the rest are line-regex checks
+for surface-syntax patterns that don't need full parsing.
+
+## Usage
+
+```bash
+uv run fenceline
+uv run fenceline --json > report.json
+uv run fenceline -q
+uv run fenceline --fail-on critical
+uv run fenceline --package my-lib=my-lib/src/my_lib
+```
+
+Exit codes: `0` (no findings at or above `--fail-on`), `1` (one or more).
+
+### Options
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--json` | off | Machine-readable output |
+| `--quiet` / `-q` | off | Suppress the banner |
+| `--fail-on` | `high` | Severity threshold (`critical`\|`high`\|`medium`\|`low`\|`info`) for the exit code |
+| `--confidence-min` | `low` | Drop findings below this confidence (`high`\|`medium`\|`low`) |
+| `--package NAME=PATH` | — | Add or override a scan target package (repeatable) |
+| `--baseline PATH` | — | Only report/fail on findings not already present in this baseline |
+| `--write-baseline PATH` | — | Snapshot current findings to PATH and exit 0 |
+
+By default, fenceline scans `boti`, `boti-data`, `boti-dask`, and itself.
+
+### Severity vs. confidence
+
+Every finding carries two independent ratings, the same distinction Bandit
+makes: **severity** is how bad it would be if the finding is real; **confidence**
+is how sure the check is that it *is* real. An AST-based check that matched a
+real `Call` node is `HIGH` confidence; a line-regex check that can't fully
+rule out a docstring or string-literal mention is `MEDIUM`; a handful of
+inherently heuristic checks (timing-attack keyword proximity, ReDoS
+backtracking-risk judgment, `debug=True` pattern matching) are `LOW`. Use
+`--confidence-min medium` to cut noise from the fuzzier checks without
+raising your severity bar.
+
+### Baselining an existing codebase
+
+Adopting fenceline on a codebase with existing findings doesn't mean fixing
+all of them before CI can pass:
+
+```bash
+uv run fenceline --write-baseline fenceline-baseline.json   # snapshot today's findings
+uv run fenceline --baseline fenceline-baseline.json          # only new findings fail CI
+```
+
+A finding is matched against the baseline by `(cwe_id, file, code_snippet)`,
+not line number, so it keeps matching across unrelated edits that shift line
+numbers elsewhere in the file. Re-run `--write-baseline` periodically (or
+whenever a baselined finding is deliberately fixed) to keep it current.
+
+### Suppressing a specific finding
+
+`# nosec` (bare) suppresses every finding on that line; `# nosec CWE-502`
+suppresses only that CWE, leaving any other finding on the same line intact
+— the same convention Bandit uses, with CWE IDs instead of Bandit's own
+B-numbers:
+
+```python
+pickle.loads(data)  # nosec CWE-502 -- trusted internal cache, not user input
+```
+
+### Extending fenceline with your own checks
+
+Built-in checks aren't dynamically discovered — they're a fixed list. Your
+own checks are, via a `fenceline.checks` entry point in *your own*
+`pyproject.toml`:
+
+```toml
+[project.entry-points."fenceline.checks"]
+"My Custom Check (CWE-000)" = "my_package.checks:my_check_function"
+```
+
+The entry point's own name becomes the check's display name; the object it
+points at must be a function with the same `(path, lines, tree) ->
+list[Finding]` signature every built-in check has. A plugin that fails to
+import is skipped with a warning rather than crashing the whole scan.
+
+## Design
+
+- `fenceline.models` — the `Finding` dataclass, severity ordering, and confidence ordering.
+- `fenceline.config` — workspace-root discovery and the default package registry.
+- `fenceline.ast_helpers` — shared AST/text-matching helpers used across checks.
+- `fenceline.scanner` — file discovery and reading.
+- `fenceline.checks` — the built-in check registry, plus `fenceline.checks`
+  entry-point discovery for third-party checks.
+- `fenceline.checks.ast_checks` — checks that walk the parsed AST (won't match
+  a dangerous call mentioned in a docstring or string literal).
+- `fenceline.checks.text_checks` — checks that scan raw source lines for
+  surface-syntax patterns.
+- `fenceline.checks.manifest_checks` — checks over dependency manifests
+  (`pyproject.toml`, `requirements.txt`, etc.), not Python source.
+- `fenceline.suppression` — `# nosec` inline-suppression parsing.
+- `fenceline.baseline` — baseline snapshot/diff for adopting fenceline on an existing codebase.
+- `fenceline.reporting` — text/JSON report rendering.
+- `fenceline.cli` — argument parsing and the scan loop.

fenceline-1.0.2/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "fenceline"
+version = "1.0.2"
+description = "Zero-day security scanner for the Boti workspace"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [
+    {name = "Luis Valverde"},
+]
+maintainers = [
+    {name = "Luis Valverde", email = "lvalverdeb@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Topic :: Security",
+]
+dependencies = [
+    "boti>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/lvalverdeb/fenceline"
+Repository = "https://github.com/lvalverdeb/fenceline"
+Documentation = "https://github.com/lvalverdeb/fenceline#readme"
+Issues = "https://github.com/lvalverdeb/fenceline/issues"
+
+[project.scripts]
+fenceline = "fenceline.cli:main"
+
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.11.0",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["fenceline*"]
+
+[tool.setuptools.package-data]
+fenceline = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]
+ignore = ["E501"]

fenceline-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fenceline-1.0.2/src/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-1.0.2/src/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-1.0.2/src/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