flawed 0.0.1__py3-none-any.whl

flawed/__init__.py

@@ -0,0 +1,43 @@
+"""Rift: static analysis engine for confusion vulnerability research.
+
+Rule authors start here::
+
+    from flawed import open_repo, detector
+    from flawed.inputs import Query, Form, Json
+    from flawed.effects import Mutation, Session
+    from flawed.checks import Crypto, Token
+    from flawed.route import Route, POST, accepting
+
+The top-level package IS the Rule API. Deeper layers live in subpackages:
+
+- ``flawed.semantic`` — Semantic Layer (framework interpretation)
+- ``flawed.index`` — Code Index (structural extraction)
+"""
+
+from __future__ import annotations
+
+from flawed.detector import detector
+from flawed.repo import RepoView
+
+
+def open_repo(path: str) -> RepoView:
+    """Load an analyzed repository and return the top-level navigation object.
+
+    Constructs a Code Index (Layer 1), runs the Semantic Layer
+    interpreters (Layer 2), and returns a :class:`RepoView` -- the
+    single entry point for all navigation and detection.
+
+    Args:
+        path: Path to the analysis store snapshot directory.
+
+    Returns:
+        A :class:`RepoView` for querying the analyzed repository.
+    """
+    raise NotImplementedError
+
+
+__all__ = [
+    "RepoView",
+    "detector",
+    "open_repo",
+]

flawed/calls.py

@@ -0,0 +1,202 @@
+"""Call site, argument, and function selector types.
+
+A :class:`CallSite` represents a specific location where a function is
+called with specific arguments.  This is distinct from
+:class:`~flawed.function.Function` -- a ``Function`` is the
+*definition*, while a ``CallSite`` is a particular *invocation* with
+its actual arguments and return value handle.
+
+The :class:`FnSelector` type and its :class:`Fn` sugar namespace
+provide composable selectors for matching functions by name, FQN, or
+pattern.  Selectors compose with ``|``::
+
+    from flawed.calls import Fn
+
+    selector = Fn.named("execute") | Fn.fqn("sqlalchemy.Session.add")
+    calls = route.reachable.calls(selector)
+
+    for call in calls:
+        print(call.target, call.arguments)
+        if call.return_value.flows_to(some_effect.target):
+            print("Return value reaches the effect")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flawed.core import Location
+    from flawed.flow import ValueHandle
+    from flawed.function import Function
+
+
+@dataclass(frozen=True)
+class Argument:
+    """A specific argument at a call site.
+
+    Represents one positional or keyword argument passed at a
+    particular call site.  The :attr:`value` property provides a
+    :class:`~flawed.flow.ValueHandle` for tracking the argument
+    value through the program.
+
+    Example::
+
+        call = route.reachable.calls(Fn.named("execute")).first()
+        for arg in call.arguments:
+            print(arg.index, arg.name, arg.expression)
+            if arg.value.derived_from(Json()):
+                print("Argument comes from JSON input!")
+    """
+
+    index: int
+    """0-based positional index of the argument."""
+
+    name: str | None
+    """Keyword name if passed as a keyword argument, or ``None``."""
+
+    expression: str
+    """Source text of the argument expression."""
+
+    location: Location
+    """Source location of the argument expression."""
+
+    @property
+    def value(self) -> ValueHandle:
+        """Handle for tracking this argument's value through the program."""
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class CallSite:
+    """A specific invocation of a function with specific arguments.
+
+    Distinct from :class:`~flawed.function.Function` -- a function
+    may be called from many sites, and each site carries its own
+    arguments and return value.
+
+    The :attr:`target` is ``None`` when the called function cannot be
+    resolved (e.g. a call through a variable whose value is unknown).
+
+    Example::
+
+        for call in route.reachable.calls(Fn.named("execute")):
+            print(call.target_expression)
+            arg0 = call.argument(0)
+            if arg0.value.derived_from(Json()):
+                yield route.finding("SQL from JSON").evidence(call, "db call")
+    """
+
+    target: Function | None
+    """The called function, or ``None`` if the target is unresolved."""
+
+    target_expression: str
+    """Source text of the call target (e.g. ``"db.execute"``)."""
+
+    arguments: tuple[Argument, ...]
+    """All arguments in call-site order."""
+
+    location: Location
+    """Source location of the call expression."""
+
+    function: Function
+    """The function containing this call site."""
+
+    def argument(self, index: int) -> Argument:
+        """Look up an argument by 0-based positional index.
+
+        Raises ``IndexError`` if the index is out of range.
+        """
+        raise NotImplementedError
+
+    def keyword_argument(self, name: str) -> Argument | None:
+        """Look up an argument by keyword name.
+
+        Returns ``None`` if no keyword argument with the given name
+        exists at this call site.
+        """
+        raise NotImplementedError
+
+    @property
+    def return_value(self) -> ValueHandle:
+        """Handle for tracking the call's return value.
+
+        Use to check whether the return value flows to a particular
+        effect or is used in a condition.
+        """
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class FnSelector:
+    """Composable selector for filtering functions by name, FQN, or pattern.
+
+    Single selectors match by one criterion (name, FQN, or regex).
+    Composed selectors (via ``|``) match if *any* alternative matches.
+
+    Construct via the :class:`Fn` sugar namespace rather than directly::
+
+        selector = Fn.named("execute") | Fn.fqn("db.Session.add")
+    """
+
+    name_filter: str | None = None
+    """Match functions with this exact short name."""
+
+    fqn_filter: str | None = None
+    """Match functions with this exact fully qualified name."""
+
+    pattern_filter: str | None = None
+    """Match functions whose name matches this regex pattern."""
+
+    _alternatives: tuple[FnSelector, ...] = ()
+    """Internal: composed alternatives from ``|`` operations."""
+
+    def __or__(self, other: FnSelector) -> FnSelector:
+        """Compose selectors: the result matches if either matches.
+
+        Example::
+
+            combined = Fn.named("execute") | Fn.named("run_query")
+        """
+        my = self._alternatives if self._alternatives else (self,)
+        theirs = other._alternatives if other._alternatives else (other,)
+        return FnSelector(_alternatives=(*my, *theirs))
+
+
+class Fn:
+    """Sugar namespace for constructing function selectors.
+
+    Example::
+
+        Fn.named("execute")                  # match by short name
+        Fn.fqn("sqlalchemy.Session.add")     # match by FQN
+        Fn.matching(r"^(get|fetch)_")        # match by regex
+    """
+
+    @staticmethod
+    def named(name: str) -> FnSelector:
+        """Select functions with the given short name.
+
+        Args:
+            name: Exact function name to match (e.g. ``"execute"``).
+        """
+        return FnSelector(name_filter=name)
+
+    @staticmethod
+    def fqn(fqn: str) -> FnSelector:
+        """Select functions with the given fully qualified name.
+
+        Args:
+            fqn: Exact FQN to match (e.g. ``"hmac.compare_digest"``).
+        """
+        return FnSelector(fqn_filter=fqn)
+
+    @staticmethod
+    def matching(pattern: str) -> FnSelector:
+        """Select functions matching the given regex pattern.
+
+        Args:
+            pattern: Regular expression matched against the function name.
+        """
+        return FnSelector(pattern_filter=pattern)

flawed/checks.py

@@ -0,0 +1,166 @@
+"""Composable selectors for security-relevant validation functions.
+
+Parallel to the effects module: where effects describe *what side
+effects occur*, checks describe *what validation functions are called*.
+Use checks to determine whether a route validates its inputs before
+performing a sensitive operation.
+
+The selector namespaces are:
+
+- :class:`Crypto` -- cryptographic comparison and hashing
+- :class:`Token` -- JWT / signed-token verification
+- :class:`Schema` -- input schema validation (pydantic, marshmallow, etc.)
+- :class:`Permission` -- authorization / permission checks (heuristic)
+
+Compose checks with effects to express security patterns::
+
+    from flawed.checks import Crypto, Token, Schema, Permission
+    from flawed.calls import Fn
+    from flawed.effects import Mutation, Session
+
+    VALIDATORS = Crypto.compare() | Token.verify()
+    SENSITIVE  = Mutation.any() | Session.write()
+
+    validators = route.reachable.calls(VALIDATORS).with_argument_from(read.value)
+
+Permission selectors use name-pattern matching (heuristic) since
+authorization functions are project-specific.  Extend with
+``Fn.fqn()`` for precision when the target project's auth functions
+are known.
+"""
+
+from __future__ import annotations
+
+from flawed.calls import Fn, FnSelector
+
+
+class Crypto:
+    """Selectors for cryptographic verification functions.
+
+    Example::
+
+        Crypto.compare()  # hmac.compare_digest, check_password_hash, etc.
+        Crypto.hash()     # hashlib.sha256, hashlib.pbkdf2_hmac, etc.
+    """
+
+    @staticmethod
+    def compare() -> FnSelector:
+        """Hash/digest comparison functions.
+
+        Matches: ``hmac.compare_digest``, ``werkzeug.security.check_password_hash``,
+        ``bcrypt.checkpw``, ``passlib.hash.bcrypt.verify``, ``argon2.verify_password``.
+        """
+        return (
+            Fn.fqn("hmac.compare_digest")
+            | Fn.fqn("werkzeug.security.check_password_hash")
+            | Fn.fqn("bcrypt.checkpw")
+            | Fn.fqn("passlib.hash.bcrypt.verify")
+            | Fn.fqn("argon2.verify_password")
+        )
+
+    @staticmethod
+    def hash() -> FnSelector:
+        """Cryptographic hash construction functions.
+
+        Matches: ``hashlib.sha256``, ``hashlib.sha512``, ``hashlib.sha384``,
+        ``hashlib.sha3_256``, ``hashlib.pbkdf2_hmac``, ``hashlib.scrypt``.
+        """
+        return (
+            Fn.fqn("hashlib.sha256")
+            | Fn.fqn("hashlib.sha512")
+            | Fn.fqn("hashlib.sha384")
+            | Fn.fqn("hashlib.sha3_256")
+            | Fn.fqn("hashlib.pbkdf2_hmac")
+            | Fn.fqn("hashlib.scrypt")
+        )
+
+
+class Token:
+    """Selectors for token verification functions.
+
+    Example::
+
+        Token.verify()  # jwt.decode, itsdangerous loads, etc.
+    """
+
+    @staticmethod
+    def verify() -> FnSelector:
+        """Token decode / verification functions.
+
+        Matches: ``jwt.decode``, ``jose.jwt.decode``, ``authlib.jose.jwt.decode``,
+        ``itsdangerous.URLSafeTimedSerializer.loads``,
+        ``itsdangerous.URLSafeSerializer.loads``, ``itsdangerous.Signer.unsign``.
+        """
+        return (
+            Fn.fqn("jwt.decode")
+            | Fn.fqn("jose.jwt.decode")
+            | Fn.fqn("authlib.jose.jwt.decode")
+            | Fn.fqn("itsdangerous.URLSafeTimedSerializer.loads")
+            | Fn.fqn("itsdangerous.URLSafeSerializer.loads")
+            | Fn.fqn("itsdangerous.Signer.unsign")
+        )
+
+
+class Schema:
+    """Selectors for schema / input validation functions.
+
+    Example::
+
+        Schema.validate()  # pydantic, marshmallow, wtforms, cerberus, etc.
+    """
+
+    @staticmethod
+    def validate() -> FnSelector:
+        """Schema validation functions.
+
+        Matches: ``pydantic.BaseModel.model_validate``,
+        ``marshmallow.Schema.load``, ``wtforms.Form.validate``,
+        ``cerberus.Validator.validate``, ``voluptuous.Schema.__call__``,
+        and their common variants.
+        """
+        return (
+            Fn.fqn("pydantic.BaseModel.model_validate")
+            | Fn.fqn("pydantic.BaseModel.model_validate_json")
+            | Fn.fqn("marshmallow.Schema.load")
+            | Fn.fqn("marshmallow.Schema.loads")
+            | Fn.fqn("wtforms.Form.validate")
+            | Fn.fqn("wtforms.Form.validate_on_submit")
+            | Fn.fqn("cerberus.Validator.validate")
+            | Fn.fqn("voluptuous.Schema.__call__")
+        )
+
+
+class Permission:
+    """Selectors for authorization / permission check functions.
+
+    These use name matching (heuristic) since permission check
+    functions are project-specific.  Extend with ``Fn.fqn()`` for
+    precision when the target project's auth functions are known.
+
+    Example::
+
+        Permission.check()    # has_permission, authorize, etc.
+        Permission.require()  # require_permission, require_role, etc.
+    """
+
+    @staticmethod
+    def check() -> FnSelector:
+        """Common permission-check function names.
+
+        Matches: ``has_permission``, ``check_permission``, ``can_access``,
+        ``authorize``, ``is_authorized``.
+        """
+        return Fn.matching(
+            r"^(has_permission|check_permission|can_access|authorize|is_authorized)$"
+        )
+
+    @staticmethod
+    def require() -> FnSelector:
+        """Common permission-require function names.
+
+        Matches: ``require_permission``, ``require_role``,
+        ``require_admin``, ``require_auth``.
+        """
+        return Fn.matching(
+            r"^(require_permission|require_role|require_admin|require_auth)$"
+        )