Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.
Python agentsai-hackingai-penetration-testingai-pentestingai-securityartificial-intelligencebug-bountycode-qualityctf-toolscybersecuritycybersecurity-toolsethical-hackinghackingllm-securityoffensive-securitypenetration-testingpentesting-toolsred-teamingsecuritysecurity-automation
feat(migration): phase 5b — STRIX_USE_SDK_HARNESS dispatch flag
0xallam4e0d0f35d92c
diff --git a/pyproject.toml b/pyproject.tomlindex f31a8cbf..e9cfa3d0 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -312,6 +312,10 @@ ignore = [# walks every supported target type — splitting it into per-type# helpers would add indirection without simplifying anything."strix/sdk_entry.py" = ["TC003", "PLR0912"]+# Legacy interface utility with intentionally many branches per supported+# scope-mode / target-type combination; refactor would obscure the+# decision tree without simplifying it.+"strix/interface/utils.py" = ["PLR0912"]# Sandbox dispatch helper has many short-circuit error returns (auth fail,# size cap, decode fail, etc). Each is a distinct, documented failure mode# the model needs to see verbatim — collapsing them harms readability.diff --git a/strix/interface/cli.py b/strix/interface/cli.pyindex ec853b3b..6004abef 100644--- a/strix/interface/cli.py+++ b/strix/interface/cli.py@@ -11,7 +11,9 @@ from rich.panel import Panelfrom rich.text import Textfrom strix.agents.StrixAgent import StrixAgent+from strix.interface.sdk_dispatch import run_scan_via_sdk, should_use_sdk_harnessfrom strix.llm.config import LLMConfig+from strix.runtime import cleanup_runtimefrom strix.telemetry.tracer import Tracer, set_global_tracerfrom .utils import (@@ -109,8 +111,6 @@ async def run_cli(args: Any) -> None: # noqa: PLR0915tracer.vulnerability_found_callback = display_vulnerabilitydef cleanup_on_exit() -> None:- from strix.runtime import cleanup_runtime-tracer.cleanup()cleanup_runtime()@@ -163,18 +163,29 @@ async def run_cli(args: Any) -> None: # noqa: PLR0915update_thread.start()try:- agent = StrixAgent(agent_config)- result = await agent.execute_scan(scan_config)-- if isinstance(result, dict) and not result.get("success", True):- error_msg = result.get("error", "Unknown error")- error_details = result.get("details")- console.print()- console.print(f"[bold red]Penetration test failed:[/] {error_msg}")- if error_details:- console.print(f"[dim]{error_details}[/]")- console.print()- sys.exit(1)+ if should_use_sdk_harness():+ # SDK harness opt-in (PLAYBOOK §7.1). Returns a+ # RunResult, not the legacy success-dict shape, so+ # we skip the legacy error-extraction block —+ # failures inside run_strix_scan raise instead.+ await run_scan_via_sdk(+ scan_config=scan_config,+ args=args,+ tracer=tracer,+ )+ else:+ agent = StrixAgent(agent_config)+ result = await agent.execute_scan(scan_config)++ if isinstance(result, dict) and not result.get("success", True):+ error_msg = result.get("error", "Unknown error")+ error_details = result.get("details")+ console.print()+ console.print(f"[bold red]Penetration test failed:[/] {error_msg}")+ if error_details:+ console.print(f"[dim]{error_details}[/]")+ console.print()+ sys.exit(1)finally:stop_updates.set()update_thread.join(timeout=1)diff --git a/strix/interface/main.py b/strix/interface/main.pyindex bc88da67..a2323aaa 100644--- a/strix/interface/main.py+++ b/strix/interface/main.py@@ -453,7 +453,7 @@ def display_completion_message(args: argparse.Namespace, results_path: Path) ->stats_text = build_final_stats_text(tracer)- panel_parts = [completion_text, "\n\n", target_text]+ panel_parts: list[Text | str] = [completion_text, "\n\n", target_text]if stats_text.plain:panel_parts.extend(["\n", stats_text])diff --git a/strix/interface/sdk_dispatch.py b/strix/interface/sdk_dispatch.pynew file mode 100644index 00000000..3cbaf344--- /dev/null+++ b/strix/interface/sdk_dispatch.py@@ -0,0 +1,143 @@+"""STRIX_USE_SDK_HARNESS dispatch — selects legacy vs SDK harness at run-time.++Phase 5b cutover gate. The legacy CLI (``strix.interface.cli``) calls+``StrixAgent(...).execute_scan(scan_config)`` directly. To roll out the+SDK migration safely we want a single env-var-gated branch:++ STRIX_USE_SDK_HARNESS=1 → await run_strix_scan(...)+ STRIX_USE_SDK_HARNESS=0 → await StrixAgent(...).execute_scan(...)++This module is a thin adapter: it reads the env var, and when the SDK+path is active, translates the legacy ``scan_config`` + ``args`` pair+into the keyword arguments :func:`run_strix_scan` expects.++Per PLAYBOOK §7.1: the legacy default stays in place until end-to-end+validation against a stable target succeeds; the env flag is the+opt-in. Removal of the legacy branch happens one release after cutover.++References:+ - PLAYBOOK.md §7.1 (cutover strategy)+ - PLAYBOOK.md §7.2 (rollback procedure)+"""++from __future__ import annotations++import logging+import os+from pathlib import Path+from typing import TYPE_CHECKING, Any+++if TYPE_CHECKING:+ from agents.result import RunResult+++logger = logging.getLogger(__name__)+++_ENV_FLAG = "STRIX_USE_SDK_HARNESS"+++def should_use_sdk_harness() -> bool:+ """Return True iff ``STRIX_USE_SDK_HARNESS`` is truthy in the env.++ Truthy values: ``"1"``, ``"true"``, ``"yes"`` (case-insensitive).+ Anything else — including unset — returns False so the default+ deployed posture stays the legacy harness.+ """+ raw = os.environ.get(_ENV_FLAG, "")+ return raw.strip().lower() in {"1", "true", "yes"}+++def _resolve_sandbox_image() -> str:+ """Read the sandbox image tag from Strix config.++ Falls back to ``"strix-sandbox:latest"`` if unset — same behavior+ the legacy ``DockerRuntime`` would surface as a config error.+ """+ from strix.config import Config++ image = Config.get("strix_image")+ if not image:+ logger.warning(+ "strix_image not configured; falling back to strix-sandbox:latest. "+ "Set this in ~/.strix/cli-config.json for production use.",+ )+ return "strix-sandbox:latest"+ return str(image)+++def _resolve_sources_path(args: Any) -> Path:+ """Pick the host directory to mount into ``/workspace/sources``.++ - When ``--local-sources`` was passed, use the parent of the first+ source's ``host_path`` (the legacy harness then copies each+ individual source under ``/workspace/<subdir>``; we mount the+ parent and let the agent walk down).+ - Otherwise, use a per-run scratch directory under+ ``$XDG_CACHE_HOME/strix`` (or ``~/.cache/strix``) — the legacy+ flow eventually populates ``/workspace`` via post-create copies,+ which the SDK session manager doesn't replicate yet (Phase 6+ will bring that in).+ """+ local_sources: list[dict[str, str]] | None = getattr(args, "local_sources", None)+ if local_sources:+ first = local_sources[0]+ host_path = first.get("host_path") or first.get("source_path") or first.get("path")+ if host_path:+ return Path(host_path).expanduser().resolve().parent++ cache_root = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")+ run_name = getattr(args, "run_name", "default") or "default"+ sources = Path(cache_root) / "strix" / "sources" / str(run_name)+ sources.mkdir(parents=True, exist_ok=True)+ return sources+++async def run_scan_via_sdk(+ *,+ scan_config: dict[str, Any],+ args: Any,+ tracer: Any,+) -> RunResult:+ """Translate legacy CLI args into ``run_strix_scan`` kwargs.++ Args:+ scan_config: The same dict the legacy ``StrixAgent.execute_scan``+ accepts. Forwarded verbatim to ``run_strix_scan``; the+ entry point reads ``targets``, ``user_instructions``,+ ``diff_scope``, ``scan_mode``, ``is_whitebox``, ``skills``+ from it.+ args: argparse Namespace from ``strix.interface.cli``. We read+ ``run_name``, ``local_sources``, ``scan_mode`` from it.+ tracer: Live ``Tracer`` instance — flows through context so+ tools (``create_vulnerability_report``, ``finish_scan``)+ persist into the same on-disk run directory the legacy+ path uses.++ Returns the SDK ``RunResult``. Raises whatever ``run_strix_scan``+ raises (sandbox bring-up failure, LLM error, etc.).+ """+ from strix.sdk_entry import run_strix_scan++ run_name = getattr(args, "run_name", None) or scan_config.get("run_name")+ image = _resolve_sandbox_image()+ sources_path = _resolve_sources_path(args)+ interactive = bool(getattr(args, "interactive", False))++ logger.info(+ "STRIX_USE_SDK_HARNESS active; dispatching scan %s via run_strix_scan "+ "(image=%s, sources=%s)",+ run_name,+ image,+ sources_path,+ )++ return await run_strix_scan(+ scan_config=scan_config,+ scan_id=run_name,+ image=image,+ sources_path=sources_path,+ tracer=tracer,+ interactive=interactive,+ )diff --git a/strix/interface/utils.py b/strix/interface/utils.pyindex 3559fa9b..aff33a01 100644--- a/strix/interface/utils.py+++ b/strix/interface/utils.py@@ -55,7 +55,7 @@ def get_cvss_color(cvss_score: float) -> str:return "#6b7280"-def format_vulnerability_report(report: dict[str, Any]) -> Text: # noqa: PLR0912, PLR0915+def format_vulnerability_report(report: dict[str, Any]) -> Text: # noqa: PLR0915"""Format a vulnerability report for CLI display with all rich fields."""field_style = "bold #4ade80"@@ -823,7 +823,7 @@ def _truncate_file_list(return files[:max_files], True-def build_diff_scope_instruction(scopes: list[RepoDiffScope]) -> str: # noqa: PLR0912+def build_diff_scope_instruction(scopes: list[RepoDiffScope]) -> str:lines = ["The user is requesting a review of a Pull Request.","Instruction: Direct your analysis primarily at the changes in the listed files. "@@ -1049,7 +1049,7 @@ def resolve_diff_scope_context()instruction_block = build_diff_scope_instruction(repo_scopes)- metadata: dict[str, Any] = {+ metadata = {"active": True,"mode": scope_mode,"repos": [scope.to_metadata() for scope in repo_scopes],@@ -1082,7 +1082,7 @@ def _is_http_git_repo(url: str) -> bool:return False-def infer_target_type(target: str) -> tuple[str, dict[str, str]]: # noqa: PLR0911, PLR0912+def infer_target_type(target: str) -> tuple[str, dict[str, str]]: # noqa: PLR0911if not target or not isinstance(target, str):raise ValueError("Target must be a non-empty string")@@ -1248,7 +1248,7 @@ def _is_localhost_host(host: str) -> bool:def rewrite_localhost_targets(targets_info: list[dict[str, Any]], host_gateway: str) -> None:- from yarl import URL # type: ignore[import-not-found]+ from yarl import URLfor target_info in targets_info:target_type = target_info.get("type")diff --git a/tests/interface/test_sdk_dispatch.py b/tests/interface/test_sdk_dispatch.pynew file mode 100644index 00000000..55912022--- /dev/null+++ b/tests/interface/test_sdk_dispatch.py@@ -0,0 +1,199 @@+"""Phase 5b tests for the STRIX_USE_SDK_HARNESS dispatch.++Covers the env-flag reader, source-path resolution, sandbox image+lookup, and the adapter that translates legacy CLI args into+``run_strix_scan`` kwargs.++We never call ``run_strix_scan`` for real — that requires a live+Docker daemon + LLM. The tests patch it and verify the kwargs handoff.+"""++from __future__ import annotations++import logging+from pathlib import Path+from types import SimpleNamespace+from typing import Any+from unittest.mock import AsyncMock, MagicMock, patch++import pytest++from strix.interface.sdk_dispatch import (+ _resolve_sandbox_image,+ _resolve_sources_path,+ run_scan_via_sdk,+ should_use_sdk_harness,+)+++# --- env flag reader ----------------------------------------------------+++ ("value", "expected"),+ [+ ("1", True),+ ("true", True),+ ("True", True),+ ("YES", True),+ ("0", False),+ ("false", False),+ ("no", False),+ ("", False),+ ("anything-else", False),+ ],+)+def test_should_use_sdk_harness_parses_env(+ monkeypatch: pytest.MonkeyPatch,+ value: str,+ expected: bool,+) -> None:+ monkeypatch.setenv("STRIX_USE_SDK_HARNESS", value)+ assert should_use_sdk_harness() is expected+++def test_should_use_sdk_harness_defaults_false_when_unset(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.delenv("STRIX_USE_SDK_HARNESS", raising=False)+ assert should_use_sdk_harness() is False+++# --- image lookup -------------------------------------------------------+++def test_resolve_sandbox_image_uses_config_value() -> None:+ with patch(+ "strix.config.Config.get",+ return_value="strix-sandbox:0.1.13",+ ):+ assert _resolve_sandbox_image() == "strix-sandbox:0.1.13"+++def test_resolve_sandbox_image_falls_back_when_unset(+ caplog: pytest.LogCaptureFixture,+) -> None:+ with (+ patch("strix.config.Config.get", return_value=None),+ caplog.at_level(logging.WARNING, logger="strix.interface.sdk_dispatch"),+ ):+ out = _resolve_sandbox_image()+ assert out == "strix-sandbox:latest"+ assert any("strix_image not configured" in r.message for r in caplog.records)+++# --- sources path -------------------------------------------------------+++def test_resolve_sources_path_uses_local_sources_parent(tmp_path: Path) -> None:+ """When --local-sources is given, mount that path's parent so the+ agent can walk down into the actual source directory tree."""+ src_dir = tmp_path / "my-project"+ src_dir.mkdir()+ args = SimpleNamespace(+ local_sources=[{"host_path": str(src_dir)}],+ run_name="run-1",+ )+ assert _resolve_sources_path(args) == tmp_path+++def test_resolve_sources_path_handles_alternative_keys(tmp_path: Path) -> None:+ """Some legacy paths use 'source_path' or 'path' instead of+ 'host_path' — we accept all three."""+ src_dir = tmp_path / "alt"+ src_dir.mkdir()+ args = SimpleNamespace(+ local_sources=[{"path": str(src_dir)}],+ run_name="run-2",+ )+ assert _resolve_sources_path(args) == tmp_path+++def test_resolve_sources_path_creates_scratch_dir_when_absent(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))+ args = SimpleNamespace(local_sources=None, run_name="scan-x")+ out = _resolve_sources_path(args)+ assert out == tmp_path / "strix" / "sources" / "scan-x"+ assert out.exists()+ assert out.is_dir()+++# --- adapter -----------------------------------------------------------+++async def test_run_scan_via_sdk_translates_args_to_kwargs(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Verify every kwarg the entry point reads is forwarded correctly."""+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))++ scan_config = {"targets": [], "scan_mode": "deep"}+ args = SimpleNamespace(+ run_name="scan-42",+ local_sources=None,+ interactive=True,+ )+ fake_tracer = MagicMock(name="tracer")++ fake_run = AsyncMock(return_value=MagicMock(name="run_result"))+ with (+ patch("strix.config.Config.get", return_value="strix-sandbox:test"),+ patch("strix.sdk_entry.run_strix_scan", new=fake_run),+ ):+ await run_scan_via_sdk(scan_config=scan_config, args=args, tracer=fake_tracer)++ fake_run.assert_awaited_once()+ assert fake_run.await_args is not None+ kwargs = fake_run.await_args.kwargs+ assert kwargs["scan_config"] is scan_config+ assert kwargs["scan_id"] == "scan-42"+ assert kwargs["image"] == "strix-sandbox:test"+ assert kwargs["sources_path"] == tmp_path / "strix" / "sources" / "scan-42"+ assert kwargs["tracer"] is fake_tracer+ assert kwargs["interactive"] is True+++async def test_run_scan_via_sdk_falls_back_to_scan_config_run_name(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """If args has no run_name, scan_config['run_name'] should be used."""+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))+ scan_config = {"targets": [], "run_name": "from-config"}+ args = SimpleNamespace(local_sources=None)++ fake_run = AsyncMock(return_value=MagicMock())+ with (+ patch("strix.config.Config.get", return_value="img:1"),+ patch("strix.sdk_entry.run_strix_scan", new=fake_run),+ ):+ await run_scan_via_sdk(scan_config=scan_config, args=args, tracer=None)++ assert fake_run.await_args is not None+ assert fake_run.await_args.kwargs["scan_id"] == "from-config"+++async def test_run_scan_via_sdk_propagates_run_failure(+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A failure inside run_strix_scan should bubble up to the caller —+ the legacy CLI relies on raised exceptions for the SDK path."""+ monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))+ scan_config: dict[str, Any] = {"targets": []}+ args = SimpleNamespace(run_name="r", local_sources=None)++ fake_run = AsyncMock(side_effect=RuntimeError("boom"))+ with (+ patch("strix.config.Config.get", return_value="img"),+ patch("strix.sdk_entry.run_strix_scan", new=fake_run),+ pytest.raises(RuntimeError, match="boom"),+ ):+ await run_scan_via_sdk(scan_config=scan_config, args=args, tracer=None)