strix-agent 0.4.0__py3-none-any.whl

strix/llm/request_queue.py

@@ -0,0 +1,87 @@
+import asyncio
+import logging
+import os
+import threading
+import time
+from typing import Any
+
+import litellm
+from litellm import ModelResponse, completion
+from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential
+
+
+logger = logging.getLogger(__name__)
+
+
+def should_retry_exception(exception: Exception) -> bool:
+    status_code = None
+
+    if hasattr(exception, "status_code"):
+        status_code = exception.status_code
+    elif hasattr(exception, "response") and hasattr(exception.response, "status_code"):
+        status_code = exception.response.status_code
+
+    if status_code is not None:
+        return bool(litellm._should_retry(status_code))
+    return True
+
+
+class LLMRequestQueue:
+    def __init__(self, max_concurrent: int = 6, delay_between_requests: float = 5.0):
+        rate_limit_delay = os.getenv("LLM_RATE_LIMIT_DELAY")
+        if rate_limit_delay:
+            delay_between_requests = float(rate_limit_delay)
+
+        rate_limit_concurrent = os.getenv("LLM_RATE_LIMIT_CONCURRENT")
+        if rate_limit_concurrent:
+            max_concurrent = int(rate_limit_concurrent)
+
+        self.max_concurrent = max_concurrent
+        self.delay_between_requests = delay_between_requests
+        self._semaphore = threading.BoundedSemaphore(max_concurrent)
+        self._last_request_time = 0.0
+        self._lock = threading.Lock()
+
+    async def make_request(self, completion_args: dict[str, Any]) -> ModelResponse:
+        try:
+            while not self._semaphore.acquire(timeout=0.2):
+                await asyncio.sleep(0.1)
+
+            with self._lock:
+                now = time.time()
+                time_since_last = now - self._last_request_time
+                sleep_needed = max(0, self.delay_between_requests - time_since_last)
+                self._last_request_time = now + sleep_needed
+
+            if sleep_needed > 0:
+                await asyncio.sleep(sleep_needed)
+
+            return await self._reliable_request(completion_args)
+        finally:
+            self._semaphore.release()
+
+    @retry(  # type: ignore[misc]
+        stop=stop_after_attempt(7),
+        wait=wait_exponential(multiplier=6, min=12, max=150),
+        retry=retry_if_exception(should_retry_exception),
+        reraise=True,
+    )
+    async def _reliable_request(self, completion_args: dict[str, Any]) -> ModelResponse:
+        response = completion(**completion_args, stream=False)
+        if isinstance(response, ModelResponse):
+            return response
+        self._raise_unexpected_response()
+        raise RuntimeError("Unreachable code")
+
+    def _raise_unexpected_response(self) -> None:
+        raise RuntimeError("Unexpected response type")
+
+
+_global_queue: LLMRequestQueue | None = None
+
+
+def get_global_queue() -> LLMRequestQueue:
+    global _global_queue  # noqa: PLW0603
+    if _global_queue is None:
+        _global_queue = LLMRequestQueue()
+    return _global_queue

strix/llm/utils.py

@@ -0,0 +1,87 @@
+import html
+import re
+from typing import Any
+
+
+def _truncate_to_first_function(content: str) -> str:
+    if not content:
+        return content
+
+    function_starts = [match.start() for match in re.finditer(r"<function=", content)]
+
+    if len(function_starts) >= 2:
+        second_function_start = function_starts[1]
+
+        return content[:second_function_start].rstrip()
+
+    return content
+
+
+def parse_tool_invocations(content: str) -> list[dict[str, Any]] | None:
+    content = _fix_stopword(content)
+
+    tool_invocations: list[dict[str, Any]] = []
+
+    fn_regex_pattern = r"<function=([^>]+)>\n?(.*?)</function>"
+    fn_param_regex_pattern = r"<parameter=([^>]+)>(.*?)</parameter>"
+
+    fn_matches = re.finditer(fn_regex_pattern, content, re.DOTALL)
+
+    for fn_match in fn_matches:
+        fn_name = fn_match.group(1)
+        fn_body = fn_match.group(2)
+
+        param_matches = re.finditer(fn_param_regex_pattern, fn_body, re.DOTALL)
+
+        args = {}
+        for param_match in param_matches:
+            param_name = param_match.group(1)
+            param_value = param_match.group(2).strip()
+
+            param_value = html.unescape(param_value)
+            args[param_name] = param_value
+
+        tool_invocations.append({"toolName": fn_name, "args": args})
+
+    return tool_invocations if tool_invocations else None
+
+
+def _fix_stopword(content: str) -> str:
+    if "<function=" in content and content.count("<function=") == 1:
+        if content.endswith("</"):
+            content = content.rstrip() + "function>"
+        elif not content.rstrip().endswith("</function>"):
+            content = content + "\n</function>"
+    return content
+
+
+def format_tool_call(tool_name: str, args: dict[str, Any]) -> str:
+    xml_parts = [f"<function={tool_name}>"]
+
+    for key, value in args.items():
+        xml_parts.append(f"<parameter={key}>{value}</parameter>")
+
+    xml_parts.append("</function>")
+
+    return "\n".join(xml_parts)
+
+
+def clean_content(content: str) -> str:
+    if not content:
+        return ""
+
+    content = _fix_stopword(content)
+
+    tool_pattern = r"<function=[^>]+>.*?</function>"
+    cleaned = re.sub(tool_pattern, "", content, flags=re.DOTALL)
+
+    hidden_xml_patterns = [
+        r"<inter_agent_message>.*?</inter_agent_message>",
+        r"<agent_completion_report>.*?</agent_completion_report>",
+    ]
+    for pattern in hidden_xml_patterns:
+        cleaned = re.sub(pattern, "", cleaned, flags=re.DOTALL | re.IGNORECASE)
+
+    cleaned = re.sub(r"\n\s*\n", "\n\n", cleaned)
+
+    return cleaned.strip()

strix/prompts/README.md

@@ -0,0 +1,64 @@
+# 📚 Strix Prompt Modules
+
+## 🎯 Overview
+
+Prompt modules are specialized knowledge packages that enhance Strix agents with deep expertise in specific vulnerability types, technologies, and testing methodologies. Each module provides advanced techniques, practical examples, and validation methods that go beyond baseline security knowledge.
+
+---
+
+## 🏗️ Architecture
+
+### How Prompts Work
+
+When an agent is created, it can load up to 5 specialized prompt modules relevant to the specific subtask and context at hand:
+
+```python
+# Agent creation with specialized modules
+create_agent(
+    task="Test authentication mechanisms in API",
+    name="Auth Specialist",
+    prompt_modules="authentication_jwt,business_logic"
+)
+```
+
+The modules are dynamically injected into the agent's system prompt, allowing it to operate with deep expertise tailored to the specific vulnerability types or technologies required for the task at hand.
+
+---
+
+## 📁 Module Categories
+
+| Category | Purpose |
+|----------|---------|
+| **`/vulnerabilities`** | Advanced testing techniques for core vulnerability classes like authentication bypasses, business logic flaws, and race conditions |
+| **`/frameworks`** | Specific testing methods for popular frameworks e.g. Django, Express, FastAPI, and Next.js |
+| **`/technologies`** | Specialized techniques for third-party services such as Supabase, Firebase, Auth0, and payment gateways |
+| **`/protocols`** | Protocol-specific testing patterns for GraphQL, WebSocket, OAuth, and other communication standards |
+| **`/cloud`** | Cloud provider security testing for AWS, Azure, GCP, and Kubernetes environments |
+| **`/reconnaissance`** | Advanced information gathering and enumeration techniques for comprehensive attack surface mapping |
+| **`/custom`** | Community-contributed modules for specialized or industry-specific testing scenarios |
+
+---
+
+## 🎨 Creating New Modules
+
+### What Should a Module Contain?
+
+A good prompt module is a structured knowledge package that typically includes:
+
+- **Advanced techniques** - Non-obvious methods specific to the task and domain
+- **Practical examples** - Working payloads, commands, or test cases with variations
+- **Validation methods** - How to confirm findings and avoid false positives
+- **Context-specific insights** - Environment and version nuances, configuration-dependent behavior, and edge cases
+
+Modules use XML-style tags for structure and focus on deep, specialized knowledge that significantly enhances agent capabilities for that specific context.
+
+---
+
+## 🤝 Contributing
+
+Community contributions are more than welcome — contribute new modules via [pull requests](https://github.com/usestrix/strix/pulls) or [GitHub issues](https://github.com/usestrix/strix/issues) to help expand the collection and improve extensibility for Strix agents.
+
+---
+
+> [!NOTE]
+> **Work in Progress** - We're actively expanding the prompt module collection with specialized techniques and new categories.

strix/prompts/__init__.py

@@ -0,0 +1,109 @@
+from pathlib import Path
+
+from jinja2 import Environment
+
+
+def get_available_prompt_modules() -> dict[str, list[str]]:
+    modules_dir = Path(__file__).parent
+    available_modules = {}
+
+    for category_dir in modules_dir.iterdir():
+        if category_dir.is_dir() and not category_dir.name.startswith("__"):
+            category_name = category_dir.name
+            modules = []
+
+            for file_path in category_dir.glob("*.jinja"):
+                module_name = file_path.stem
+                modules.append(module_name)
+
+            if modules:
+                available_modules[category_name] = sorted(modules)
+
+    return available_modules
+
+
+def get_all_module_names() -> set[str]:
+    all_modules = set()
+    for category_modules in get_available_prompt_modules().values():
+        all_modules.update(category_modules)
+    return all_modules
+
+
+def validate_module_names(module_names: list[str]) -> dict[str, list[str]]:
+    available_modules = get_all_module_names()
+    valid_modules = []
+    invalid_modules = []
+
+    for module_name in module_names:
+        if module_name in available_modules:
+            valid_modules.append(module_name)
+        else:
+            invalid_modules.append(module_name)
+
+    return {"valid": valid_modules, "invalid": invalid_modules}
+
+
+def generate_modules_description() -> str:
+    available_modules = get_available_prompt_modules()
+
+    if not available_modules:
+        return "No prompt modules available"
+
+    all_module_names = get_all_module_names()
+
+    if not all_module_names:
+        return "No prompt modules available"
+
+    sorted_modules = sorted(all_module_names)
+    modules_str = ", ".join(sorted_modules)
+
+    description = (
+        f"List of prompt modules to load for this agent (max 5). Available modules: {modules_str}. "
+    )
+
+    example_modules = sorted_modules[:2]
+    if example_modules:
+        example = f"Example: {', '.join(example_modules)} for specialized agent"
+        description += example
+
+    return description
+
+
+def load_prompt_modules(module_names: list[str], jinja_env: Environment) -> dict[str, str]:
+    import logging
+
+    logger = logging.getLogger(__name__)
+    module_content = {}
+    prompts_dir = Path(__file__).parent
+
+    available_modules = get_available_prompt_modules()
+
+    for module_name in module_names:
+        try:
+            module_path = None
+
+            if "/" in module_name:
+                module_path = f"{module_name}.jinja"
+            else:
+                for category, modules in available_modules.items():
+                    if module_name in modules:
+                        module_path = f"{category}/{module_name}.jinja"
+                        break
+
+                if not module_path:
+                    root_candidate = f"{module_name}.jinja"
+                    if (prompts_dir / root_candidate).exists():
+                        module_path = root_candidate
+
+            if module_path and (prompts_dir / module_path).exists():
+                template = jinja_env.get_template(module_path)
+                var_name = module_name.split("/")[-1]
+                module_content[var_name] = template.render()
+                logger.info(f"Loaded prompt module: {module_name} -> {var_name}")
+            else:
+                logger.warning(f"Prompt module not found: {module_name}")
+
+        except (FileNotFoundError, OSError, ValueError) as e:
+            logger.warning(f"Failed to load prompt module {module_name}: {e}")
+
+    return module_content

strix/prompts/coordination/root_agent.jinja

@@ -0,0 +1,41 @@
+<coordination_role>
+You are a COORDINATION AGENT ONLY. You do NOT perform any security testing, vulnerability assessment, or technical work yourself.
+
+Your ONLY responsibilities:
+1. Create specialized agents for specific security tasks
+2. Monitor agent progress and coordinate between them
+3. Compile final scan reports from agent findings
+4. Manage agent communication and dependencies
+
+CRITICAL RESTRICTIONS:
+- NEVER perform vulnerability testing or security assessments
+- NEVER write detailed vulnerability reports (only compile final summaries)
+- ONLY use agent_graph and finish tools for coordination
+- You can create agents throughout the scan process, depending on the task and findings, not just at the beginning!
+</coordination_role>
+
+<agent_management>
+BEFORE CREATING AGENTS:
+1. Analyze the target scope and break into independent tasks
+2. Check existing agents to avoid duplication
+3. Create agents with clear, specific objectives to avoid duplication
+
+AGENT TYPES YOU CAN CREATE:
+- Reconnaissance: subdomain enum, port scanning, tech identification, etc.
+- Vulnerability Testing: SQL injection, XSS, auth bypass, IDOR, RCE, SSRF, etc. Can be black-box or white-box.
+    - Direct vulnerability testing agents to implement hierarchical workflow (per finding: discover, verify, report, fix): each one should create validation agents for findings verification, which spawn reporting agents for documentation, which create fix agents for remediation
+
+COORDINATION GUIDELINES:
+- Ensure clear task boundaries and success criteria
+- Terminate redundant agents when objectives overlap
+- Use message passing only when essential (requests/answers or critical handoffs); avoid routine status messages and prefer batched updates
+</agent_management>
+
+<final_responsibilities>
+When all agents complete:
+1. Collect findings from all agents
+2. Compile a final scan summary report
+3. Use finish tool to complete the assessment
+
+Your value is in orchestration, not execution.
+</final_responsibilities>

strix/prompts/frameworks/fastapi.jinja

@@ -0,0 +1,142 @@
+<fastapi_security_testing_guide>
+<title>FASTAPI — ADVERSARIAL TESTING PLAYBOOK</title>
+
+<critical>FastAPI (on Starlette) spans HTTP, WebSocket, and background tasks with powerful dependency injection and automatic OpenAPI. Security breaks where identity, authorization, and validation drift across routers, middlewares, proxies, and channels. Treat every dependency, header, and object reference as untrusted until bound to the caller and tenant.</critical>
+
+<surface_map>
+- ASGI stack: Starlette middlewares (CORS, TrustedHost, ProxyHeaders, Session), exception handlers, lifespan events
+- Routers/sub-apps: APIRouter with prefixes/tags, mounted apps (StaticFiles, admin subapps), `include_router`, versioned paths
+- Security and DI: `Depends`, `Security`, `OAuth2PasswordBearer`, `HTTPBearer`, scopes, per-router vs per-route dependencies
+- Models and validation: Pydantic v1/v2 models, unions/Annotated, custom validators, extra fields policy, coercion
+- Docs and schema: `/openapi.json`, `/docs`, `/redoc`, alternative docs_url/redoc_url, schema extensions
+- Files and static: `UploadFile`, `File`, `FileResponse`, `StaticFiles` mounts, template engines (`Jinja2Templates`)
+- Channels: HTTP (sync/async), WebSocket, StreamingResponse/SSE, BackgroundTasks/Task queues
+- Deployment: Uvicorn/Gunicorn, reverse proxies/CDN, TLS termination, header trust
+</surface_map>
+
+<methodology>
+1. Enumerate routes from OpenAPI and via crawling; diff with 404-fuzzing for hidden endpoints (`include_in_schema=False`).
+2. Build a Principal × Channel × Content-Type matrix (unauth, user, staff/admin; HTTP vs WebSocket; JSON/form/multipart) and capture baselines.
+3. For each route, identify dependencies (router-level and route-level). Attempt to satisfy security dependencies minimally, then mutate context (tokens, scopes, tenant headers) and object IDs.
+4. Compare behavior across deployments: dev/stage/prod often differ in middlewares (CORS, TrustedHost, ProxyHeaders) and docs exposure.
+</methodology>
+
+<high_value_targets>
+- `/openapi.json`, `/docs`, `/redoc` in production (full attack surface map; securitySchemes and server URLs)
+- Auth flows: token endpoints, session/cookie bridges, OAuth device/PKCE, scope checks
+- Admin/staff routers, feature-flagged routes, `include_in_schema=False` endpoints
+- File upload/download, import/export/report endpoints, signed URL generators
+- WebSocket endpoints carrying notifications, admin channels, or commands
+- Background job creation/fetch (`/jobs/{id}`, `/tasks/{id}/result`)
+- Mounted subapps (admin UI, storage browsers, metrics/health endpoints)
+</high_value_targets>
+
+<advanced_techniques>
+<openapi_and_docs>
+- Try default and alternate locations: `/openapi.json`, `/docs`, `/redoc`, `/api/openapi.json`, `/internal/openapi.json`.
+- If OpenAPI is exposed, mine: paths, parameter names, securitySchemes, scopes, servers; find endpoints hidden in UI but present in schema.
+- Schema drift: endpoints with `include_in_schema=False` won’t appear—use wordlists based on tags/prefixes and common admin/debug names.
+</openapi_and_docs>
+
+<dependency_injection_and_security>
+- Router vs route dependencies: routes may miss security dependencies present elsewhere; check for unprotected variants of protected actions.
+- Minimal satisfaction: `OAuth2PasswordBearer` only yields a token string—verify if any route treats token presence as auth without verification.
+- Scope checks: ensure scopes are enforced by the dependency (e.g., `Security(...)`); routes using `Depends` instead may ignore requested scopes.
+- Header/param aliasing: DI sources headers/cookies/query by name; try case variations and duplicates to influence which value binds.
+</dependency_injection_and_security>
+
+<auth_and_jwt>
+- Token misuse: developers may decode JWTs without verifying signature/issuer/audience; attempt unsigned/attacker-signed tokens and cross-service audiences.
+- Algorithm/key confusion: try HS/RS cross-use if verification is not pinned; inject `kid` header targeting local files/paths where custom key lookup exists.
+- Session bridges: check cookies set via SessionMiddleware or custom cookies. Attempt session fixation and forging if weak `secret_key` or predictable signing is used.
+- Device/PKCE flows: verify strict PKCE S256 and state/nonce enforcement if OAuth/OIDC is integrated.
+</auth_and_jwt>
+
+<cors_and_csrf>
+- CORS reflection: broad `allow_origin_regex` or mis-specified origins can permit cross-site reads; test arbitrary Origins and credentialed requests.
+- CSRF: FastAPI/Starlette lack built-in CSRF. If cookies carry auth, attempt state-changing requests via cross-site forms/XHR; validate origin header checks and same-site settings.
+</cors_and_csrf>
+
+<proxy_and_host_trust>
+- ProxyHeadersMiddleware: if enabled without network boundary, spoof `X-Forwarded-For/Proto` to influence auth/IP gating and secure redirects.
+- TrustedHostMiddleware absent or lax: perform Host header poisoning; attempt password reset links / absolute URL generation under attacker host.
+- Upstream/CDN cache keys: ensure Vary on Authorization/Cookie/Tenant; try cache key confusion to leak personalized responses.
+</proxy_and_host_trust>
+
+<static_and_uploads>
+- UploadFile.filename: attempt path traversal and control characters; verify server joins/sanitizes and enforces storage roots.
+- FileResponse/StaticFiles: confirm directory boundaries and index/auto-listing; probe symlinks and case/encoding variants.
+- Parser differentials: send JSON vs multipart for the same route to hit divergent code paths/validators.
+</static_and_uploads>
+
+<template_injection>
+- Jinja2 templates via `TemplateResponse`: search for unescaped injection in variables and filters. Probe with minimal expressions:
+{% raw %}- `{{7*7}}` → arithmetic confirmation
+- `{{cycler.__init__.__globals__['os'].popen('id').read()}}` for RCE in unsafe contexts{% endraw %}
+- Confirm autoescape and strict sandboxing; inspect custom filters/globals.
+</template_injection>
+
+<ssrf_and_outbound>
+- Endpoints fetching user-supplied URLs (imports, previews, webhooks validation): test loopback/RFC1918/IPv6, redirects, DNS rebinding, and header control.
+- Library behavior (httpx/requests): examine redirect policy, header forwarding, and protocol support; try `file://`, `ftp://`, or gopher-like shims if custom clients are used.
+</ssrf_and_outbound>
+
+<websockets>
+- Authenticate each connection (query/header/cookie). Attempt cross-origin handshakes and cookie-bearing WS from untrusted origins.
+- Topic naming and authorization: if using user/tenant IDs in channels, subscribe/publish to foreign IDs.
+- Message-level checks: ensure per-message authorization, not only at handshake.
+</websockets>
+
+<background_tasks_and_jobs>
+- BackgroundTasks that act on IDs must re-enforce ownership/tenant at execution time. Attempt to fetch/cancel others’ jobs by referencing their IDs.
+- Export/import pipelines: test job/result endpoints for IDOR and cross-tenant leaks.
+</background_tasks_and_jobs>
+
+<multi_app_mounting>
+- Mounted subapps (e.g., `/admin`, `/static`, `/metrics`) may bypass global middlewares. Confirm middleware parity and auth on mounts.
+</multi_app_mounting>
+</advanced_techniques>
+
+<bypass_techniques>
+- Content-type switching: `application/json` ↔ `application/x-www-form-urlencoded` ↔ `multipart/form-data` to traverse alternate validators/handlers.
+- Parameter duplication and case variants to exploit DI precedence.
+- Method confusion via proxies (e.g., `X-HTTP-Method-Override`) if upstream respects it while app does not.
+- Race windows around dependency-validated state transitions (issue token then mutate with parallel requests).
+</bypass_techniques>
+
+<special_contexts>
+<pydantic_edges>
+- Coercion: strings to ints/bools, empty strings to None; exploit truthiness and boundary conditions.
+- Extra fields: if models allow/ignore extras, sneak in control fields for downstream logic (scope/role/ownerId) that are later trusted.
+- Unions and `Annotated`: craft shapes hitting unintended branches.
+</pydantic_edges>
+
+<graphql_and_alt_stacks>
+- If GraphQL (Strawberry/Graphene) is mounted, validate resolver-level authorization and IDOR on node/global IDs.
+- If SQLModel/SQLAlchemy present, probe for raw query usage and row-level authorization gaps.
+</graphql_and_alt_stacks>
+</special_contexts>
+
+<validation>
+1. Show unauthorized data access or action with side-by-side owner vs non-owner requests (or different tenants).
+2. Demonstrate cross-channel consistency (HTTP and WebSocket) for the same rule.
+3. Include proof where proxies/headers/caches alter outcomes (Host/XFF/CORS).
+4. Provide minimal payloads confirming template/SSRF execution or token misuse, with safe or OAST-based oracles.
+5. Document exact dependency paths (router-level, route-level) that missed enforcement.
+</validation>
+
+<pro_tips>
+1. Always fetch `/openapi.json` first; it’s the blueprint. If hidden, brute-force likely admin/report/export routes.
+2. Trace dependencies per route; map which ones enforce auth/scopes vs merely parse input.
+3. Treat tokens returned by `OAuth2PasswordBearer` as untrusted strings—verify actual signature and claims on the server.
+4. Test CORS with arbitrary Origins and with credentials; verify preflight and actual request deltas.
+5. Add Host and X-Forwarded-* fuzzing when behind proxies; watch for redirect/absolute URL differences.
+6. For uploads, vary filename encodings, dot segments, and NUL-like bytes; verify storage paths and served URLs.
+7. Use content-type toggling to hit alternate validators and code paths.
+8. For WebSockets, test cookie-based auth, origin restrictions, and per-message authorization.
+9. Mine client bundles/env for secret paths and preview/admin flags; many teams hide routes via UI only.
+10. Keep PoCs minimal and durable (IDs, headers, small payloads) and prefer reproducible diffs over noisy payloads.
+</pro_tips>
+
+<remember>Authorization and validation must be enforced in the dependency graph and at the resource boundary for every path and channel. If any route, middleware, or mount skips binding subject, action, and object/tenant, expect cross-user and cross-tenant breakage.</remember>
+</fastapi_security_testing_guide>

strix/prompts/frameworks/nextjs.jinja

@@ -0,0 +1,126 @@
+<nextjs_security_testing_guide>
+<title>NEXT.JS — ADVERSARIAL TESTING PLAYBOOK</title>
+
+<critical>Modern Next.js combines multiple execution contexts (Edge, Node, RSC, client) with smart caching (ISR/RSC fetch cache), middleware, and server actions. Authorization and cache boundaries must be enforced consistently across all paths or attackers will cross tenants, leak data, or invoke privileged actions.</critical>
+
+<surface_map>
+- Routers: App Router (`app/`) and Pages Router (`pages/`) coexist; test both
+- Runtimes: Node.js vs Edge (V8 isolates with restricted APIs)
+- Data paths: RSC (server components), Client components, Route Handlers (`app/api/**`), API routes (`pages/api/**`)
+- Middleware: `middleware.ts`/`_middleware.ts`
+- Rendering modes: SSR, SSG, ISR, on-demand revalidation, draft/preview mode
+- Images: `next/image` optimization and remote loader
+- Auth: NextAuth.js (callbacks, CSRF/state, callbackUrl), custom JWT/session bridges
+- Server Actions: streamed POST with `Next-Action` header and action IDs
+</surface_map>
+
+<methodology>
+1. Inventory routes (pages + app), static vs dynamic segments, and params. Map middleware coverage and runtime per path.
+2. Capture baseline for each role (unauth, user, admin) across SSR, API routes, Route Handlers, Server Actions, and streaming data.
+3. Diff responses while toggling runtime (Edge/Node), content-type, fetch cache directives, and preview/draft mode.
+4. Probe caching and revalidation boundaries (ISR, RSC fetch, CDN) for cross-user/tenant leaks.
+</methodology>
+
+<high_value_targets>
+- Middleware-protected routes (auth, geo, A/B)
+- Admin/staff paths, draft/preview content, on-demand revalidate endpoints
+- RSC payloads and flight data, streamed responses (server actions)
+- Image optimizer and custom loaders, remotePatterns/domains
+- NextAuth callbacks (`/api/auth/callback/*`), sign-in providers, CSRF/state handling
+- Edge-only features (bot protection, IP gates) and their Node equivalents
+</high_value_targets>
+
+<advanced_techniques>
+<middleware_bypass>
+- Test for CVE-class middleware bypass via `x-middleware-subrequest` crafting and `x-nextjs-data` probing. Look for 307 + `x-middleware-rewrite`/`x-nextjs-redirect` headers and attempt bypass on protected routes.
+- Attempt direct route access on Node vs Edge runtimes; confirm protection parity.
+</middleware_bypass>
+
+<server_actions>
+- Capture streamed POSTs containing `Next-Action` headers. Map hashed action IDs via source maps or specialized tooling to discover hidden actions.
+- Invoke actions out of UI flow and with alternate content-types; verify server-side authorization is enforced per action and not assumed from client state.
+- Try cross-tenant/object references within action payloads to expose BOLA/IDOR via server actions.
+</server_actions>
+
+<rsc_and_cache>
+- RSC fetch cache: probe `fetch` cache modes (force-cache, default, no-store) and revalidate tags/paths. Look for user-bound data cached without identity keys (ETag/Set-Cookie unaware).
+- Confirm that personalized data is rendered via `no-store` or properly keyed; attempt cross-user content via shared caches/CDN.
+- Inspect Flight data streams for serialized sensitive fields leaking through props.
+</rsc_and_cache>
+
+<isr_and_revalidation>
+- Identify ISR pages (stale-while-revalidate). Check if responses may include user-bound fragments or tenant-dependent content.
+- On-demand revalidation endpoints: look for weak secrets in URLs, referer-disclosed tokens, or unvalidated hosts triggering `revalidatePath`/`revalidateTag`.
+- Attempt header-smuggling or method variations to trigger revalidation flows.
+</isr_and_revalidation>
+
+<draft_preview_mode>
+- Draft/preview mode toggles via secret URLs/cookies; search for preview enable endpoints and secrets in client bundles/env leaks.
+- Try setting preview cookies from subdomains, alternate paths, or through open redirects; observe content differences and persistence.
+</draft_preview_mode>
+
+<next_image_ssrf>
+- Review `images.domains`/`remotePatterns` in `next.config.js`; test SSRF to internal hosts (IPv4/IPv6 variants, DNS rebinding) if patterns are broad.
+- Custom loader functions may fetch with arbitrary URLs; test protocol smuggling and redirection chains.
+- Attempt cache poisoning: craft same URL with different normalization to affect other users.
+</next_image_ssrf>
+
+<nextauth_pitfalls>
+- State/nonce/PKCE: validate per-provider correctness; attempt missing/relaxed checks leading to login CSRF or token mix-up.
+- Callback URL restrictions: open redirect in `callbackUrl` or mis-scoped allowed hosts; hijack sessions by forcing callbacks.
+- JWT/session bridges: audience/issuer not enforced across API routes/Route Handlers; attempt cross-service token reuse.
+</nextauth_pitfalls>
+
+<edge_runtime_diffs>
+- Edge runtime lacks certain Node APIs; defenses relying on Node-only modules may be skipped. Compare behavior of the same route in Edge vs Node.
+- Header trust and IP determination can differ at the edge; test auth decisions tied to `x-forwarded-*` variance.
+</edge_runtime_diffs>
+
+<client_and_dom>
+- Identify `dangerouslySetInnerHTML`, Markdown renderers, and user-controlled href/src attributes. Validate CSP/Trusted Types coverage for SSR/CSR/hydration.
+- Attack hydration boundaries: server vs client render mismatches can enable gadget-based XSS.
+</client_and_dom>
+</advanced_techniques>
+
+<bypass_techniques>
+- Content-type switching: `application/json` ↔ `multipart/form-data` ↔ `application/x-www-form-urlencoded` to traverse alternate code paths.
+- Method override/tunneling: `_method`, `X-HTTP-Method-Override`, GET on endpoints unexpectedly accepting writes.
+- Case/param aliasing and query duplication affecting middleware vs handler parsing.
+- Cache key confusion at CDN/proxy (lack of Vary on auth cookies/headers) to leak personalized SSR/ISR content.
+</bypass_techniques>
+
+<special_contexts>
+<uploads_and_files>
+- API routes and Route Handlers handling file uploads: check MIME sniffing, Content-Disposition, stored path traversal, and public serving of user files.
+- Validate signing/scoping of any generated file URLs (short TTL, audience-bound).
+</uploads_and_files>
+
+<integrations_and_webhooks>
+- Webhooks that trigger revalidation/imports: require HMAC verification; test with replay and cross-tenant object IDs.
+- Analytics/AB testing flags controlled via cookies/headers; ensure they do not unlock privileged server paths.
+</integrations_and_webhooks>
+</special_contexts>
+
+<validation>
+1. Provide side-by-side requests for different principals showing cross-user/tenant content or actions.
+2. Prove cache boundary failure (RSC/ISR/CDN) with response diffs or ETag collisions.
+3. Demonstrate server action invocation outside UI with insufficient authorization checks.
+4. Show middleware bypass (where applicable) with explicit headers and resulting protected content.
+5. Include runtime parity checks (Edge vs Node) proving inconsistent enforcement.
+</validation>
+
+<pro_tips>
+1. Enumerate with both App and Pages routers: many apps ship a hybrid surface.
+2. Treat caching as an identity boundary—test with cookies stripped, altered, and with Vary/ETag diffs.
+3. Decode client bundles for preview/revalidate secrets, action IDs, and hidden routes.
+4. Use streaming-aware tooling to capture server actions and RSC payloads; diff flight data.
+5. For NextAuth, fuzz provider params (state, nonce, scope, callbackUrl) and verify strictness.
+6. Always retest under Edge and Node; misconfigurations often exist in only one runtime.
+7. Probe `next/image` aggressively but safely—test IPv6/obscure encodings and redirect behavior.
+8. Validate negative paths: other-user IDs, other-tenant headers/subdomains, lower roles.
+9. Focus on export/report/download endpoints; they often bypass resolver-level checks.
+10. Document minimal, reproducible PoCs; avoid noisy payloads—prefer precise diffs.
+</pro_tips>
+
+<remember>Next.js security breaks where identity, authorization, and caching diverge across routers, runtimes, and data paths. Bind subject, action, and object on every path, and key caches to identity and tenant explicitly.</remember>
+</nextjs_security_testing_guide>