mirror of
https://github.com/Strategic-Automation/violin.git
synced 2026-08-14 12:33:37 +02:00
325 lines
10 KiB
Python
325 lines
10 KiB
Python
"""Guarded process execution, evidence persistence, and receipt registry.
|
|
|
|
This is the ONLY module in core/ that uses subprocess. All others are pure.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import os
|
|
import re
|
|
import shutil
|
|
import signal
|
|
import subprocess
|
|
import time
|
|
import uuid
|
|
from datetime import UTC, datetime
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
from . import state
|
|
from .phases import normalize_phase
|
|
|
|
__all__ = [
|
|
"execute",
|
|
"status",
|
|
"cancel",
|
|
"SCHEMA_VERSION",
|
|
"DEFAULT_TIMEOUT",
|
|
"MAX_TIMEOUT",
|
|
"MIN_TIMEOUT",
|
|
"MAX_OUTPUT_BYTES",
|
|
"PREVIEW_BYTES",
|
|
]
|
|
|
|
SCHEMA_VERSION = 2
|
|
DEFAULT_TIMEOUT = 180
|
|
MIN_TIMEOUT = 1
|
|
MAX_TIMEOUT = 1800
|
|
MAX_OUTPUT_BYTES = 10 * 1024 * 1024
|
|
PREVIEW_BYTES = 32 * 1024
|
|
DOCKER_CONTAINER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
|
|
|
|
|
|
def _utc_now() -> str:
|
|
return datetime.now(UTC).isoformat().replace("+00:00", "Z")
|
|
|
|
|
|
def _atomic_json(path: Path, value: dict[str, Any]) -> None:
|
|
path.parent.mkdir(parents=True, exist_ok=True)
|
|
tmp = path.with_suffix(path.suffix + ".tmp")
|
|
tmp.write_text(json.dumps(value, indent=2, sort_keys=True), encoding="utf-8")
|
|
tmp.replace(path)
|
|
|
|
|
|
def _read_json(path: Path) -> dict[str, Any]:
|
|
try:
|
|
return json.loads(path.read_text(encoding="utf-8"))
|
|
except (OSError, json.JSONDecodeError):
|
|
return {}
|
|
|
|
|
|
def _resolve_engagement(eng_dir: str) -> Path:
|
|
path = Path(eng_dir).resolve()
|
|
if not path.is_dir():
|
|
raise ValueError(f"engagement directory not found: {path}")
|
|
return path
|
|
|
|
|
|
def _resolve_cwd(eng_dir: Path, cwd: str) -> Path:
|
|
candidate = (eng_dir / (cwd or ".")).resolve()
|
|
try:
|
|
candidate.relative_to(eng_dir)
|
|
except ValueError as exc:
|
|
raise ValueError("cwd must stay inside the engagement directory") from exc
|
|
if not candidate.is_dir():
|
|
raise ValueError(f"execution cwd not found: {candidate}")
|
|
return candidate
|
|
|
|
|
|
def _label(value: str) -> str:
|
|
cleaned = re.sub(r"[^A-Za-z0-9_.-]+", "-", value.strip()).strip("-.")
|
|
return (cleaned or "command")[:64]
|
|
|
|
|
|
def _timeout(value: Any) -> int:
|
|
try:
|
|
parsed = int(value or DEFAULT_TIMEOUT)
|
|
except (TypeError, ValueError) as exc:
|
|
raise ValueError("timeout_seconds must be an integer") from exc
|
|
if not MIN_TIMEOUT <= parsed <= MAX_TIMEOUT:
|
|
raise ValueError(f"timeout_seconds must be between {MIN_TIMEOUT} and {MAX_TIMEOUT}")
|
|
return parsed
|
|
|
|
|
|
def _command_argv(
|
|
command: str, backend: str, cwd: Path, eng_dir: Path, container: str
|
|
) -> list[str]:
|
|
if backend == "local":
|
|
if os.name == "nt":
|
|
return [os.environ.get("COMSPEC", "cmd.exe"), "/d", "/s", "/c", command]
|
|
return ["/bin/sh", "-lc", command]
|
|
|
|
if backend != "docker":
|
|
raise ValueError("backend must be local or docker")
|
|
|
|
if not DOCKER_CONTAINER_RE.fullmatch(container):
|
|
raise ValueError("invalid Docker container name")
|
|
|
|
if shutil.which("docker") is None:
|
|
raise ValueError("Docker backend unavailable: docker executable not found")
|
|
|
|
relative = cwd.relative_to(eng_dir).as_posix()
|
|
docker_cwd = "/engagement" if relative == "." else f"/engagement/{relative}"
|
|
return ["docker", "exec", "-i", "-w", docker_cwd, container, "sh", "-lc", command]
|
|
|
|
|
|
def _terminate_pid(pid: int) -> None:
|
|
if pid <= 0:
|
|
return
|
|
if os.name == "nt":
|
|
subprocess.run(
|
|
["taskkill", "/PID", str(pid), "/T", "/F"],
|
|
capture_output=True,
|
|
check=False,
|
|
)
|
|
else:
|
|
try:
|
|
os.killpg(pid, signal.SIGTERM)
|
|
time.sleep(0.2)
|
|
os.killpg(pid, signal.SIGKILL)
|
|
except ProcessLookupError:
|
|
pass
|
|
|
|
|
|
def _preview(path: Path) -> str:
|
|
with path.open("rb") as handle:
|
|
return handle.read(PREVIEW_BYTES).decode("utf-8", errors="replace")
|
|
|
|
|
|
def _record_history(eng_dir: Path, command: str, exit_code: int, phase: str, evidence: str) -> None:
|
|
state.append_history(eng_dir, command, phase, exit_code, evidence)
|
|
|
|
|
|
def execute(
|
|
command: str,
|
|
*,
|
|
eng_dir: str,
|
|
phase: str,
|
|
backend: str = "local",
|
|
timeout_seconds: Any = DEFAULT_TIMEOUT,
|
|
cwd: str = "",
|
|
label: str = "",
|
|
docker_container: str = "kali-pentest",
|
|
) -> dict[str, Any]:
|
|
"""Execute one already-authorized command and persist its complete receipt."""
|
|
engagement = _resolve_engagement(eng_dir)
|
|
workdir = _resolve_cwd(engagement, cwd)
|
|
timeout = _timeout(timeout_seconds)
|
|
execution_id = str(uuid.uuid4())
|
|
started_at = _utc_now()
|
|
stem = f"{started_at[:19].replace(':', '')}-{execution_id[:8]}-{_label(label)}"
|
|
evidence_dir = engagement / "evidence" / "executions"
|
|
stdout_path = evidence_dir / f"{stem}.stdout.txt"
|
|
stderr_path = evidence_dir / f"{stem}.stderr.txt"
|
|
manifest_path = evidence_dir / f"{stem}.json"
|
|
registry_path = engagement / "state" / "executions" / f"{execution_id}.json"
|
|
|
|
evidence_dir.mkdir(parents=True, exist_ok=True)
|
|
|
|
record: dict[str, Any] = {
|
|
"schema_version": SCHEMA_VERSION,
|
|
"execution_id": execution_id,
|
|
"status": "starting",
|
|
"backend": backend,
|
|
"command": command,
|
|
"phase": phase,
|
|
"cwd": str(workdir),
|
|
"started_at": started_at,
|
|
"pid": None,
|
|
}
|
|
_atomic_json(registry_path, record)
|
|
|
|
timed_out = False
|
|
output_limited = False
|
|
cancelled = False
|
|
proc: subprocess.Popen | None = None
|
|
|
|
try:
|
|
with stdout_path.open("wb") as stdout_file, stderr_path.open("wb") as stderr_file:
|
|
popen_kwargs: dict[str, Any] = {
|
|
"cwd": str(workdir),
|
|
"stdout": stdout_file,
|
|
"stderr": stderr_file,
|
|
"stdin": subprocess.DEVNULL,
|
|
"shell": False,
|
|
}
|
|
if os.name == "nt":
|
|
popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
|
|
else:
|
|
popen_kwargs["start_new_session"] = True
|
|
|
|
argv = _command_argv(command, backend, workdir, engagement, docker_container)
|
|
proc = subprocess.Popen(argv, **popen_kwargs)
|
|
|
|
record.update(status="running", pid=proc.pid)
|
|
_atomic_json(registry_path, record)
|
|
|
|
deadline = time.monotonic() + timeout
|
|
while proc.poll() is None:
|
|
current = _read_json(registry_path)
|
|
if current.get("cancel_requested"):
|
|
cancelled = True
|
|
_terminate_pid(proc.pid)
|
|
break
|
|
if time.monotonic() >= deadline:
|
|
timed_out = True
|
|
_terminate_pid(proc.pid)
|
|
break
|
|
stdout_file.flush()
|
|
stderr_file.flush()
|
|
if stdout_path.stat().st_size + stderr_path.stat().st_size > MAX_OUTPUT_BYTES:
|
|
output_limited = True
|
|
_terminate_pid(proc.pid)
|
|
break
|
|
time.sleep(0.1)
|
|
|
|
try:
|
|
exit_code = proc.wait(timeout=5)
|
|
except subprocess.TimeoutExpired:
|
|
_terminate_pid(proc.pid)
|
|
exit_code = proc.wait(timeout=5)
|
|
except Exception as exc:
|
|
exit_code = -1
|
|
stderr_path.write_text(f"executor error: {exc}\n", encoding="utf-8")
|
|
|
|
completed_at = _utc_now()
|
|
rel_manifest = manifest_path.relative_to(engagement).as_posix()
|
|
rel_stdout = stdout_path.relative_to(engagement).as_posix()
|
|
rel_stderr = stderr_path.relative_to(engagement).as_posix()
|
|
|
|
receipt = {
|
|
**record,
|
|
"status": "cancelled"
|
|
if cancelled
|
|
else "timed_out"
|
|
if timed_out
|
|
else "output_limited"
|
|
if output_limited
|
|
else "completed",
|
|
"completed_at": completed_at,
|
|
"exit_code": exit_code,
|
|
"timed_out": timed_out,
|
|
"cancelled": cancelled,
|
|
"output_limited": output_limited,
|
|
"evidence_paths": {
|
|
"manifest": rel_manifest,
|
|
"stdout": rel_stdout,
|
|
"stderr": rel_stderr,
|
|
},
|
|
}
|
|
_atomic_json(manifest_path, receipt)
|
|
_atomic_json(registry_path, receipt)
|
|
|
|
_record_history(engagement, command, exit_code, phase, rel_manifest)
|
|
|
|
if state.is_local_bookkeeping_command(command):
|
|
remaining = state.sync_credit_remaining(str(engagement))
|
|
else:
|
|
remaining = _commit_guard_state(engagement, command, phase)
|
|
|
|
return {
|
|
**receipt,
|
|
"executed": True,
|
|
"stdout_preview": _preview(stdout_path),
|
|
"stderr_preview": _preview(stderr_path),
|
|
"sync_required": remaining <= 0,
|
|
"sync_credit_remaining": remaining,
|
|
}
|
|
|
|
|
|
def _commit_guard_state(eng_dir: Path, command: str, phase: str) -> int:
|
|
state.record_ok_check(str(eng_dir), command, phase)
|
|
remaining = state.spend_sync_credit(str(eng_dir))
|
|
state.mark_pending_sync(str(eng_dir), command, phase)
|
|
count = state.tick_command(str(eng_dir))
|
|
from .phases import suppresses_heartbeat
|
|
|
|
phase_enum = normalize_phase(phase)
|
|
if count % state.COMMAND_INTERVAL == 0 and not suppresses_heartbeat(phase_enum):
|
|
state.set_heartbeat_pending(
|
|
str(eng_dir),
|
|
f"Reached {count} executed target commands. Review engagement files for drift.",
|
|
)
|
|
return remaining
|
|
|
|
|
|
def status(eng_dir: str, execution_id: str) -> dict[str, Any]:
|
|
engagement = _resolve_engagement(eng_dir)
|
|
if not re.fullmatch(r"[0-9a-fA-F-]{36}", execution_id):
|
|
raise ValueError("invalid execution_id")
|
|
path = engagement / "state" / "executions" / f"{execution_id}.json"
|
|
record = _read_json(path)
|
|
if not record:
|
|
raise ValueError("execution not found")
|
|
return record
|
|
|
|
|
|
def cancel(eng_dir: str, execution_id: str) -> dict[str, Any]:
|
|
engagement = _resolve_engagement(eng_dir)
|
|
path = engagement / "state" / "executions" / f"{execution_id}.json"
|
|
record = status(str(engagement), execution_id)
|
|
if record.get("status") not in {"starting", "running"}:
|
|
return {**record, "cancel_requested": False, "message": "execution is not running"}
|
|
|
|
pid = record.get("pid")
|
|
if not isinstance(pid, int) or pid <= 0:
|
|
raise ValueError("running execution has no valid tracked PID")
|
|
|
|
record["cancel_requested"] = True
|
|
record["cancel_requested_at"] = _utc_now()
|
|
_atomic_json(path, record)
|
|
_terminate_pid(pid)
|
|
|
|
return {**record, "message": "cancellation requested for tracked process group"}
|