splitagent 0.0.3__py3-none-any.whl

splitagent/core/models.py

@@ -0,0 +1,310 @@
+"""Data structures shared across the engine, the agents and the reports."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, ClassVar
+
+SEVERITIES = ("critical", "high", "medium", "low", "info")
+
+SEVERITY_ORDER = {name: index for index, name in enumerate(SEVERITIES)}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}-{uuid.uuid4().hex[:8]}"
+
+
+def normalize_severity(value: str | None, score: float | None = None) -> str:
+    if value:
+        value = value.strip().lower()
+        if value in SEVERITY_ORDER:
+            return value
+    if score is not None:
+        if score >= 9.0:
+            return "critical"
+        if score >= 7.0:
+            return "high"
+        if score >= 4.0:
+            return "medium"
+        if score > 0:
+            return "low"
+    return "info"
+
+
+@dataclass
+class Finding:
+    """A vulnerability or weakness discovered by the Red Agent."""
+
+    id: str = field(default_factory=lambda: new_id("F"))
+    title: str = ""
+    category: str = "general"
+    description: str = ""
+    severity: str = "info"
+    cvss_vector: str = ""
+    cvss_score: float = 0.0
+    target: str = ""
+    endpoint: str = ""
+    evidence: str = ""
+    recommendation: str = ""
+    # Report fields: keep the AI's contribution to a fixed, structured shape so
+    # the generated document is consistent from run to run.
+    cwe: str = ""
+    owasp: str = ""
+    impact: str = ""
+    reproduction: str = ""
+    references: list[str] = field(default_factory=list)
+    confidence: str = "medium"
+    discovered_by: str = "red"
+    round: int = 0
+    status: str = "open"  # open | mitigated | accepted | false-positive
+    created_at: str = field(default_factory=_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Finding:
+        if not isinstance(data, dict):
+            return cls()
+        known = set(cls.__dataclass_fields__)
+        filtered = {k: v for k, v in data.items() if k in known}
+        # Coerce the fields the report formats numerically; a corrupt session
+        # must degrade, not crash the renderer.
+        try:
+            filtered["cvss_score"] = float(filtered.get("cvss_score") or 0.0)
+        except (TypeError, ValueError):
+            filtered["cvss_score"] = 0.0
+        try:
+            filtered["round"] = int(filtered.get("round") or 0)
+        except (TypeError, ValueError):
+            filtered["round"] = 0
+        if not isinstance(filtered.get("references"), list):
+            filtered["references"] = []
+        return cls(**filtered)
+
+
+@dataclass
+class Mitigation:
+    """A defensive countermeasure produced by the Blue Agent."""
+
+    id: str = field(default_factory=lambda: new_id("M"))
+    finding_id: str = ""
+    title: str = ""
+    kind: str = "config"  # firewall | patch | config | detection | process
+    description: str = ""
+    content: str = ""
+    rationale: str = ""
+    status: str = "proposed"  # proposed | applied | verified | rejected
+    verified: bool = False
+    round: int = 0
+    created_at: str = field(default_factory=_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Mitigation:
+        if not isinstance(data, dict):
+            return cls()
+        known = set(cls.__dataclass_fields__)
+        filtered = {k: v for k, v in data.items() if k in known}
+        try:
+            filtered["round"] = int(filtered.get("round") or 0)
+        except (TypeError, ValueError):
+            filtered["round"] = 0
+        return cls(**filtered)
+
+
+@dataclass
+class Round:
+    """A single Red -> Blue cycle."""
+
+    index: int = 1
+    red_summary: str = ""
+    blue_summary: str = ""
+    finding_ids: list[str] = field(default_factory=list)
+    mitigation_ids: list[str] = field(default_factory=list)
+    started_at: str = field(default_factory=_now)
+    ended_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Round:
+        if not isinstance(data, dict):
+            return cls()
+        known = set(cls.__dataclass_fields__)
+        filtered = {k: v for k, v in data.items() if k in known}
+        try:
+            filtered["index"] = int(filtered.get("index") or 1)
+        except (TypeError, ValueError):
+            filtered["index"] = 1
+        if not isinstance(filtered.get("finding_ids"), list):
+            filtered["finding_ids"] = []
+        if not isinstance(filtered.get("mitigation_ids"), list):
+            filtered["mitigation_ids"] = []
+        return cls(**filtered)
+
+
+@dataclass
+class SessionState:
+    """The complete, serialisable state of an audit session."""
+
+    id: str = field(default_factory=lambda: new_id("S"))
+    name: str = "splitagent"
+    target: str = ""
+    target_kind: str = "web"
+    scope: list[str] = field(default_factory=list)
+    model: str = ""
+    provider: str = ""
+    started_at: str = field(default_factory=_now)
+    ended_at: str = ""
+    rounds: list[Round] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    mitigations: list[Mitigation] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    usage: dict[str, int] = field(default_factory=dict)
+    checkpoints: list[dict[str, Any]] = field(default_factory=list)
+    traces: dict[str, list[dict[str, Any]]] = field(default_factory=dict)
+    todos: list[dict[str, str]] = field(default_factory=list)
+
+    # -- convenience ------------------------------------------------------- #
+    def add_finding(self, finding: Finding) -> Finding:
+        self.findings.append(finding)
+        return finding
+
+    def add_mitigation(self, mitigation: Mitigation) -> Mitigation:
+        self.mitigations.append(mitigation)
+        return mitigation
+
+    def get_finding(self, finding_id: str) -> Finding | None:
+        return next((f for f in self.findings if f.id == finding_id), None)
+
+    def rounds_by_index(self) -> dict[int, Round]:
+        return {r.index: r for r in self.rounds}
+
+    def latest_round(self) -> Round | None:
+        return self.rounds[-1] if self.rounds else None
+
+    def severity_counts(self) -> dict[str, int]:
+        counts = dict.fromkeys(SEVERITIES, 0)
+        for finding in self.findings:
+            counts[normalize_severity(finding.severity, finding.cvss_score)] += 1
+        return counts
+
+    SEVERITY_WEIGHTS: ClassVar[dict[str, float]] = {
+        "critical": 10.0,
+        "high": 6.0,
+        "medium": 3.0,
+        "low": 1.0,
+        "info": 0.25,
+    }
+
+    def finding_weight(self, finding: Finding) -> float:
+        severity = normalize_severity(finding.severity, finding.cvss_score)
+        return self.SEVERITY_WEIGHTS.get(severity, 0.25)
+
+    def resilience_score(self) -> float:
+        """0-100: how much of the discovered attack surface is actually closed.
+
+        Only a mitigation that was *re-tested* counts. Proposing a firewall
+        rule changes nothing on the target, so scoring proposals as fixes
+        reports a confident number that is simply untrue - which is worse than
+        reporting nothing, because the operator stops looking.
+        """
+        if not self.findings:
+            return 100.0
+        total = 0.0
+        covered = 0.0
+        for finding in self.findings:
+            weight = self.finding_weight(finding)
+            total += weight
+            if self.finding_is_closed(finding):
+                covered += weight
+        if total <= 0:
+            return 100.0
+        return round((covered / total) * 100.0, 1)
+
+    def finding_is_closed(self, finding: Finding) -> bool:
+        """True only when a verified mitigation addresses this finding."""
+        if finding.status in ("false-positive", "accepted"):
+            # Not a real issue, or consciously accepted: not an open risk.
+            return True
+        return any(
+            m.finding_id == finding.id and m.verified and m.status == "verified"
+            for m in self.mitigations
+        )
+
+    def resilience_breakdown(self) -> dict[str, Any]:
+        """The number plus the evidence behind it, for the report and the UI."""
+        proposed = sum(1 for m in self.mitigations if not m.verified)
+        verified = sum(1 for m in self.mitigations if m.verified)
+        open_critical = [
+            f.id
+            for f in self.findings
+            if not self.finding_is_closed(f)
+            and normalize_severity(f.severity, f.cvss_score) == "critical"
+        ]
+        return {
+            "score": self.resilience_score(),
+            "findings_total": len(self.findings),
+            "findings_closed": sum(1 for f in self.findings if self.finding_is_closed(f)),
+            "open_critical": open_critical,
+            "mitigations_proposed": proposed,
+            "mitigations_verified": verified,
+            "verified_is_zero": verified == 0 and bool(self.findings),
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "target": self.target,
+            "target_kind": self.target_kind,
+            "scope": list(self.scope),
+            "model": self.model,
+            "provider": self.provider,
+            "started_at": self.started_at,
+            "ended_at": self.ended_at,
+            "rounds": [r.to_dict() for r in self.rounds],
+            "findings": [f.to_dict() for f in self.findings],
+            "mitigations": [m.to_dict() for m in self.mitigations],
+            "notes": list(self.notes),
+            "usage": dict(self.usage),
+            "checkpoints": list(self.checkpoints),
+            "traces": self.traces,
+            "todos": list(self.todos),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SessionState:
+        return cls(
+            id=data.get("id", new_id("S")),
+            name=data.get("name", "splitagent"),
+            target=data.get("target", ""),
+            target_kind=data.get("target_kind", "web"),
+            scope=list(data.get("scope", [])),
+            model=data.get("model", ""),
+            provider=data.get("provider", ""),
+            started_at=data.get("started_at", _now()),
+            ended_at=data.get("ended_at", ""),
+            rounds=[Round.from_dict(r) for r in data.get("rounds", []) if isinstance(r, dict)],
+            findings=[
+                Finding.from_dict(f) for f in data.get("findings", []) if isinstance(f, dict)
+            ],
+            mitigations=[
+                Mitigation.from_dict(m) for m in data.get("mitigations", []) if isinstance(m, dict)
+            ],
+            notes=list(data.get("notes", [])),
+            usage=dict(data.get("usage", {})),
+            checkpoints=list(data.get("checkpoints", [])),
+            traces=dict(data.get("traces", {})),
+            todos=[dict(item) for item in data.get("todos", [])],
+        )

splitagent/core/proc.py

@@ -0,0 +1,73 @@
+"""Subprocess helpers that never flash a console window on Windows.
+
+When SplitAgent runs under ``pythonw.exe`` (the desktop app) there is no
+console attached. Any child process spawned without the right flags makes
+Windows create one, which shows up as a storm of CMD windows spamming the
+screen - especially during a Docker build or an apt install that spawns many
+subprocesses. Every command SplitAgent runs goes through here.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import Any
+
+# Windows process-creation flags.
+CREATE_NO_WINDOW = 0x08000000
+CREATE_NEW_PROCESS_GROUP = 0x00000200
+DETACHED_PROCESS = 0x00000008
+
+IS_WINDOWS = os.name == "nt"
+
+
+def hidden_flags(detach: bool = False) -> int:
+    """Creation flags that keep a child process invisible and independent."""
+    if not IS_WINDOWS:
+        return 0
+    flags = CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP
+    if detach:
+        flags |= DETACHED_PROCESS
+    return flags
+
+
+def run(
+    argv: list[str],
+    *,
+    cwd: str | None = None,
+    timeout: int | None = None,
+    env: dict[str, str] | None = None,
+    text: bool = False,
+    shell: bool = False,
+) -> subprocess.CompletedProcess[Any]:
+    """``subprocess.run`` with the console window suppressed on Windows."""
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        capture_output=True,
+        timeout=timeout,
+        env=env,
+        check=False,
+        shell=shell,
+        creationflags=hidden_flags(),
+    )
+
+
+def popen(
+    argv: list[str],
+    *,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+    detach: bool = True,
+) -> subprocess.Popen[Any]:
+    """Launch a background process with no console window."""
+    return subprocess.Popen(
+        argv,
+        cwd=cwd,
+        env=env,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        creationflags=hidden_flags(detach=detach),
+        close_fds=True,
+    )

splitagent/core/sandbox.py

@@ -0,0 +1,184 @@
+"""Ephemeral Docker sandbox management.
+
+The sandbox gives the agents a disposable target: a container is started on
+an isolated bridge network, exercised for the duration of the audit and then
+removed. When Docker is unavailable the framework degrades gracefully to
+"local mode" (the agents operate against the configured target only).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+from dataclasses import dataclass
+from typing import Any
+
+from splitagent.config import SandboxConfig
+from splitagent.core import proc
+from splitagent.errors import SandboxError
+
+# Ready-to-use intentionally vulnerable targets for demos / training.
+# ``port_map`` is {host_port: container_port}: the publish argument is
+# ``-p host:container`` and the URL is derived from the host port.
+TARGET_PRESETS: dict[str, dict[str, Any]] = {
+    "juice-shop": {
+        "image": "bkimminich/juice-shop:latest",
+        "port_map": {"3000": 3000},
+        "url": "http://localhost:3000",
+    },
+    "dvwa": {
+        "image": "vulnerables/web-dvwa:latest",
+        "port_map": {"8080": 80},
+        "url": "http://localhost:8080",
+    },
+    "bwapp": {
+        "image": "raesene/bwapp:latest",
+        "port_map": {"8081": 80},
+        "url": "http://localhost:8081",
+    },
+    "webgoat": {
+        "image": "webgoat/webgoat:latest",
+        "port_map": {"8082": 8080},
+        "url": "http://localhost:8082/WebGoat",
+    },
+}
+
+
+@dataclass
+class SandboxStatus:
+    available: bool
+    running: bool = False
+    container_id: str = ""
+    name: str = ""
+    url: str = ""
+    message: str = ""
+
+
+class DockerSandbox:
+    """Thin wrapper around the ``docker`` CLI."""
+
+    def __init__(self, config: SandboxConfig, session_id: str = "run") -> None:
+        self.config = config
+        self.name = f"splitagent-target-{session_id}"
+        self.container_id = ""
+        self.url = ""
+        self.engine = config.engine or "docker"
+
+    # -- detection --------------------------------------------------------- #
+    @staticmethod
+    def docker_available() -> bool:
+        return shutil.which("docker") is not None
+
+    async def _run(self, *args: str, check: bool = False) -> tuple[int, str, str]:
+        try:
+            child = await asyncio.create_subprocess_exec(
+                self.engine,
+                *args,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                stdin=asyncio.subprocess.DEVNULL,
+                # No console window on Windows (the desktop app has none).
+                creationflags=proc.hidden_flags(),
+            )
+        except FileNotFoundError as exc:  # pragma: no cover - guarded by detection
+            raise SandboxError(
+                f"'{self.engine}' was not found on PATH. Disable the sandbox or install Docker."
+            ) from exc
+        stdout, stderr = await child.communicate()
+        code = child.returncode or 0
+        out = stdout.decode("utf-8", "replace").strip()
+        err = stderr.decode("utf-8", "replace").strip()
+        if check and code != 0:
+            raise SandboxError(err or out or f"{self.engine} exited with {code}")
+        return code, out, err
+
+    # -- lifecycle --------------------------------------------------------- #
+    async def up(self) -> SandboxStatus:
+        if not self.config.enabled:
+            return SandboxStatus(available=head_ok(), message="sandbox disabled")
+        if not self.docker_available():
+            return SandboxStatus(
+                available=False,
+                message="Docker not found; running without sandbox.",
+            )
+
+        await self._ensure_network()
+        await self.down(quiet=True)
+
+        args = [
+            "run",
+            "-d",
+            "--name",
+            self.name,
+            "--network",
+            self.config.network or "splitagent-net",
+        ]
+        if self.config.auto_remove:
+            args.append("--rm")
+        for host_port, container_port in (self.config.port_map or {}).items():
+            args += ["-p", f"{host_port}:{container_port}"]
+        args.append(self.config.image)
+
+        code, out, err = await self._run(*args)
+        if code != 0:
+            return SandboxStatus(
+                available=True,
+                running=False,
+                message=err or "failed to start container",
+            )
+        self.container_id = out.splitlines()[-1].strip()
+        self.url = self._infer_url()
+        return SandboxStatus(
+            available=True,
+            running=True,
+            container_id=self.container_id,
+            name=self.name,
+            url=self.url,
+            message="sandbox started",
+        )
+
+    async def down(self, quiet: bool = False) -> None:
+        if not self.docker_available():
+            return
+        await self._run("rm", "-f", self.name)
+        self.container_id = ""
+
+    async def status(self) -> SandboxStatus:
+        if not self.docker_available():
+            return SandboxStatus(available=False, message="Docker not found")
+        code, out, _ = await self._run(
+            "ps", "--filter", f"name={self.name}", "--format", "{{.ID}} {{.Names}}"
+        )
+        running = bool(out.strip()) and code == 0
+        return SandboxStatus(
+            available=True,
+            running=running,
+            name=self.name,
+            message="running" if running else "stopped",
+            url=self.url or self._infer_url(),
+        )
+
+    async def logs(self, tail: int = 100) -> str:
+        _, out, err = await self._run("logs", "--tail", str(tail), self.name)
+        return out or err
+
+    async def exec(self, *command: str) -> str:
+        code, out, err = await self._run("exec", self.name, *command)
+        return out if code == 0 else (err or out)
+
+    async def _ensure_network(self) -> None:
+        network = self.config.network or "splitagent-net"
+        _code, out, _ = await self._run("network", "ls", "--format", "{{.Name}}")
+        if network in out.splitlines():
+            return
+        await self._run("network", "create", network)
+
+    def _infer_url(self) -> str:
+        if not self.config.port_map:
+            return ""
+        host_port = next(iter(self.config.port_map))
+        return f"http://localhost:{host_port}"
+
+
+def head_ok() -> bool:
+    return True