feat: support API specs and Postman collections as targets (#866)

strix/interface/cli_args.py

@@ -65,6 +65,14 @@ Examples:
   # Local code analysis
   strix --target ./my-project
 
+  # API spec test (OpenAPI/Swagger file or Postman collection export)
+  strix --target ./openapi.yaml --target https://api.example.com
+  strix --target ./collection.postman_collection.json
+
+  # Postman collection pulled live by id (needs POSTMAN_API_KEY); optional environment
+  strix --target postman://<collection-uuid> --target https://api.example.com
+  strix --target "postman://<collection-uuid>?env=<environment-uuid>"
+
   # Domain penetration test
   strix --target example.com
 
@@ -107,8 +115,10 @@ Examples:
         "--target",
         type=str,
         action="append",
-        help="Target to test (URL, repository, local directory path, domain name, or IP address). "
-        "Local directories are mounted into the sandbox writable. "
+        help="Target to test: URL, repository, local directory path, domain name, IP address, "
+        "an API spec file (OpenAPI/Swagger .json/.yaml or a Postman collection export), or a "
+        "Postman collection by id (postman://<collection-uuid>[?env=<environment-uuid>], needs "
+        "POSTMAN_API_KEY). Local directories are mounted into the sandbox writable. "
         "Can be specified multiple times for multi-target scans. "
         "Fresh runs require --target or --target-list.",
     )

strix/interface/scan_setup.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import asyncio
 import logging
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from strix.config import Settings, codex, load_settings
 from strix.core.paths import run_dir_for
@@ -28,8 +28,18 @@ from strix.interface.utils import (
     read_target_list_file,
     resolve_diff_scope_context,
     rewrite_localhost_targets,
+    stage_api_specs,
+    write_fetched_collection,
 )
 from strix.telemetry import posthog, scarf
+from strix.utils.api_spec import (
+    SpecParseError,
+    fetch_postman_collection,
+    fetch_postman_environment,
+    load_spec,
+    spec_base_urls,
+    spec_title,
+)
 
 
 if TYPE_CHECKING:
@@ -109,6 +119,9 @@ def build_targets_info(args: argparse.Namespace) -> None:
         else:
             display_target = target
 
+        if target_type == "api_spec":
+            _resolve_api_spec(target, target_dict)
+
         args.targets_info.append(
             {"type": target_type, "details": target_dict, "original": display_target}
         )
@@ -119,6 +132,34 @@ def build_targets_info(args: argparse.Namespace) -> None:
     rewrite_localhost_targets(args.targets_info, HOST_GATEWAY_HOSTNAME)
 
 
+def _resolve_api_spec(target: str, details: dict[str, Any]) -> None:
+    """Read the spec up front so bad input fails before the run starts.
+
+    Records the declared base URLs (the only thing scope authorization can take
+    from a spec) and, for a ``postman://`` target, downloads the collection to a
+    local file so the sandbox never needs the Postman API key.
+    """
+    try:
+        if details.get("source") == "postman_api":
+            collection_uid = str(details["collection_uid"])
+            api_key = load_settings().integrations.postman_api_key or ""
+            raw = fetch_postman_collection(collection_uid, api_key)
+            environment_uid = str(details.get("environment_uid") or "")
+            extra_variables = (
+                fetch_postman_environment(environment_uid, api_key) if environment_uid else None
+            )
+            details["target_spec"] = write_fetched_collection(raw, collection_uid)
+        else:
+            raw = load_spec(str(details["target_spec"]))
+            extra_variables = None
+        base_urls = spec_base_urls(raw, extra_variables=extra_variables)
+    except SpecParseError as exc:
+        raise ValueError(f"Invalid API spec '{target}': {exc}") from None
+
+    details["spec_title"] = spec_title(raw)
+    details["base_urls"] = base_urls
+
+
 def prepare_run(args: argparse.Namespace) -> None:
     """Resolve the run name, clone repos, compute diff-scope, and persist state.
 
@@ -139,6 +180,7 @@ def prepare_run(args: argparse.Namespace) -> None:
             target_info["details"]["cloned_repo_path"] = cloned_path
 
     args.local_sources = collect_local_sources(args.targets_info)
+    args.local_sources.extend(stage_api_specs(args.targets_info, args.run_name))
     diff_scope = resolve_diff_scope_context(
         local_sources=args.local_sources,
         scope_mode=args.scope_mode,

strix/interface/utils.py

@@ -11,7 +11,7 @@ import tempfile
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
-from urllib.parse import urlparse
+from urllib.parse import parse_qs, urlparse
 
 import docker
 import requests
@@ -21,6 +21,7 @@ from rich.panel import Panel
 from rich.text import Text
 
 from strix.config import load_settings
+from strix.utils.api_spec import detect_spec_format
 
 
 logger = logging.getLogger(__name__)
@@ -484,6 +485,15 @@ def _derive_target_label_for_run_name(targets_info: list[dict[str, Any]] | None)
     if target_type == "ip_address":
         return str(details.get("target_ip", original) or original)
 
+    if target_type == "api_spec":
+        if details.get("source") == "postman_api":
+            return "postman-collection"
+        spec_path = details.get("target_spec", original)
+        try:
+            return str(Path(spec_path).stem or spec_path)
+        except Exception:
+            return str(spec_path)
+
     return str(original or "pentest")
 
 
@@ -1113,6 +1123,24 @@ def infer_target_type(target: str) -> tuple[str, dict[str, str]]:  # noqa: PLR09
         return "repository", {"target_repo": target}
 
     parsed = urlparse(target)
+    if parsed.scheme == "postman":
+        collection_uid = f"{parsed.netloc}{parsed.path}".strip("/")
+        if not collection_uid:
+            raise ValueError(
+                f"Missing Postman collection id in '{target}' (expected postman://<collection-uid>)"
+            )
+        details = {
+            "target_spec": target,
+            "spec_format": "postman",
+            "source": "postman_api",
+            "collection_uid": collection_uid,
+        }
+        query = parse_qs(parsed.query)
+        env_uid = (query.get("env") or query.get("environment") or [""])[0].strip()
+        if env_uid:
+            details["environment_uid"] = env_uid
+        return "api_spec", details
+
     if parsed.scheme in ("http", "https"):
         if parsed.username or parsed.password:
             return "repository", {"target_repo": target}
@@ -1138,6 +1166,12 @@ def infer_target_type(target: str) -> tuple[str, dict[str, str]]:  # noqa: PLR09
             if path.is_dir():
                 check_mountable_dir(path)
                 return "local_code", {"target_path": str(path.resolve())}
+            spec_format = detect_spec_format(path)
+            if spec_format is not None:
+                return "api_spec", {
+                    "target_spec": str(path.resolve()),
+                    "spec_format": spec_format,
+                }
             raise ValueError(f"Path exists but is not a directory: {target}")
     except (OSError, RuntimeError) as e:
         raise ValueError(f"Invalid path: {target} - {e!s}") from e
@@ -1164,6 +1198,9 @@ def infer_target_type(target: str) -> tuple[str, dict[str, str]]:  # noqa: PLR09
         "- A valid URL (http:// or https://)\n"
         "- A Git repository URL (https://host/org/repo or git@host:org/repo.git)\n"
         "- A local directory path\n"
+        "- An API spec file (OpenAPI/Swagger .json/.yaml or a Postman collection)\n"
+        "- A Postman collection by id (postman://<collection-uid>[?env=<environment-uid>], "
+        "needs POSTMAN_API_KEY)\n"
         "- A domain name (e.g., example.com)\n"
         "- An IP address (e.g., 192.168.1.10)"
     )
@@ -1438,6 +1475,62 @@ def rewrite_localhost_targets(targets_info: list[dict[str, Any]], host_gateway:
                 details["target_ip"] = host_gateway
 
 
+#: API spec targets are copied into one workspace directory rather than mounted
+#: from wherever they happen to live on the host.
+API_SPEC_WORKSPACE_SUBDIR = "api-specs"
+
+
+def write_fetched_collection(collection: dict[str, Any], collection_uid: str) -> str:
+    """Write a collection fetched from the Postman API to a local file.
+
+    Returns the file path, so a ``postman://`` target continues as an ordinary
+    spec file from here on and the API key never leaves the host.
+    """
+    staging = Path(tempfile.gettempdir()) / "strix_api_specs" / "fetched"
+    staging.mkdir(parents=True, exist_ok=True)
+    path = staging / f"{sanitize_name(collection_uid)}.postman_collection.json"
+    path.write_text(json.dumps(collection, indent=2), encoding="utf-8")
+    return str(path)
+
+
+def stage_api_specs(targets_info: list[dict[str, Any]], run_name: str) -> list[dict[str, Any]]:
+    """Copy every ``api_spec`` target into one directory for the sandbox.
+
+    A spec is a single file the agent reads, not a tree it works in, so it is
+    copied to a per-run staging directory that is exposed at
+    ``/workspace/api-specs`` instead of mounting its host location. Each target's
+    ``workspace_path`` records where the agent will find it.
+    """
+    specs = [t for t in targets_info if t.get("type") == "api_spec"]
+    if not specs:
+        return []
+
+    staging = Path(tempfile.gettempdir()) / "strix_api_specs" / run_name
+    staging.mkdir(parents=True, exist_ok=True)
+
+    used: set[str] = set()
+    for target in specs:
+        details = target["details"]
+        source = Path(str(details["target_spec"]))
+        name = source.name
+        stem, suffix = source.stem, source.suffix
+        count = 1
+        while name in used:
+            count += 1
+            name = f"{stem}-{count}{suffix}"
+        used.add(name)
+        shutil.copy2(source, staging / name)
+        details["workspace_path"] = f"/workspace/{API_SPEC_WORKSPACE_SUBDIR}/{name}"
+
+    return [
+        {
+            "source_path": str(staging),
+            "workspace_subdir": API_SPEC_WORKSPACE_SUBDIR,
+            "protect_metadata": False,
+        }
+    ]
+
+
 def clone_repository(repo_url: str, run_name: str, dest_name: str | None = None) -> str:
     console = Console()