securescout-iast 0.1.0__tar.gz

securescout_iast-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: securescout-iast
+Version: 0.1.0
+Summary: Interactive Application Security Testing (IAST) runtime agent for Python
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# securescout-iast
+
+Interactive Application Security Testing (IAST) runtime agent for Python web applications. Detects SQL injection vulnerabilities in real time by tracing untrusted request data as it flows into database queries during normal application traffic.
+
+## How it works
+
+`securescout-iast` tags incoming request data (query parameters, headers, cookies, and JSON/form body) at the ASGI layer, then watches for that data appearing in raw SQL execute calls. If untrusted input reaches a database query without being safely parameterized, a finding is reported to your SecureScout dashboard — confirmed by actual runtime execution, not static guesswork.
+
+## Installation
+
+```bash
+pip install securescout-iast
+```
+
+## Quick start (FastAPI / Starlette)
+
+```python
+from fastapi import FastAPI
+from securescout_iast import SecureScoutIastMiddleware, init
+
+app = FastAPI()
+
+init(
+    api_key="ssk_live_your_api_key",
+    project_id="your-project-id",
+)
+app.add_middleware(SecureScoutIastMiddleware)
+```
+
+Get your API key and project ID from **Settings → API Keys** and your project's **Runtime (IAST)** tab in the SecureScout dashboard.
+
+## Supported database drivers
+
+- `psycopg2` (sync PostgreSQL)
+- `asyncpg` (async PostgreSQL, including async SQLAlchemy)
+
+Drivers are detected automatically. If a driver isn't installed in your environment, that patch is silently skipped — no errors, no extra dependencies pulled in.
+
+## Detected vulnerability classes
+
+- SQL Injection (CWE-89) — v1
+
+## Safety guarantees
+
+- `init()` never raises. Misconfiguration or network issues degrade to a silent no-op, never a crash.
+- Your request and database driver behavior are never modified — the agent only observes.
+- Request bodies over 1MB are not buffered for taint analysis (still passed through to your app unmodified).
+- No third-party dependencies. Pure standard library.
+
+## Privacy
+
+This agent inspects request data and SQL query text locally, within your application process, to detect taint matches. Only confirmed findings (rule type, query snippet, stack trace, endpoint) are sent to SecureScout — never raw request bodies or full traffic.
+
+## License
+
+MIT

securescout_iast-0.1.0/README.md

@@ -0,0 +1,56 @@
+# securescout-iast
+
+Interactive Application Security Testing (IAST) runtime agent for Python web applications. Detects SQL injection vulnerabilities in real time by tracing untrusted request data as it flows into database queries during normal application traffic.
+
+## How it works
+
+`securescout-iast` tags incoming request data (query parameters, headers, cookies, and JSON/form body) at the ASGI layer, then watches for that data appearing in raw SQL execute calls. If untrusted input reaches a database query without being safely parameterized, a finding is reported to your SecureScout dashboard — confirmed by actual runtime execution, not static guesswork.
+
+## Installation
+
+```bash
+pip install securescout-iast
+```
+
+## Quick start (FastAPI / Starlette)
+
+```python
+from fastapi import FastAPI
+from securescout_iast import SecureScoutIastMiddleware, init
+
+app = FastAPI()
+
+init(
+    api_key="ssk_live_your_api_key",
+    project_id="your-project-id",
+)
+app.add_middleware(SecureScoutIastMiddleware)
+```
+
+Get your API key and project ID from **Settings → API Keys** and your project's **Runtime (IAST)** tab in the SecureScout dashboard.
+
+## Supported database drivers
+
+- `psycopg2` (sync PostgreSQL)
+- `asyncpg` (async PostgreSQL, including async SQLAlchemy)
+
+Drivers are detected automatically. If a driver isn't installed in your environment, that patch is silently skipped — no errors, no extra dependencies pulled in.
+
+## Detected vulnerability classes
+
+- SQL Injection (CWE-89) — v1
+
+## Safety guarantees
+
+- `init()` never raises. Misconfiguration or network issues degrade to a silent no-op, never a crash.
+- Your request and database driver behavior are never modified — the agent only observes.
+- Request bodies over 1MB are not buffered for taint analysis (still passed through to your app unmodified).
+- No third-party dependencies. Pure standard library.
+
+## Privacy
+
+This agent inspects request data and SQL query text locally, within your application process, to detect taint matches. Only confirmed findings (rule type, query snippet, stack trace, endpoint) are sent to SecureScout — never raw request bodies or full traffic.
+
+## License
+
+MIT

securescout_iast-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "securescout-iast"
+version = "0.1.0"
+description = "Interactive Application Security Testing (IAST) runtime agent for Python"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Security",
+    "Framework :: FastAPI",
+]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["securescout_iast*"]

securescout_iast-0.1.0/securescout_iast/__init__.py

@@ -0,0 +1,60 @@
+import logging
+import threading
+from securescout_iast.config import DEFAULT_BACKEND_URL
+from securescout_iast.reporter import init_reporter, send_heartbeat, queue_finding
+from securescout_iast.patches.psycopg2_patch import install_psycopg2_patch
+from securescout_iast.patches.asyncpg_patch import install_asyncpg_patch
+from securescout_iast.middleware import SecureScoutIastMiddleware
+
+# Expose the ASGI middleware class and the init entrypoint
+__all__ = ["SecureScoutIastMiddleware", "init"]
+
+logger = logging.getLogger("securescout_iast")
+_initialized = False
+
+
+def init(
+    api_key: str,
+    project_id: str,
+    backend_url: str = DEFAULT_BACKEND_URL,
+    framework: str = "fastapi"
+) -> None:
+    """
+    Initializes the SecureScout IAST runtime monitoring agent.
+    Safely monkey-patches database connection libraries and spawns background telemetry loops.
+    Guarantees no exception propagation to avoid interrupting customer application startup.
+    """
+    global _initialized
+    if _initialized:
+        logger.warning("SecureScout IAST agent is already initialized. Skipping setup.")
+        return
+
+    try:
+        # Check inputs and degrade to no-op on missing parameters without raising ValueErrors
+        if not api_key:
+            logger.error("SecureScout IAST initialization aborted: API Key must not be empty.")
+            return
+        if not project_id:
+            logger.error("SecureScout IAST initialization aborted: Project ID must not be empty.")
+            return
+
+        # 1. Initialize background telemetry batch reporter daemon
+        init_reporter(api_key=api_key, project_id=project_id, backend_url=backend_url)
+
+        # 2. Inject database driver interception monkey-patches
+        install_psycopg2_patch(queue_finding)
+        install_asyncpg_patch(queue_finding)
+
+        # 3. Transmit connection heartbeat on a background thread to prevent blocking boot probes
+        threading.Thread(
+            target=send_heartbeat,
+            args=(framework,),
+            daemon=True
+        ).start()
+
+        _initialized = True
+        logger.info("SecureScout IAST agent initialized successfully.")
+
+    except Exception as e:
+        # Guarantee absolute fail-safety for the customer app on startup
+        logger.error(f"Failed to initialize SecureScout IAST agent: {e}", exc_info=True)

securescout_iast-0.1.0/securescout_iast/config.py

@@ -0,0 +1,10 @@
+import os
+
+# Base API endpoint for the SecureScout backend
+DEFAULT_BACKEND_URL = os.environ.get("SECURESCOUT_BACKEND_URL", "https://api.getsecurescout.com")
+
+# Maximum request body size (in bytes) we are willing to buffer for taint parsing (1MB)
+MAX_BODY_SIZE_BYTES = 1_000_000
+
+# Minimum string length required to register a taint value to prevent single-character false positives
+TAINT_MIN_LENGTH = 6

securescout_iast-0.1.0/securescout_iast/middleware.py

@@ -0,0 +1,142 @@
+import uuid
+import logging
+from typing import Any
+from urllib.parse import parse_qsl
+from http.cookies import SimpleCookie
+
+from securescout_iast.taint import (
+    init_request_taint_registry,
+    register_taint,
+    register_endpoint,
+    clear_thread_taint_registry
+)
+
+logger = logging.getLogger("securescout_iast")
+
+
+class SecureScoutIastMiddleware:
+    """
+    Pure ASGI Middleware that performs wire-level interception of query parameters,
+    headers, cookies, and body inputs. Stores observed taint data in task-local ContextVars
+    without modifying Starlette's Request objects or customer application types.
+    """
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # 1. Initialize context-isolated registry and request ID
+        request_id = str(uuid.uuid4())
+        scope["securescout_request_id"] = request_id
+        init_request_taint_registry()
+
+        # Register endpoint context
+        endpoint = f"{scope.get('method', 'GET')} {scope.get('path', '/')}"
+        register_endpoint(request_id, endpoint)
+
+        try:
+            # 2. Parse raw query string from scope
+            query_bytes = scope.get("query_string", b"")
+            try:
+                query_string = query_bytes.decode("utf-8", errors="ignore")
+                if query_string:
+                    for key, val in parse_qsl(query_string, keep_blank_values=True):
+                        if len(val) >= 6:
+                            register_taint(val, source="query_param", field_name=key, request_id=request_id)
+            except Exception as e:
+                logger.debug(f"Failed to parse query string: {e}")
+
+            # 3. Parse cookies and client headers from scope headers list
+            for raw_key, raw_val in scope.get("headers", []):
+                try:
+                    key = raw_key.decode("latin-1").lower()
+                    val = raw_val.decode("latin-1")
+                    
+                    if key == "cookie":
+                        cookie = SimpleCookie()
+                        cookie.load(val)
+                        for c_key, morsel in cookie.items():
+                            if len(morsel.value) >= 6:
+                                register_taint(morsel.value, source="cookie", field_name=c_key, request_id=request_id)
+                    elif key in {"referer", "user-agent", "x-forwarded-for"}:
+                        if len(val) >= 6:
+                            register_taint(val, source="header", field_name=key, request_id=request_id)
+                except Exception as e:
+                    logger.debug(f"Failed to parse header {raw_key}: {e}")
+
+            # 4. Content-Length pre-check to prevent buffering huge bodies
+            content_length = 0
+            for rk, rv in scope.get("headers", []):
+                if rk.decode("latin-1").lower() == "content-length":
+                    try:
+                        content_length = int(rv.decode("latin-1"))
+                    except ValueError:
+                        pass
+                    break
+
+            max_buffer_size = 1_000_000  # 1MB size limit
+            should_buffer_body = content_length <= max_buffer_size
+
+            body_bytes = bytearray()
+            buffer_overflow = False
+
+            # Wrap receive function to capture request body chunks safely
+            async def wrapped_receive():
+                nonlocal buffer_overflow
+                message = await receive()
+                if should_buffer_body and not buffer_overflow and message.get("type") == "http.request":
+                    chunk = message.get("body", b"")
+                    if chunk:
+                        # Enforce hard cap during streaming (e.g. if Content-Length was missing or lying)
+                        if len(body_bytes) + len(chunk) > max_buffer_size:
+                            buffer_overflow = True
+                            body_bytes.clear()  # Free memory immediately
+                            logger.debug("Body size exceeded 1MB cap. Taint extraction disabled for this request.")
+                        else:
+                            body_bytes.extend(chunk)
+
+                    # Trigger parsing only on the final chunk if no overflow occurred
+                    if not message.get("more_body", False) and not buffer_overflow:
+                        try:
+                            # Extract Content-Type header from scope
+                            content_type = ""
+                            for rk, rv in scope.get("headers", []):
+                                if rk.decode("latin-1").lower() == "content-type":
+                                    content_type = rv.decode("latin-1")
+                                    break
+                            
+                            if "application/json" in content_type:
+                                import json
+                                parsed_json = json.loads(body_bytes.decode("utf-8"))
+                                _extract_json_taints(parsed_json, request_id)
+                            elif "application/x-www-form-urlencoded" in content_type:
+                                form_data = body_bytes.decode("utf-8")
+                                for fk, fv in parse_qsl(form_data, keep_blank_values=True):
+                                    if len(fv) >= 6:
+                                        register_taint(fv, source="body", field_name=fk, request_id=request_id)
+                        except Exception as e:
+                            logger.debug(f"Failed to extract body taints: {e}")
+                return message
+
+            # Execute the ASGI application stack passing the wrapped receive
+            await self.app(scope, wrapped_receive, send)
+
+        finally:
+            # 5. Guaranteed cleanup of contextvars memory
+            clear_thread_taint_registry()
+
+
+def _extract_json_taints(data: Any, request_id: str, field_name: str = "") -> None:
+    """Recursively walks parsed JSON payload elements to register string values >= 6 chars."""
+    if isinstance(data, str):
+        if len(data) >= 6:
+            register_taint(data, source="body", field_name=field_name, request_id=request_id)
+    elif isinstance(data, dict):
+        for k, v in data.items():
+            _extract_json_taints(v, request_id, field_name=str(k))
+    elif isinstance(data, list):
+        for idx, item in enumerate(data):
+            _extract_json_taints(item, request_id, field_name=f"{field_name}[{idx}]")

securescout_iast-0.1.0/securescout_iast/patches/__init__.py

@@ -0,0 +1 @@
+# SecureScout IAST patches package

securescout_iast-0.1.0/securescout_iast/patches/asyncpg_patch.py

@@ -0,0 +1,77 @@
+import logging
+import traceback
+from typing import Any
+
+from securescout_iast.taint import check_query_taint, get_endpoint
+
+logger = logging.getLogger("securescout_iast")
+
+_original_execute = None
+_original_fetch = None
+_original_fetchrow = None
+_original_fetchval = None
+
+
+def install_asyncpg_patch(reporter_callback) -> None:
+    """Monkey-patches asyncpg connection queries to inspect query strings."""
+    global _original_execute, _original_fetch, _original_fetchrow, _original_fetchval
+    try:
+        import asyncpg.connection
+
+        _original_execute = asyncpg.connection.Connection.execute
+        _original_fetch = asyncpg.connection.Connection.fetch
+        _original_fetchrow = asyncpg.connection.Connection.fetchrow
+        _original_fetchval = asyncpg.connection.Connection.fetchval
+
+        def _inspect_query(query: Any) -> None:
+            try:
+                query_str = query
+                # If query is a PreparedStatement object, get its raw query text
+                if hasattr(query, "get_query"):
+                    query_str = query.get_query()
+                
+                if isinstance(query_str, str):
+                    match = check_query_taint(query_str)
+                    if match:
+                        stack = [
+                            f"File \"{f.filename}\", line {f.lineno}, in {f.name}\n    {f.line}"
+                            for f in traceback.extract_stack()
+                            if "securescout_iast" not in f.filename
+                        ]
+                        reporter_callback(
+                            rule="sql_injection",
+                            tainted_value=match["tainted_value"],
+                            source=match["source"],
+                            field_name=match["field_name"],
+                            request_id=match["request_id"],
+                            query_snippet=query_str,
+                            stack_trace=stack,
+                            endpoint=get_endpoint()
+                        )
+            except Exception as e:
+                logger.debug(f"asyncpg query hook error: {e}")
+
+        async def custom_execute(self, query, *args, **kwargs):
+            _inspect_query(query)
+            return await _original_execute(self, query, *args, **kwargs)
+
+        async def custom_fetch(self, query, *args, **kwargs):
+            _inspect_query(query)
+            return await _original_fetch(self, query, *args, **kwargs)
+
+        async def custom_fetchrow(self, query, *args, **kwargs):
+            _inspect_query(query)
+            return await _original_fetchrow(self, query, *args, **kwargs)
+
+        async def custom_fetchval(self, query, *args, **kwargs):
+            _inspect_query(query)
+            return await _original_fetchval(self, query, *args, **kwargs)
+
+        asyncpg.connection.Connection.execute = custom_execute
+        asyncpg.connection.Connection.fetch = custom_fetch
+        asyncpg.connection.Connection.fetchrow = custom_fetchrow
+        asyncpg.connection.Connection.fetchval = custom_fetchval
+        logger.info("Successfully patched asyncpg driver.")
+
+    except ImportError:
+        logger.debug("asyncpg driver not found. Skipping patch.")

securescout_iast-0.1.0/securescout_iast/patches/psycopg2_patch.py

@@ -0,0 +1,84 @@
+import logging
+import traceback
+
+from securescout_iast.taint import check_query_taint, get_endpoint
+
+logger = logging.getLogger("securescout_iast")
+
+_original_execute = None
+_original_executemany = None
+
+
+def install_psycopg2_patch(reporter_callback) -> None:
+    """Monkey-patches psycopg2 cursor execute methods to inspect query strings."""
+    global _original_execute, _original_executemany
+    try:
+        import psycopg2.extensions
+        
+        _original_execute = psycopg2.extensions.cursor.execute
+        _original_executemany = psycopg2.extensions.cursor.executemany
+
+        def custom_execute(self, query, vars=None):
+            try:
+                query_str = query
+                if isinstance(query, bytes):
+                    query_str = query.decode("utf-8", errors="ignore")
+                
+                if isinstance(query_str, str):
+                    match = check_query_taint(query_str)
+                    if match:
+                        stack = [
+                            f"File \"{f.filename}\", line {f.lineno}, in {f.name}\n    {f.line}"
+                            for f in traceback.extract_stack()
+                            if "securescout_iast" not in f.filename
+                        ]
+                        reporter_callback(
+                            rule="sql_injection",
+                            tainted_value=match["tainted_value"],
+                            source=match["source"],
+                            field_name=match["field_name"],
+                            request_id=match["request_id"],
+                            query_snippet=query_str,
+                            stack_trace=stack,
+                            endpoint=get_endpoint()
+                        )
+            except Exception as e:
+                logger.debug(f"psycopg2 execute hook error: {e}")
+            
+            return _original_execute(self, query, vars)
+
+        def custom_executemany(self, query, vars_list):
+            try:
+                query_str = query
+                if isinstance(query, bytes):
+                    query_str = query.decode("utf-8", errors="ignore")
+                
+                if isinstance(query_str, str):
+                    match = check_query_taint(query_str)
+                    if match:
+                        stack = [
+                            f"File \"{f.filename}\", line {f.lineno}, in {f.name}\n    {f.line}"
+                            for f in traceback.extract_stack()
+                            if "securescout_iast" not in f.filename
+                        ]
+                        reporter_callback(
+                            rule="sql_injection",
+                            tainted_value=match["tainted_value"],
+                            source=match["source"],
+                            field_name=match["field_name"],
+                            request_id=match["request_id"],
+                            query_snippet=query_str,
+                            stack_trace=stack,
+                            endpoint=get_endpoint()
+                        )
+            except Exception as e:
+                logger.debug(f"psycopg2 executemany hook error: {e}")
+            
+            return _original_executemany(self, query, vars_list)
+
+        psycopg2.extensions.cursor.execute = custom_execute
+        psycopg2.extensions.cursor.executemany = custom_executemany
+        logger.info("Successfully patched psycopg2 driver.")
+
+    except ImportError:
+        logger.debug("psycopg2 driver not found. Skipping patch.")

securescout_iast-0.1.0/securescout_iast/patches/sqlite3_patch.py

@@ -0,0 +1,105 @@
+import logging
+import traceback
+import sqlite3
+
+from securescout_iast.taint import check_query_taint, get_endpoint
+
+logger = logging.getLogger("securescout_iast")
+
+
+class Sqlite3CursorWrapper:
+    """Wrapper that delegates calls to a real sqlite3.Cursor and intercepts query executions."""
+    def __init__(self, cursor, reporter_callback):
+        self._cursor = cursor
+        self._reporter_callback = reporter_callback
+
+    def execute(self, query, parameters=None):
+        try:
+            if isinstance(query, str):
+                match = check_query_taint(query)
+                if match:
+                    stack = [
+                        f"File \"{f.filename}\", line {f.lineno}, in {f.name}\n    {f.line}"
+                        for f in traceback.extract_stack()
+                        if "securescout_iast" not in f.filename
+                    ]
+                    self._reporter_callback(
+                        rule="sql_injection",
+                        tainted_value=match["tainted_value"],
+                        source=match["source"],
+                        field_name=match["field_name"],
+                        request_id=match["request_id"],
+                        query_snippet=query,
+                        stack_trace=stack,
+                        endpoint=get_endpoint()
+                    )
+        except Exception as e:
+            logger.debug(f"sqlite3 execute hook error: {e}")
+
+        if parameters is None:
+            return self._cursor.execute(query)
+        return self._cursor.execute(query, parameters)
+
+    def executemany(self, query, seq_of_parameters):
+        try:
+            if isinstance(query, str):
+                match = check_query_taint(query)
+                if match:
+                    stack = [
+                        f"File \"{f.filename}\", line {f.lineno}, in {f.name}\n    {f.line}"
+                        for f in traceback.extract_stack()
+                        if "securescout_iast" not in f.filename
+                    ]
+                    self._reporter_callback(
+                        rule="sql_injection",
+                        tainted_value=match["tainted_value"],
+                        source=match["source"],
+                        field_name=match["field_name"],
+                        request_id=match["request_id"],
+                        query_snippet=query,
+                        stack_trace=stack,
+                        endpoint=get_endpoint()
+                    )
+        except Exception as e:
+            logger.debug(f"sqlite3 executemany hook error: {e}")
+
+        return self._cursor.executemany(query, seq_of_parameters)
+
+    def __getattr__(self, name):
+        return getattr(self._cursor, name)
+
+    def __iter__(self):
+        return iter(self._cursor)
+
+
+class Sqlite3ConnectionWrapper:
+    """Wrapper that delegates calls to a real sqlite3.Connection and wraps returned cursors."""
+    def __init__(self, connection, reporter_callback):
+        self._connection = connection
+        self._reporter_callback = reporter_callback
+
+    def cursor(self, *args, **kwargs):
+        real_cursor = self._connection.cursor(*args, **kwargs)
+        return Sqlite3CursorWrapper(real_cursor, self._reporter_callback)
+
+    def __enter__(self):
+        self._connection.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        return self._connection.__exit__(exc_type, exc_val, exc_tb)
+
+    def __getattr__(self, name):
+        return getattr(self._connection, name)
+
+
+def install_sqlite3_patch(reporter_callback) -> None:
+    """Monkey-patches the sqlite3.connect module function to return wrapped connections."""
+    _original_connect = sqlite3.connect
+
+    def custom_connect(*args, **kwargs):
+        real_conn = _original_connect(*args, **kwargs)
+        return Sqlite3ConnectionWrapper(real_conn, reporter_callback)
+
+    sqlite3.connect = custom_connect
+    logger.info("Successfully installed sqlite3 wrapper patch.")

securescout_iast-0.1.0/securescout_iast/reporter.py

@@ -0,0 +1,163 @@
+import sys
+import queue
+import threading
+import time
+import json
+import logging
+import urllib.request
+from typing import List, Optional
+
+logger = logging.getLogger("securescout_iast")
+
+# Enforce a hard queue cap to prevent memory leaks during backend outages
+_finding_queue: queue.Queue = queue.Queue(maxsize=500)
+_worker_thread: Optional[threading.Thread] = None
+_api_key: str = ""
+_project_id: str = ""
+_backend_url: str = "https://api.getsecurescout.com"
+_running: bool = False
+
+# Failure / Backoff tracking
+_consecutive_failures: int = 0
+_backoff_until: float = 0.0
+
+
+def init_reporter(api_key: str, project_id: str, backend_url: str = "https://api.getsecurescout.com") -> None:
+    """Initializes the background daemon worker and registers config attributes."""
+    global _api_key, _project_id, _backend_url, _worker_thread, _running
+    _api_key = api_key
+    _project_id = project_id
+    _backend_url = backend_url.rstrip("/")
+    
+    if not _running:
+        _running = True
+        _worker_thread = threading.Thread(target=_reporter_worker, daemon=True)
+        _worker_thread.start()
+        logger.info("SecureScout IAST background reporter initialized.")
+
+
+def queue_finding(
+    rule: str,
+    tainted_value: str,
+    source: str,
+    field_name: str,
+    request_id: str,
+    query_snippet: str,
+    stack_trace: List[str],
+    endpoint: str
+) -> None:
+    """
+    Callback function queued by database patches when a query matches a tainted string.
+    Drops findings on queue overflow to preserve memory limits.
+    """
+    finding = {
+        "rule": rule,
+        "tainted_source": f"{source}:{field_name}" if field_name else source,
+        "query_snippet": query_snippet,
+        "endpoint": endpoint,
+        "stack_trace": stack_trace,
+        "request_id": request_id,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    }
+    
+    try:
+        # Non-blocking put to avoid hanging the customer request thread on overflow
+        _finding_queue.put_nowait(finding)
+    except queue.Full:
+        logger.warning("SecureScout IAST telemetry queue is full. Dropping finding report.")
+
+
+def send_heartbeat(framework: str = "fastapi") -> bool:
+    """Transmits connection heartbeat payload to the backend."""
+    url = f"{_backend_url}/v1/iast/heartbeat"
+    payload = {
+        "project_id": _project_id,
+        "app_metadata": {
+            "agent": "securescout-iast-python",
+            "framework": framework,
+            "python_version": sys.version.split()[0]
+        }
+    }
+    
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "x-api-key": _api_key,
+            "User-Agent": "SecureScout-IAST-Agent/1.0"
+        },
+        method="POST"
+    )
+    
+    try:
+        with urllib.request.urlopen(req, timeout=5) as response:
+            return response.status == 200
+    except Exception as e:
+        logger.debug(f"Failed to transmit IAST heartbeat: {e}")
+        return False
+
+
+def _reporter_worker() -> None:
+    """Daemon thread loop that reads from the queue and aggregates batches of findings."""
+    global _running, _backoff_until
+    while _running:
+        # If backing off, sleep briefly and skip loop to avoid hammering the backend
+        if time.time() < _backoff_until:
+            time.sleep(5)
+            continue
+
+        batch = []
+        try:
+            # Block up to 5 seconds waiting for a queued finding
+            item = _finding_queue.get(timeout=5)
+            batch.append(item)
+            
+            # Drain up to 10 additional findings currently in the queue
+            while len(batch) < 10:
+                try:
+                    batch.append(_finding_queue.get_nowait())
+                except queue.Empty:
+                    break
+        except queue.Empty:
+            pass
+
+        if batch:
+            _send_batch(batch)
+
+
+def _send_batch(batch: List[dict]) -> bool:
+    """Sends aggregated payload batch to the IAST findings endpoint. Implements backoff."""
+    global _consecutive_failures, _backoff_until
+    url = f"{_backend_url}/v1/iast/findings"
+    payload = {
+        "project_id": _project_id,
+        "findings": batch
+    }
+    
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "x-api-key": _api_key,
+            "User-Agent": "SecureScout-IAST-Agent/1.0"
+        },
+        method="POST"
+    )
+    
+    try:
+        with urllib.request.urlopen(req, timeout=5) as response:
+            if response.status == 202:
+                _consecutive_failures = 0
+                return True
+            else:
+                logger.debug(f"SecureScout IAST findings ingestion rejected with status code: {response.status}")
+    except Exception as e:
+        logger.debug(f"Failed to transmit IAST findings payload: {e}")
+
+    _consecutive_failures += 1
+    if _consecutive_failures >= 3:
+        _backoff_until = time.time() + 30  # Back off for 30 seconds
+        logger.debug("SecureScout IAST reporter detected 3+ consecutive failures. Backing off for 30s.")
+    return False

securescout_iast-0.1.0/securescout_iast/taint.py

@@ -0,0 +1,174 @@
+import contextvars
+from typing import Optional, List, Any, Dict, Set
+
+# ContextVar storing a dictionary of: raw_tainted_string -> metadata_dict
+_taint_registry: contextvars.ContextVar[Dict[str, dict]] = contextvars.ContextVar("securescout_iast_registry")
+
+# ContextVar storing the HTTP endpoint string (e.g. "GET /api/users") for the request context
+_endpoint_var: contextvars.ContextVar[str] = contextvars.ContextVar("securescout_iast_endpoint", default="unknown")
+
+
+def init_request_taint_registry() -> Dict[str, dict]:
+    """Initializes a fresh, task-isolated metadata dict for the current request context."""
+    registry = {}
+    _taint_registry.set(registry)
+    return registry
+
+
+def register_taint(value: str, source: str, field_name: str, request_id: str) -> None:
+    """Registers a tainted string value and its provenance metadata."""
+    if not value:
+        return
+    try:
+        registry = _taint_registry.get()
+    except LookupError:
+        registry = init_request_taint_registry()
+    
+    registry[value] = {
+        "source": source,
+        "field_name": field_name,
+        "request_id": request_id
+    }
+
+
+def get_taint_metadata(value: str) -> Optional[dict]:
+    """Retrieves provenance metadata for a given tainted string value."""
+    try:
+        return _taint_registry.get().get(value)
+    except LookupError:
+        return None
+
+
+def clear_thread_taint_registry() -> None:
+    """Clears task-local metadata dict to release memory."""
+    try:
+        _taint_registry.get().clear()
+    except Exception:
+        pass
+
+
+def check_query_taint(query: str) -> Optional[dict]:
+    """
+    Scans a query string for any registered tainted values.
+    Returns the metadata dict of the matched taint if found.
+    """
+    try:
+        registry = _taint_registry.get()
+    except LookupError:
+        return None
+
+    for tainted_val, meta in registry.items():
+        if tainted_val in query:
+            return {
+                "tainted_value": tainted_val,
+                "source": meta["source"],
+                "field_name": meta["field_name"],
+                "request_id": meta["request_id"]
+            }
+    return None
+
+
+def register_endpoint(request_id: str, endpoint: str) -> None:
+    """Registers the HTTP endpoint (method + path) for the current request context."""
+    _endpoint_var.set(endpoint)
+
+
+def get_endpoint() -> str:
+    """Retrieves the HTTP endpoint associated with the current request context."""
+    try:
+        return _endpoint_var.get()
+    except LookupError:
+        return "unknown"
+
+
+class TaintedStr(str):
+    """
+    A subclass of str that carries provenance metadata indicating
+    it originated from an untrusted source.
+    """
+    def __new__(
+        cls,
+        value: Any,
+        source: Optional[str] = None,
+        field_name: Optional[str] = None,
+        request_id: Optional[str] = None
+    ):
+        obj = str.__new__(cls, value)
+        obj.source = source
+        obj.field_name = field_name
+        obj.request_id = request_id
+        return obj
+
+    def _clone(self, new_value: str) -> "TaintedStr":
+        """Clones the taint metadata to a new string value."""
+        return TaintedStr(
+            new_value,
+            source=self.source,
+            field_name=self.field_name,
+            request_id=self.request_id
+        )
+
+    def __add__(self, other: Any) -> "TaintedStr":
+        res = super().__add__(str(other))
+        return self._clone(res)
+
+    def __radd__(self, other: Any) -> "TaintedStr":
+        res = str(other) + str(self)
+        return self._clone(res)
+
+    def __mod__(self, other: Any) -> "TaintedStr":
+        res = super().__mod__(other)
+        return self._clone(res)
+
+    def __rmod__(self, other: Any) -> "TaintedStr":
+        res = str(other) % str(self)
+        return self._clone(res)
+
+    def __getitem__(self, index: Any) -> "TaintedStr":
+        res = super().__getitem__(index)
+        return self._clone(res)
+
+    def __format__(self, format_spec: str) -> str:
+        res = super().__format__(format_spec)
+        # Register in task-local storage if the tainted string is long enough
+        # to avoid false positives on common short substrings (e.g. "id", "abc", "1")
+        if len(self) >= 6:
+            register_taint(str(self), source=self.source or "formatted", field_name=self.field_name or "unknown", request_id=self.request_id or "unknown")
+        return res
+
+    def replace(self, old: str, new: str, count: int = -1) -> "TaintedStr":
+        res = super().replace(old, new, count)
+        return self._clone(res)
+
+    def split(self, sep: Optional[str] = None, maxsplit: int = -1) -> List["TaintedStr"]:
+        res = super().split(sep, maxsplit)
+        return [self._clone(item) for item in res]
+
+    def strip(self, chars: Optional[str] = None) -> "TaintedStr":
+        res = super().strip(chars)
+        return self._clone(res)
+
+    def lstrip(self, chars: Optional[str] = None) -> "TaintedStr":
+        res = super().lstrip(chars)
+        return self._clone(res)
+
+    def rstrip(self, chars: Optional[str] = None) -> "TaintedStr":
+        res = super().rstrip(chars)
+        return self._clone(res)
+
+    def lower(self) -> "TaintedStr":
+        res = super().lower()
+        return self._clone(res)
+
+    def upper(self) -> "TaintedStr":
+        res = super().upper()
+        return self._clone(res)
+
+    def join(self, iterable: Any) -> "TaintedStr":
+        res = super().join(iterable)
+        return self._clone(res)
+
+
+def is_tainted(value: Any) -> bool:
+    """Helper function to check if a value is a TaintedStr."""
+    return isinstance(value, TaintedStr)

securescout_iast-0.1.0/securescout_iast.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: securescout-iast
+Version: 0.1.0
+Summary: Interactive Application Security Testing (IAST) runtime agent for Python
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# securescout-iast
+
+Interactive Application Security Testing (IAST) runtime agent for Python web applications. Detects SQL injection vulnerabilities in real time by tracing untrusted request data as it flows into database queries during normal application traffic.
+
+## How it works
+
+`securescout-iast` tags incoming request data (query parameters, headers, cookies, and JSON/form body) at the ASGI layer, then watches for that data appearing in raw SQL execute calls. If untrusted input reaches a database query without being safely parameterized, a finding is reported to your SecureScout dashboard — confirmed by actual runtime execution, not static guesswork.
+
+## Installation
+
+```bash
+pip install securescout-iast
+```
+
+## Quick start (FastAPI / Starlette)
+
+```python
+from fastapi import FastAPI
+from securescout_iast import SecureScoutIastMiddleware, init
+
+app = FastAPI()
+
+init(
+    api_key="ssk_live_your_api_key",
+    project_id="your-project-id",
+)
+app.add_middleware(SecureScoutIastMiddleware)
+```
+
+Get your API key and project ID from **Settings → API Keys** and your project's **Runtime (IAST)** tab in the SecureScout dashboard.
+
+## Supported database drivers
+
+- `psycopg2` (sync PostgreSQL)
+- `asyncpg` (async PostgreSQL, including async SQLAlchemy)
+
+Drivers are detected automatically. If a driver isn't installed in your environment, that patch is silently skipped — no errors, no extra dependencies pulled in.
+
+## Detected vulnerability classes
+
+- SQL Injection (CWE-89) — v1
+
+## Safety guarantees
+
+- `init()` never raises. Misconfiguration or network issues degrade to a silent no-op, never a crash.
+- Your request and database driver behavior are never modified — the agent only observes.
+- Request bodies over 1MB are not buffered for taint analysis (still passed through to your app unmodified).
+- No third-party dependencies. Pure standard library.
+
+## Privacy
+
+This agent inspects request data and SQL query text locally, within your application process, to detect taint matches. Only confirmed findings (rule type, query snippet, stack trace, endpoint) are sent to SecureScout — never raw request bodies or full traffic.
+
+## License
+
+MIT

securescout_iast-0.1.0/securescout_iast.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+securescout_iast/__init__.py
+securescout_iast/config.py
+securescout_iast/middleware.py
+securescout_iast/reporter.py
+securescout_iast/taint.py
+securescout_iast.egg-info/PKG-INFO
+securescout_iast.egg-info/SOURCES.txt
+securescout_iast.egg-info/dependency_links.txt
+securescout_iast.egg-info/top_level.txt
+securescout_iast/patches/__init__.py
+securescout_iast/patches/asyncpg_patch.py
+securescout_iast/patches/psycopg2_patch.py
+securescout_iast/patches/sqlite3_patch.py
+tests/test_taint_propagation.py

securescout_iast-0.1.0/securescout_iast.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

securescout_iast-0.1.0/securescout_iast.egg-info/top_level.txt

@@ -0,0 +1 @@
+securescout_iast

securescout_iast-0.1.0/setup.cfg

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

securescout_iast-0.1.0/tests/test_taint_propagation.py

@@ -0,0 +1,137 @@
+import sys
+import types
+import pytest
+import contextvars
+
+from securescout_iast.taint import (
+    TaintedStr,
+    register_taint,
+    check_query_taint,
+    init_request_taint_registry,
+    get_endpoint,
+    register_endpoint
+)
+from securescout_iast.patches.psycopg2_patch import install_psycopg2_patch
+
+
+def test_tainted_str_propagation():
+    """Verifies that TaintedStr propagates its type and metadata through common string operations."""
+    t = TaintedStr("O-Malley", source="query_param", field_name="username", request_id="req-123")
+    
+    # Concatenation (+)
+    res_add = "SELECT * FROM users WHERE name = '" + t + "'"
+    assert isinstance(res_add, TaintedStr)
+    assert res_add.source == "query_param"
+    assert res_add.field_name == "username"
+    assert res_add.request_id == "req-123"
+
+    # Reflected Concat
+    res_radd = t + " LIMIT 1"
+    assert isinstance(res_radd, TaintedStr)
+
+    # Replace
+    res_rep = t.replace("O-", "O")
+    assert isinstance(res_rep, TaintedStr)
+    assert res_rep == "OMalley"
+
+    # Strip
+    t_padded = TaintedStr("  O-Malley  ", source="query_param", field_name="username", request_id="req-123")
+    res_strip = t_padded.strip()
+    assert isinstance(res_strip, TaintedStr)
+    assert res_strip == "O-Malley"
+
+    # Slicing (__getitem__)
+    res_slice = t[0:3]
+    assert isinstance(res_slice, TaintedStr)
+    assert res_slice == "O-M"
+
+    # Modulo format (%)
+    res_mod = "SELECT * FROM users WHERE name = '%s'" % t
+    assert isinstance(res_mod, TaintedStr)
+    assert "O-Malley" in res_mod
+
+
+def test_registry_matching_and_isolation():
+    """Verifies that register_taint and check_query_taint are context-isolated."""
+    # 1. Simulate Request A
+    ctx_a = contextvars.copy_context()
+    def run_a():
+        init_request_taint_registry()
+        register_taint("O-Malley", source="query_param", field_name="name", request_id="a")
+        
+        # Match expected
+        match = check_query_taint("SELECT * FROM users WHERE name = 'O-Malley'")
+        assert match is not None
+        assert match["request_id"] == "a"
+        
+        # Clean query
+        assert check_query_taint("SELECT * FROM users WHERE name = %s") is None
+        
+    ctx_a.run(run_a)
+
+    # 2. Simulate Request B (should be isolated from Request A)
+    ctx_b = contextvars.copy_context()
+    def run_b():
+        init_request_taint_registry()
+        # Should not see Request A's taint
+        assert check_query_taint("SELECT * FROM users WHERE name = 'O-Malley'") is None
+        
+        register_taint("admin_user", source="body", field_name="role", request_id="b")
+        match = check_query_taint("UPDATE users SET role = 'admin_user'")
+        assert match is not None
+        assert match["request_id"] == "b"
+        
+    ctx_b.run(run_b)
+
+
+def test_psycopg2_driver_mock_patching():
+    """Mocks psycopg2 class structures and tests executing the patcher pipeline."""
+    # 1. Construct a mock psycopg2 module
+    mock_psycopg2 = types.ModuleType("psycopg2")
+    mock_psycopg2.extensions = types.ModuleType("psycopg2.extensions")
+    
+    class DummyCursor:
+        def execute(self, query, vars=None):
+            return "executed"
+            
+        def executemany(self, query, vars_list):
+            return "executed many"
+
+    mock_psycopg2.extensions.cursor = DummyCursor
+    sys.modules["psycopg2"] = mock_psycopg2
+    sys.modules["psycopg2.extensions"] = mock_psycopg2.extensions
+
+    # 2. Install the patch
+    reporter_calls = []
+    def dummy_reporter(**kwargs):
+        reporter_calls.append(kwargs)
+
+    install_psycopg2_patch(dummy_reporter)
+
+    # 3. Simulate context request
+    ctx = contextvars.copy_context()
+    def run_test():
+        init_request_taint_registry()
+        register_endpoint("req-789", "POST /api/login")
+        register_taint("compromised_value", source="query_param", field_name="id", request_id="req-789")
+
+        cursor = mock_psycopg2.extensions.cursor()
+
+        # Vulnerable call: concatenated tainted string
+        cursor.execute("SELECT * FROM items WHERE id = 'compromised_value'")
+        assert len(reporter_calls) == 1
+        assert reporter_calls[0]["rule"] == "sql_injection"
+        assert reporter_calls[0]["tainted_value"] == "compromised_value"
+        assert reporter_calls[0]["endpoint"] == "POST /api/login"
+        assert reporter_calls[0]["source"] == "query_param"
+
+        # Safe call: parameterized query (no match)
+        reporter_calls.clear()
+        cursor.execute("SELECT * FROM items WHERE id = %s", ("compromised_value",))
+        assert len(reporter_calls) == 0
+
+    ctx.run(run_test)
+
+    # Clean up mock from sys.modules
+    sys.modules.pop("psycopg2", None)
+    sys.modules.pop("psycopg2.extensions", None)