apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/core/types.py

@@ -0,0 +1,587 @@
+"""
+Core type definitions for apisec-code-bolt.
+
+This module defines all enums, protocols, and base types used throughout the codebase.
+We use strong typing everywhere - no magic strings where enums should be used.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+
+# =============================================================================
+# Language and Framework Enums
+# =============================================================================
+
+
+class Language(Enum):
+    """
+    Programming languages supported by the analyzer.
+
+    Only add languages here when parser support is implemented.
+    This enum drives parser selection and framework detection.
+    """
+
+    PYTHON = auto()
+    JAVA = auto()
+    CSHARP = auto()
+    JAVASCRIPT = auto()
+
+
+class Framework(Enum):
+    """
+    Frameworks we detect and provide specialized analysis for.
+
+    Only add frameworks here when extraction logic is implemented.
+    Includes web frameworks, CLI frameworks, and task/worker frameworks.
+    """
+
+    # Python web frameworks
+    FASTAPI = auto()
+    FLASK = auto()
+    DJANGO = auto()
+
+    # Python CLI frameworks
+    CLICK = auto()
+    TYPER = auto()
+
+    # Python task / worker frameworks
+    CELERY = auto()
+    DRAMATIQ = auto()
+    PREFECT = auto()
+
+    # Java frameworks
+    SPRING_BOOT = auto()
+    MICRONAUT = auto()
+    JAXRS = auto()  # Jersey, Quarkus REST, RESTEasy — javax.ws.rs / jakarta.ws.rs
+
+    # .NET / C# frameworks
+    ASPNET_CORE = auto()
+    ASPNET_LEGACY = auto()  # System.Web.Mvc / System.Web.Http (pre-.NET Core)
+    REFIT = auto()  # Refit declarative HTTP client interfaces
+    GRPC = auto()  # Grpc.Core / Grpc.AspNetCore.Server (server-side)
+    WCF = auto()  # Windows Communication Foundation / CoreWCF
+
+    # JavaScript / TypeScript frameworks
+    EXPRESS = auto()
+    NESTJS = auto()
+    FASTIFY = auto()
+
+    # GraphQL (cross-language)
+    GRAPHQL = auto()
+
+    # Generic fallback
+    GENERIC = auto()
+
+
+# =============================================================================
+# Data Origin Types (Generic - not vulnerability-specific)
+# =============================================================================
+
+
+class OriginType(Enum):
+    """
+    Types of data origins - where data enters the application.
+
+    These are OBSERVABLE FACTS about data sources, not security judgments.
+    The Cloud applies vulnerability rules to interpret these.
+
+    Member names are the canonical serialization strings written into
+    manifests and matched by the reasoning engine's _ORIGIN_CATEGORY_MAP.
+    Do NOT rename members without updating the engine map.
+    """
+
+    # HTTP request data
+    HTTP_PATH_PARAM = auto()  # /users/{user_id}
+    HTTP_QUERY_PARAM = auto()  # ?filter=value
+    HTTP_BODY = auto()  # POST/PUT body
+    HTTP_HEADER = auto()  # Request headers
+    HTTP_COOKIE = auto()  # Cookie values
+    HTTP_FORM = auto()  # Form data
+    HTTP_FILE = auto()  # Uploaded files
+
+    # Environment and configuration
+    ENVIRONMENT_VAR = auto()  # os.environ, System.getenv
+    CONFIG_VALUE = auto()  # Loaded from config files
+
+    # External data sources
+    FILE_CONTENT = auto()  # Read from filesystem
+    DATABASE_RESULT = auto()  # Query result from DB
+    EXTERNAL_API = auto()  # Response from HTTP call
+    MESSAGE_QUEUE = auto()  # Message from queue/broker
+
+    # Code-level origins
+    FUNCTION_PARAMETER = auto()  # Parameter passed to function
+    FUNCTION_RETURN = auto()  # Return value from function
+    CLASS_ATTRIBUTE = auto()  # Instance/class attribute
+    LITERAL = auto()  # Hardcoded literal value
+
+    # Generic
+    USER_INPUT = auto()  # Generic user input
+
+    # Unknown/unresolved
+    UNKNOWN = auto()
+
+
+class TransformationType(Enum):
+    """
+    Types of transformations applied to data as it flows.
+
+    This helps the Cloud understand what happened to data.
+    """
+
+    # String operations
+    STRING_CONCATENATION = auto()  # "prefix" + value
+    STRING_FORMAT = auto()  # f"...{value}..." or .format()
+    STRING_INTERPOLATION = auto()  # Template strings
+
+    # Encoding/decoding
+    URL_ENCODE = auto()
+    URL_DECODE = auto()
+    BASE64_ENCODE = auto()
+    BASE64_DECODE = auto()
+    JSON_SERIALIZE = auto()
+    JSON_DESERIALIZE = auto()
+
+    # Type conversions
+    TYPE_CAST = auto()  # int(value), str(value)
+    TYPE_COERCION = auto()  # Implicit conversion
+
+    # Collection operations
+    LIST_INDEX = auto()  # value[0]
+    DICT_ACCESS = auto()  # value["key"]
+    ATTRIBUTE_ACCESS = auto()  # value.attr
+
+    # Function calls
+    FUNCTION_CALL = auto()  # some_function(value)
+    METHOD_CALL = auto()  # obj.method(value)
+
+    # Assignments
+    VARIABLE_ASSIGNMENT = auto()  # x = value
+    DESTRUCTURING = auto()  # a, b = value
+
+    # Unknown
+    UNKNOWN = auto()
+
+
+# =============================================================================
+# Authentication Types
+# =============================================================================
+
+
+class AuthSchemeType(Enum):
+    """
+    Types of authentication schemes we detect.
+
+    These represent observable authentication patterns, not security judgments.
+    """
+
+    # OAuth2 variants
+    OAUTH2_PASSWORD = auto()  # Resource Owner Password Grant
+    OAUTH2_AUTHORIZATION_CODE = auto()  # Authorization Code Grant
+    OAUTH2_CLIENT_CREDENTIALS = auto()  # Client Credentials Grant
+    OAUTH2_IMPLICIT = auto()  # Implicit Grant (deprecated but exists)
+
+    # Token-based
+    JWT_BEARER = auto()  # JWT in Authorization: Bearer header
+    API_KEY_HEADER = auto()  # API key in custom header
+    API_KEY_QUERY = auto()  # API key in query string
+    API_KEY_COOKIE = auto()  # API key in cookie
+
+    # Session-based
+    SESSION_COOKIE = auto()  # Server-side session with cookie
+
+    # Basic authentication
+    HTTP_BASIC = auto()  # Basic auth header
+    HTTP_DIGEST = auto()  # Digest auth header
+
+    # Framework-specific
+    SPRING_SECURITY = auto()  # Spring Security configuration
+
+    # Unknown/custom
+    CUSTOM = auto()
+    UNKNOWN = auto()
+
+
+class AuthDependencyType(Enum):
+    """Types of authentication dependencies/guards."""
+
+    FUNCTION = auto()  # Dependency is a function
+    CLASS = auto()  # Dependency is a class
+    DECORATOR = auto()  # Dependency is a decorator
+    ANNOTATION = auto()  # Dependency is an annotation (Java)
+    MIDDLEWARE = auto()  # Authentication in middleware
+    FILTER = auto()  # Authentication in filter (Java)
+    INTERCEPTOR = auto()  # Authentication in interceptor (Java)
+
+
+# =============================================================================
+# HTTP Types
+# =============================================================================
+
+
+class HttpMethod(Enum):
+    """HTTP methods for route definitions."""
+
+    GET = auto()
+    POST = auto()
+    PUT = auto()
+    PATCH = auto()
+    DELETE = auto()
+    HEAD = auto()
+    OPTIONS = auto()
+    TRACE = auto()
+
+    # WebSocket (special case)
+    WEBSOCKET = auto()
+
+
+class ParameterLocation(Enum):
+    """Where a parameter comes from in a request or entry point invocation."""
+
+    # HTTP parameter locations
+    PATH = auto()
+    QUERY = auto()
+    HEADER = auto()
+    COOKIE = auto()
+    BODY = auto()
+    FORM = auto()
+
+    # CLI parameter locations
+    CLI_ARGUMENT = auto()
+    CLI_OPTION = auto()
+
+    # Task / message consumer parameter locations
+    TASK_ARGUMENT = auto()
+
+
+# =============================================================================
+# Code Location Types
+# =============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class CodeLocation:
+    """
+    Precise location in source code.
+
+    Immutable and hashable for use as dict keys and in sets.
+    """
+
+    file: Path
+    line: int
+    column: int | None = None
+    end_line: int | None = None
+    end_column: int | None = None
+
+    def __str__(self) -> str:
+        if self.column is not None:
+            return f"{self.file}:{self.line}:{self.column}"
+        return f"{self.file}:{self.line}"
+
+
+@dataclass(frozen=True, slots=True)
+class QualifiedName:
+    """
+    Fully qualified name for a symbol (function, class, method).
+
+    Examples:
+        - "app.routes.users.get_user"
+        - "com.example.UserController.getUser"
+    """
+
+    module: str  # "app.routes.users" or "com.example"
+    name: str  # "get_user" or "UserController.getUser"
+
+    @property
+    def full(self) -> str:
+        """Full qualified name."""
+        if self.module:
+            return f"{self.module}.{self.name}"
+        return self.name
+
+    def __str__(self) -> str:
+        return self.full
+
+
+# =============================================================================
+# Analysis Context Types
+# =============================================================================
+
+
+@dataclass(slots=True)
+class CallContext:
+    """
+    Context about where a function call occurs.
+
+    This provides valuable information for security analysis:
+    - Is the call inside a try block? (affects error handling)
+    - Is it inside a conditional? (affects reachability)
+    """
+
+    in_try_block: bool = False
+    exception_handlers: list[str] = field(default_factory=list)
+    exception_swallowed: bool = False  # except: pass
+
+    in_conditional: bool = False
+    conditional_expressions: list[str] = field(default_factory=list)
+    guards_this_call: bool = False  # Is the conditional a guard for this call?
+
+    in_loop: bool = False
+    loop_type: str | None = None  # "for", "while"
+
+    in_async_context: bool = False
+
+
+@dataclass(slots=True)
+class FlowContext:
+    """
+    Context about a data flow's execution environment.
+    """
+
+    entry_point_id: str | None = None
+    in_try_block: bool = False
+    exception_handlers: list[str] = field(default_factory=list)
+    guarded_by_conditionals: list[str] = field(default_factory=list)
+    in_loop: bool = False
+
+
+# =============================================================================
+# Confidence and Analysis Metadata
+# =============================================================================
+
+
+class Confidence(Enum):
+    """
+    Confidence level in an analysis result.
+
+    Used to indicate how certain we are about detected patterns.
+    """
+
+    HIGH = auto()  # Definitely correct
+    MEDIUM = auto()  # Likely correct, may need verification
+    LOW = auto()  # Uncertain, needs Cloud verification
+    UNKNOWN = auto()  # Could not determine
+
+
+@dataclass(slots=True)
+class AnalysisNote:
+    """
+    Note or warning about analysis quality for a specific item.
+    """
+
+    level: str  # "info", "warning", "error"
+    message: str
+    location: CodeLocation | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+# =============================================================================
+# Protocol Definitions (Interfaces)
+# =============================================================================
+
+
+@runtime_checkable
+class Visitable(Protocol):
+    """Protocol for AST nodes that can be visited."""
+
+    def accept(self, visitor: Any) -> Any:
+        """Accept a visitor."""
+        ...
+
+
+@runtime_checkable
+class Parser(Protocol):
+    """
+    Protocol for language-specific parsers.
+
+    Each language (Python, Java, etc.) implements this protocol
+    to provide parsing capabilities.
+    """
+
+    @property
+    def language(self) -> Language:
+        """The language this parser handles."""
+        ...
+
+    @property
+    def supported_extensions(self) -> frozenset[str]:
+        """File extensions this parser handles (e.g., {'.py'})."""
+        ...
+
+    def can_parse(self, file_path: Path) -> bool:
+        """Check if this parser can handle the given file."""
+        ...
+
+    def parse_file(self, file_path: Path) -> ParsedFile:
+        """
+        Parse a single file and return structured data.
+
+        Raises:
+            ParseError: If the file cannot be parsed.
+        """
+        ...
+
+    def parse_files(self, file_paths: Sequence[Path]) -> Iterator[ParsedFile]:
+        """
+        Parse multiple files, yielding results.
+
+        This allows for streaming/incremental processing.
+        """
+        ...
+
+
+@runtime_checkable
+class FrameworkPlugin(Protocol):
+    """
+    Protocol for framework-specific extraction plugins.
+
+    Each framework (FastAPI, Spring Boot, etc.) implements this
+    to provide specialized route and dependency extraction.
+    """
+
+    @property
+    def framework(self) -> Framework:
+        """The framework this plugin handles."""
+        ...
+
+    @property
+    def language(self) -> Language:
+        """The language this framework is for."""
+        ...
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        """
+        Detect if this framework is used in the parsed file.
+
+        Returns True if framework-specific patterns are found.
+        """
+        ...
+
+    def extract_routes(self, parsed_file: ParsedFile) -> list[RouteDefinition]:
+        """Extract HTTP route definitions from the file."""
+        ...
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[DependencyDefinition]:
+        """Extract dependency injection definitions."""
+        ...
+
+    def extract_auth(self, parsed_file: ParsedFile) -> list[AuthDefinition]:
+        """Extract authentication-related definitions."""
+        ...
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[MiddlewareDefinition]:
+        """Extract middleware/interceptor definitions."""
+        ...
+
+
+# =============================================================================
+# Forward Declarations (to be fully defined in manifest.py)
+# =============================================================================
+
+# These are declared here so they can be referenced in protocols above.
+# Full definitions with all fields are in manifest.py
+
+
+@dataclass
+class ParsedFile:
+    """Represents a parsed source file."""
+
+    path: Path
+    language: Language
+    # Full definition in manifest.py
+
+
+@dataclass
+class RouteDefinition:
+    """Represents an HTTP route definition."""
+
+    id: str
+    method: HttpMethod
+    path: str
+    # Full definition in manifest.py
+
+
+@dataclass
+class DependencyDefinition:
+    """Represents a dependency injection definition."""
+
+    id: str
+    name: str
+    # Full definition in manifest.py
+
+
+@dataclass
+class AuthDefinition:
+    """Represents an authentication definition."""
+
+    id: str
+    scheme_type: AuthSchemeType
+    # Full definition in manifest.py
+
+
+@dataclass
+class MiddlewareDefinition:
+    """Represents a middleware/interceptor definition."""
+
+    id: str
+    name: str
+    # Full definition in manifest.py
+
+
+# =============================================================================
+# Exception Types
+# =============================================================================
+
+
+class CodeBoltError(Exception):
+    """Base exception for all apisec-code-bolt errors."""
+
+    pass
+
+
+class ParseError(CodeBoltError):
+    """Error during parsing."""
+
+    def __init__(
+        self,
+        message: str,
+        file_path: Path | None = None,
+        line: int | None = None,
+        column: int | None = None,
+    ):
+        super().__init__(message)
+        self.file_path = file_path
+        self.line = line
+        self.column = column
+
+
+class ConfigurationError(CodeBoltError):
+    """Error in configuration."""
+
+    pass
+
+
+class AnalysisError(CodeBoltError):
+    """Error during analysis."""
+
+    pass
+
+
+class CloudCommunicationError(CodeBoltError):
+    """Error communicating with cloud services."""
+
+    pass
+
+
+class TimeoutError(CodeBoltError):
+    """Analysis timeout."""
+
+    pass

apisec_code_bolt/fingerprinting/__init__.py

@@ -0,0 +1 @@
+"""Integration detection and capability fingerprinting."""

apisec_code_bolt/frameworks/__init__.py

@@ -0,0 +1,29 @@
+"""Framework-specific extraction plugins."""
+
+from .base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedBody,
+    ExtractedDependency,
+    ExtractedJwtConfig,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedResponse,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+__all__ = [
+    "BaseFrameworkPlugin",
+    "FrameworkPluginRegistry",
+    "ExtractedRoute",
+    "ExtractedParameter",
+    "ExtractedBody",
+    "ExtractedResponse",
+    "ExtractedDependency",
+    "ExtractedAuthScheme",
+    "ExtractedAuthDependency",
+    "ExtractedJwtConfig",
+    "ExtractedMiddleware",
+]

apisec_code_bolt/frameworks/_jwt_common.py

@@ -0,0 +1,50 @@
+"""
+Shared JWT algorithm helpers.
+
+The canonical JWA algorithm set is identical across every JWT library
+(HS256/RS256/ES256/PS256 families). The normalization and append-to-config
+helpers used by `JavaJwtConfigExtractor` and `DotNetJwtConfigExtractor`
+were near-byte-identical — promoted here so each extractor only carries
+the framework-specific aliases.
+"""
+
+from __future__ import annotations
+
+from .base import ExtractedJwtConfig
+
+# Canonical JWA algorithm names (RFC 7518).  Both Java and .NET extractors
+# share this set; framework-specific aliases live alongside each extractor.
+ALGORITHM_NAMES: frozenset[str] = frozenset(
+    {
+        "HS256",
+        "HS384",
+        "HS512",
+        "RS256",
+        "RS384",
+        "RS512",
+        "ES256",
+        "ES384",
+        "ES512",
+        "PS256",
+        "PS384",
+        "PS512",
+    }
+)
+
+
+def normalize_algorithm(raw: str, aliases: dict[str, str]) -> str | None:
+    """Return a canonical JWA algorithm name, or None if unrecognised.
+
+    Upper-cases and strips `-` / `_` so framework-specific forms like
+    `HMAC-SHA256` or `RSA_SHA256` collapse to the alias-lookup key.
+    """
+    upper = raw.upper().replace("-", "").replace("_", "")
+    if upper in ALGORITHM_NAMES:
+        return upper
+    return aliases.get(upper)
+
+
+def add_algorithm(algo: str | None, jwt_config: ExtractedJwtConfig) -> None:
+    """Append an algorithm to the config if non-empty and not already present."""
+    if algo and algo not in jwt_config.algorithms:
+        jwt_config.algorithms.append(algo)