shadowcat 2.0.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,17 @@
+"""ShadowCat - AI-Powered Penetration Testing Assistant."""
+
+__version__ = "1.0.0"
+__author__ = "Your Name"
+__license__ = "MIT"
+
+from agent.core.agent import run_pentest
+from agent.core.config import ShadowCatConfig, load_config
+from agent.core.tracer import Tracer, get_global_tracer
+
+__all__ = [
+    "ShadowCatConfig",
+    "Tracer",
+    "get_global_tracer",
+    "load_config",
+    "run_pentest",
+]

agent/benchmark/__init__.py

@@ -0,0 +1,11 @@
+"""Simple benchmark manager for ShadowCat.
+
+Start/stop benchmark containers and expose ports for manual testing.
+"""
+
+from agent.benchmark.registry import BenchmarkInfo, BenchmarkRegistry
+
+__all__ = [
+    "BenchmarkInfo",
+    "BenchmarkRegistry",
+]

agent/benchmark/cli.py

@@ -0,0 +1,179 @@
+"""Simple CLI for benchmark management.
+
+Usage:
+    shadowcat_agent-benchmark list [--tags TAG ...] [--levels N ...]
+    shadowcat_agent-benchmark start BENCHMARK_ID
+    shadowcat_agent-benchmark stop BENCHMARK_ID
+    shadowcat_agent-benchmark status
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from agent.benchmark.config import DEFAULT_BENCHMARKS_DIR
+from agent.benchmark.docker import (
+    get_running_benchmarks,
+    start_benchmark,
+    stop_benchmark,
+)
+from agent.benchmark.registry import BenchmarkRegistry
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List available benchmarks."""
+    benchmarks_dir = Path(args.benchmarks_dir) if args.benchmarks_dir else DEFAULT_BENCHMARKS_DIR
+
+    try:
+        registry = BenchmarkRegistry(benchmarks_dir)
+        registry.load()
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        return 1
+
+    # Show tags if requested
+    if args.show_tags:
+        print("Available tags:")
+        for tag in sorted(registry.get_all_tags()):
+            count = len(registry.filter(tags=[tag]))
+            print(f"  {tag}: {count} benchmarks")
+        return 0
+
+    # Filter and list
+    benchmarks = registry.filter(tags=args.tags, levels=args.levels)
+
+    print(f"{'ID':<15} {'Level':^5} {'Name':<40} {'Tags'}")
+    print("-" * 80)
+    for b in benchmarks:
+        tags_str = ", ".join(b.tags[:3])
+        if len(b.tags) > 3:
+            tags_str += "..."
+        print(f"{b.id:<15} {b.level:^5} {b.name[:40]:<40} {tags_str}")
+
+    print(f"\nTotal: {len(benchmarks)} benchmarks")
+    return 0
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """Start a benchmark."""
+    benchmarks_dir = Path(args.benchmarks_dir) if args.benchmarks_dir else DEFAULT_BENCHMARKS_DIR
+
+    registry = BenchmarkRegistry(benchmarks_dir)
+    benchmark = registry.get(args.benchmark_id)
+
+    if not benchmark:
+        print(f"Error: Benchmark '{args.benchmark_id}' not found")
+        return 1
+
+    print(f"Starting benchmark: {benchmark.name}")
+    print(f"Description: {benchmark.description}")
+    print(f"Level: {benchmark.level}, Tags: {', '.join(benchmark.tags)}")
+    print()
+
+    result = start_benchmark(benchmark.path)
+
+    if result["success"]:
+        target_url = result["target_url"]
+        # Extract port from URL for Docker target
+        port = target_url.split(":")[-1]
+        docker_url = f"http://host.docker.internal:{port}"
+
+        print("\nBenchmark started successfully!")
+        print(f"Target URL: {target_url}")
+        print()
+        print("Run ShadowCat against this target:")
+        print(f"  Local:  shadowcat_agent --target {target_url}")
+        print(f"  Docker: shadowcat_agent --target {docker_url}")
+    else:
+        print(f"\nFailed to start benchmark: {result['message']}")
+        return 1
+
+    return 0
+
+
+def cmd_stop(args: argparse.Namespace) -> int:
+    """Stop a benchmark."""
+    benchmarks_dir = Path(args.benchmarks_dir) if args.benchmarks_dir else DEFAULT_BENCHMARKS_DIR
+
+    registry = BenchmarkRegistry(benchmarks_dir)
+    benchmark = registry.get(args.benchmark_id)
+
+    if not benchmark:
+        print(f"Error: Benchmark '{args.benchmark_id}' not found")
+        return 1
+
+    result = stop_benchmark(benchmark.path)
+
+    if result["success"]:
+        print("Benchmark stopped successfully")
+    else:
+        print(f"Failed to stop benchmark: {result['message']}")
+        return 1
+
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Show running benchmarks."""
+    running = get_running_benchmarks()
+
+    if not running:
+        print("No benchmark containers currently running")
+        return 0
+
+    print("Running benchmark containers:")
+    print(f"{'Name':<40} {'Ports':<30} {'Status'}")
+    print("-" * 80)
+    for container in running:
+        print(f"{container['name']:<40} {container['ports']:<30} {container['status']}")
+
+    return 0
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        prog="shadowcat_agent-benchmark",
+        description="Manage benchmark containers for ShadowCat testing",
+    )
+    parser.add_argument(
+        "--benchmarks-dir",
+        "-d",
+        help="Path to benchmarks directory",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # List command
+    list_parser = subparsers.add_parser("list", help="List available benchmarks")
+    list_parser.add_argument("--tags", "-t", nargs="+", help="Filter by tags")
+    list_parser.add_argument(
+        "--levels", "-l", nargs="+", type=int, help="Filter by levels (1, 2, 3)"
+    )
+    list_parser.add_argument("--show-tags", action="store_true", help="Show all tags")
+
+    # Start command
+    start_parser = subparsers.add_parser("start", help="Start a benchmark")
+    start_parser.add_argument("benchmark_id", help="Benchmark ID (e.g., XBEN-001-24)")
+
+    # Stop command
+    stop_parser = subparsers.add_parser("stop", help="Stop a benchmark")
+    stop_parser.add_argument("benchmark_id", help="Benchmark ID")
+
+    # Status command
+    subparsers.add_parser("status", help="Show running benchmarks")
+
+    args = parser.parse_args()
+
+    if args.command == "list":
+        sys.exit(cmd_list(args))
+    elif args.command == "start":
+        sys.exit(cmd_start(args))
+    elif args.command == "stop":
+        sys.exit(cmd_stop(args))
+    elif args.command == "status":
+        sys.exit(cmd_status(args))
+
+
+if __name__ == "__main__":
+    main()

agent/benchmark/config.py

@@ -0,0 +1,15 @@
+"""Simple configuration for benchmark manager."""
+
+from pathlib import Path
+
+# Default benchmarks directory (relative to project root)
+# Use xbow-validation-benchmarks as the default benchmark suite
+DEFAULT_BENCHMARKS_DIR = (
+    Path(__file__).parent.parent.parent / "benchmark" / "xbow-validation-benchmarks" / "benchmarks"
+)
+
+# Default host to bind ports
+DEFAULT_HOST = "0.0.0.0"
+
+# Default port for single benchmark (can be overridden)
+DEFAULT_PORT = 8080

agent/benchmark/docker.py

@@ -0,0 +1,192 @@
+"""Simple Docker manager for benchmarks.
+
+Starts/stops benchmark containers with ports exposed to localhost.
+
+Async versions (``async_*`` prefix) are the primary implementation.
+The original sync names are thin wrappers around ``asyncio.run()`` so
+existing call-sites remain unchanged.  Call the ``async_*`` forms directly
+when already inside an event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from typing import Any
+
+from agent.benchmark.config import DEFAULT_HOST, DEFAULT_PORT
+from agent.tools.executor import AsyncToolExecutor
+
+# One shared executor for all Docker operations; Docker I/O is heavy so we
+# cap concurrency at 3 and give long-running builds up to 10 minutes.
+_docker_executor = AsyncToolExecutor(max_workers=3, default_timeout=600.0)
+
+
+async def async_start_benchmark(benchmark_path: Path, port: int = DEFAULT_PORT) -> dict[str, Any]:
+    """Start a benchmark container (async).
+
+    Args:
+        benchmark_path: Path to benchmark directory (contains docker-compose.yml)
+        port: Port to expose on host (default: 8080)
+
+    Returns:
+        dict with 'success', 'target_url', and 'message'
+    """
+    if not benchmark_path.exists():
+        return {
+            "success": False,
+            "target_url": None,
+            "message": f"Path not found: {benchmark_path}",
+        }
+
+    compose_file = benchmark_path / "docker-compose.yml"
+    if not compose_file.exists():
+        return {"success": False, "target_url": None, "message": "No docker-compose.yml found"}
+
+    print(f"Building benchmark at {benchmark_path.name}...")
+    build_result = await _docker_executor.run(
+        ["make", "build"],
+        cwd=str(benchmark_path),
+        timeout=600.0,
+        shell=False,
+    )
+
+    if not build_result.success:
+        return {
+            "success": False,
+            "target_url": None,
+            "message": f"Build failed: {build_result.stderr or build_result.stdout}",
+        }
+
+    print(f"Starting containers on port {port}...")
+    up_result = await _docker_executor.run(
+        ["docker", "compose", "up", "-d", "--wait"],
+        cwd=str(benchmark_path),
+        timeout=120.0,
+        shell=False,
+    )
+
+    if not up_result.success:
+        return {
+            "success": False,
+            "target_url": None,
+            "message": f"Start failed: {up_result.stderr or up_result.stdout}",
+        }
+
+    actual_port = await async_get_exposed_port(benchmark_path)
+    target_url = f"http://{DEFAULT_HOST}:{actual_port or port}"
+
+    return {
+        "success": True,
+        "target_url": target_url,
+        "port": actual_port or port,
+        "message": f"Benchmark started at {target_url}",
+    }
+
+
+async def async_stop_benchmark(benchmark_path: Path) -> dict[str, Any]:
+    """Stop a benchmark container (async).
+
+    Args:
+        benchmark_path: Path to benchmark directory
+
+    Returns:
+        dict with 'success' and 'message'
+    """
+    if not benchmark_path.exists():
+        return {"success": False, "message": f"Path not found: {benchmark_path}"}
+
+    print(f"Stopping benchmark at {benchmark_path.name}...")
+    result = await _docker_executor.run(
+        ["docker", "compose", "down", "--remove-orphans"],
+        cwd=str(benchmark_path),
+        timeout=60.0,
+        shell=False,
+    )
+
+    if not result.success:
+        return {"success": False, "message": f"Stop failed: {result.stderr or result.stdout}"}
+
+    return {"success": True, "message": "Benchmark stopped"}
+
+
+async def async_get_exposed_port(benchmark_path: Path) -> int | None:
+    """Get the exposed port from running containers (async).
+
+    Args:
+        benchmark_path: Path to benchmark directory
+
+    Returns:
+        Port number or None if not found
+    """
+    result = await _docker_executor.run(
+        ["docker", "compose", "ps", "--format", "{{.Ports}}"],
+        cwd=str(benchmark_path),
+        timeout=15.0,
+        shell=False,
+    )
+
+    if not result.success or not result.stdout.strip():
+        return None
+
+    for line in result.stdout.strip().split("\n"):
+        match = re.search(r"0\.0\.0\.0:(\d+)->", line)
+        if match:
+            return int(match.group(1))
+
+    return None
+
+
+async def async_get_running_benchmarks() -> list[dict[str, Any]]:
+    """Get list of running benchmark containers (async).
+
+    Returns:
+        List of dicts with container info
+    """
+    result = await _docker_executor.run(
+        ["docker", "ps", "--format", "{{.Names}}\t{{.Ports}}\t{{.Status}}"],
+        timeout=15.0,
+        shell=False,
+    )
+
+    if not result.success:
+        return []
+
+    running = []
+    for line in result.stdout.strip().split("\n"):
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) >= 3:
+            name, ports, status = parts[0], parts[1], parts[2]
+            if "xben" in name.lower():
+                running.append({"name": name, "ports": ports, "status": status})
+
+    return running
+
+
+# ---------------------------------------------------------------------------
+# Synchronous wrappers (backward-compatible call-sites)
+# ---------------------------------------------------------------------------
+# These must NOT be called from within a running event loop.
+
+
+def start_benchmark(benchmark_path: Path, port: int = DEFAULT_PORT) -> dict[str, Any]:
+    """Synchronous wrapper around async_start_benchmark."""
+    return asyncio.run(async_start_benchmark(benchmark_path, port))
+
+
+def stop_benchmark(benchmark_path: Path) -> dict[str, Any]:
+    """Synchronous wrapper around async_stop_benchmark."""
+    return asyncio.run(async_stop_benchmark(benchmark_path))
+
+
+def get_exposed_port(benchmark_path: Path) -> int | None:
+    """Synchronous wrapper around async_get_exposed_port."""
+    return asyncio.run(async_get_exposed_port(benchmark_path))
+
+
+def get_running_benchmarks() -> list[dict[str, Any]]:
+    """Synchronous wrapper around async_get_running_benchmarks."""
+    return asyncio.run(async_get_running_benchmarks())

agent/benchmark/registry.py

@@ -0,0 +1,99 @@
+"""Simple benchmark registry - discovers benchmarks from directory."""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent.benchmark.config import DEFAULT_BENCHMARKS_DIR
+
+
+@dataclass
+class BenchmarkInfo:
+    """Information about a benchmark."""
+
+    id: str
+    name: str
+    description: str
+    level: int
+    tags: list[str]
+    path: Path
+
+
+class BenchmarkRegistry:
+    """Discovers benchmarks from a directory."""
+
+    def __init__(self, benchmarks_dir: Path | None = None):
+        self.benchmarks_dir = benchmarks_dir or DEFAULT_BENCHMARKS_DIR
+        self._benchmarks: dict[str, BenchmarkInfo] = {}
+
+    def load(self) -> None:
+        """Load all benchmarks from directory."""
+        self._benchmarks.clear()
+
+        if not self.benchmarks_dir.exists():
+            raise FileNotFoundError(f"Benchmarks directory not found: {self.benchmarks_dir}")
+
+        for benchmark_path in sorted(self.benchmarks_dir.iterdir()):
+            if not benchmark_path.is_dir():
+                continue
+
+            benchmark_json = benchmark_path / "benchmark.json"
+            if not benchmark_json.exists():
+                continue
+
+            try:
+                with open(benchmark_json) as f:
+                    data = json.load(f)
+
+                info = BenchmarkInfo(
+                    id=benchmark_path.name,
+                    name=data.get("name", benchmark_path.name),
+                    description=data.get("description", ""),
+                    level=int(data.get("level", 1)),
+                    tags=data.get("tags", []),
+                    path=benchmark_path,
+                )
+                self._benchmarks[info.id] = info
+            except (json.JSONDecodeError, KeyError, ValueError) as e:
+                print(f"Warning: Failed to parse {benchmark_json}: {e}")
+
+    def get(self, benchmark_id: str) -> BenchmarkInfo | None:
+        """Get benchmark by ID."""
+        if not self._benchmarks:
+            self.load()
+        return self._benchmarks.get(benchmark_id)
+
+    def list_all(self) -> list[BenchmarkInfo]:
+        """List all benchmarks."""
+        if not self._benchmarks:
+            self.load()
+        return sorted(self._benchmarks.values(), key=lambda b: b.id)
+
+    def filter(
+        self,
+        tags: list[str] | None = None,
+        levels: list[int] | None = None,
+    ) -> list[BenchmarkInfo]:
+        """Filter benchmarks by tags or levels."""
+        if not self._benchmarks:
+            self.load()
+
+        result = list(self._benchmarks.values())
+
+        if levels:
+            result = [b for b in result if b.level in levels]
+
+        if tags:
+            tags_lower = [t.lower() for t in tags]
+            result = [b for b in result if any(t.lower() in tags_lower for t in b.tags)]
+
+        return sorted(result, key=lambda b: b.id)
+
+    def get_all_tags(self) -> set[str]:
+        """Get all unique tags."""
+        if not self._benchmarks:
+            self.load()
+        tags: set[str] = set()
+        for b in self._benchmarks.values():
+            tags.update(b.tags)
+        return tags