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
refactor(telemetry): extract scan artifact I/O into ``strix.io.scan_artifacts``
0xallam8f1f473eb8a5
diff --git a/pyproject.toml b/pyproject.tomlindex 4081c278..c07cd8f8 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -209,6 +209,9 @@ ignore = [# Backend factories import their backend's deps lazily so deployments# that pick a different backend don't need every backend's libs installed."strix/runtime/backends.py" = ["PLC0415"]+# The vulnerability MD renderer is a long monolithic format function;+# splitting per-section would obscure the structure without simplifying.+"strix/io/scan_artifacts.py" = ["PLR0912", "PLR0915", "PERF401"]"strix/runtime/docker_client.py" = ["TC002", # Manifest, Container imported for annotations"TC003", # uuid imported for annotationdiff --git a/strix/io/__init__.py b/strix/io/__init__.pynew file mode 100644index 00000000..557d8f06--- /dev/null+++ b/strix/io/__init__.py@@ -0,0 +1,6 @@+"""Strix I/O — disk artifact writers.++- :class:`ScanArtifactWriter` — writes vulnerability MD/CSV plus the+ final penetration-test report under ``strix_runs/<run>/``. Used by+ the tracer; could be used directly by post-run tooling.+"""diff --git a/strix/io/scan_artifacts.py b/strix/io/scan_artifacts.pynew file mode 100644index 00000000..4c25fe7c--- /dev/null+++ b/strix/io/scan_artifacts.py@@ -0,0 +1,199 @@+"""Per-scan artifact writer.++Writes the customer-facing penetration-test report and per-vulnerability+markdown + a ``vulnerabilities.csv`` index under ``strix_runs/<run>/``.+"""++from __future__ import annotations++import csv+import logging+from datetime import UTC, datetime+from typing import TYPE_CHECKING, Any+++if TYPE_CHECKING:+ from pathlib import Path+++logger = logging.getLogger(__name__)+++_SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}+++class ScanArtifactWriter:+ """Writes scan artifacts under ``run_dir``. Idempotent on repeat calls.++ Tracks which vulnerability ids have already been written so that+ re-saves only emit new files; the ``vulnerabilities.csv`` index is+ fully rewritten each call so the displayed order stays in sync with+ severity sorting.+ """++ def __init__(self, run_dir: Path):+ self._run_dir = run_dir+ self._saved_vuln_ids: set[str] = set()++ @property+ def run_dir(self) -> Path:+ return self._run_dir++ def save(+ self,+ *,+ vulnerability_reports: list[dict[str, Any]],+ final_scan_result: str | None,+ ) -> None:+ """Write any new vulnerability MDs + rewrite the CSV index ++ write the executive penetration-test report if available.++ Tolerant of OSError / RuntimeError — logs and swallows so a+ cleanup failure can't prevent the next scan from finishing.+ """+ try:+ self._run_dir.mkdir(parents=True, exist_ok=True)++ if final_scan_result:+ self._write_executive_report(final_scan_result)++ if vulnerability_reports:+ self._write_vulnerabilities(vulnerability_reports)++ logger.info("📊 Essential scan data saved to: %s", self._run_dir)+ except (OSError, RuntimeError):+ logger.exception("Failed to save scan data")++ # --- internals ---------------------------------------------------------++ def _write_executive_report(self, body: str) -> None:+ path = self._run_dir / "penetration_test_report.md"+ with path.open("w", encoding="utf-8") as f:+ f.write("# Security Penetration Test Report\n\n")+ f.write(f"**Generated:** {datetime.now(UTC).strftime('%Y-%m-%d %H:%M:%S UTC')}\n\n")+ f.write(f"{body}\n")+ logger.info("Saved final penetration test report to: %s", path)++ def _write_vulnerabilities(self, reports: list[dict[str, Any]]) -> None:+ vuln_dir = self._run_dir / "vulnerabilities"+ vuln_dir.mkdir(exist_ok=True)++ new_reports = [r for r in reports if r["id"] not in self._saved_vuln_ids]++ for report in new_reports:+ (vuln_dir / f"{report['id']}.md").write_text(+ _render_vulnerability_md(report),+ encoding="utf-8",+ )+ self._saved_vuln_ids.add(report["id"])++ sorted_reports = sorted(+ reports,+ key=lambda r: (_SEVERITY_ORDER.get(r["severity"], 5), r["timestamp"]),+ )+ csv_path = self._run_dir / "vulnerabilities.csv"+ with csv_path.open("w", encoding="utf-8", newline="") as f:+ fieldnames = ["id", "title", "severity", "timestamp", "file"]+ writer = csv.DictWriter(f, fieldnames=fieldnames)+ writer.writeheader()+ for report in sorted_reports:+ writer.writerow(+ {+ "id": report["id"],+ "title": report["title"],+ "severity": report["severity"].upper(),+ "timestamp": report["timestamp"],+ "file": f"vulnerabilities/{report['id']}.md",+ },+ )++ if new_reports:+ logger.info(+ "Saved %d new vulnerability report(s) to: %s",+ len(new_reports),+ vuln_dir,+ )+ logger.info("Updated vulnerability index: %s", csv_path)+++def _render_vulnerability_md(report: dict[str, Any]) -> str:+ lines: list[str] = [+ f"# {report.get('title', 'Untitled Vulnerability')}\n",+ f"**ID:** {report.get('id', 'unknown')}",+ f"**Severity:** {report.get('severity', 'unknown').upper()}",+ f"**Found:** {report.get('timestamp', 'unknown')}",+ ]++ metadata: list[tuple[str, Any]] = [+ ("Target", report.get("target")),+ ("Endpoint", report.get("endpoint")),+ ("Method", report.get("method")),+ ("CVE", report.get("cve")),+ ("CWE", report.get("cwe")),+ ]+ cvss = report.get("cvss")+ if cvss is not None:+ metadata.append(("CVSS", cvss))+ for label, value in metadata:+ if value:+ lines.append(f"**{label}:** {value}")++ lines.append("")+ lines.append("## Description\n")+ lines.append(report.get("description") or "No description provided.")+ lines.append("")++ if report.get("impact"):+ lines.append("## Impact\n")+ lines.append(str(report["impact"]))+ lines.append("")++ if report.get("technical_analysis"):+ lines.append("## Technical Analysis\n")+ lines.append(str(report["technical_analysis"]))+ lines.append("")++ if report.get("poc_description") or report.get("poc_script_code"):+ lines.append("## Proof of Concept\n")+ if report.get("poc_description"):+ lines.append(str(report["poc_description"]))+ lines.append("")+ if report.get("poc_script_code"):+ lines.append("```")+ lines.append(str(report["poc_script_code"]))+ lines.append("```")+ lines.append("")++ if report.get("code_locations"):+ lines.append("## Code Analysis\n")+ for i, loc in enumerate(report["code_locations"]):+ file_ref = loc.get("file", "unknown")+ line_ref = ""+ if loc.get("start_line") is not None:+ if loc.get("end_line") and loc["end_line"] != loc["start_line"]:+ line_ref = f" (lines {loc['start_line']}-{loc['end_line']})"+ else:+ line_ref = f" (line {loc['start_line']})"+ lines.append(f"**Location {i + 1}:** `{file_ref}`{line_ref}")+ if loc.get("label"):+ lines.append(f" {loc['label']}")+ if loc.get("snippet"):+ lines.append(f" ```\n {loc['snippet']}\n ```")+ if loc.get("fix_before") or loc.get("fix_after"):+ lines.append("\n **Suggested Fix:**")+ lines.append("```diff")+ if loc.get("fix_before"):+ for ln in str(loc["fix_before"]).splitlines():+ lines.append(f"- {ln}")+ if loc.get("fix_after"):+ for ln in str(loc["fix_after"]).splitlines():+ lines.append(f"+ {ln}")+ lines.append("```")+ lines.append("")++ if report.get("remediation_steps"):+ lines.append("## Remediation\n")+ lines.append(str(report["remediation_steps"]))+ lines.append("")++ return "\n".join(lines)diff --git a/strix/telemetry/tracer.py b/strix/telemetry/tracer.pyindex 3f46ecb2..48f81a02 100644--- a/strix/telemetry/tracer.py+++ b/strix/telemetry/tracer.py@@ -5,6 +5,7 @@ from pathlib import Pathfrom typing import Any, Optionalfrom uuid import uuid4+from strix.io.scan_artifacts import ScanArtifactWriterfrom strix.telemetry import posthog@@ -67,8 +68,8 @@ class Tracer:"status": "running",}self._run_dir: Path | None = None+ self._writer: ScanArtifactWriter | None = Noneself._next_message_id = 1- self._saved_vuln_ids: set[str] = set()self.caido_url: str | None = Noneself.vulnerability_found_callback: Callable[[dict[str, Any]], None] | None = None@@ -79,6 +80,7 @@ class Tracer:self.run_metadata["run_name"] = run_nameself.run_metadata["run_id"] = run_nameself._run_dir = None+ self._writer = Nonedef get_run_dir(self) -> Path:if self._run_dir is None:@@ -91,6 +93,11 @@ class Tracer:return self._run_dir+ def _get_writer(self) -> ScanArtifactWriter:+ if self._writer is None:+ self._writer = ScanArtifactWriter(self.get_run_dir())+ return self._writer+def add_vulnerability_report(self,title: str,@@ -231,155 +238,16 @@ class Tracer:)def save_run_data(self, mark_complete: bool = False) -> None:- try:- run_dir = self.get_run_dir()- if mark_complete:- if self.end_time is None:- self.end_time = datetime.now(UTC).isoformat()- self.run_metadata["end_time"] = self.end_time- self.run_metadata["status"] = "completed"-- if self.final_scan_result:- penetration_test_report_file = run_dir / "penetration_test_report.md"- with penetration_test_report_file.open("w", encoding="utf-8") as f:- f.write("# Security Penetration Test Report\n\n")- f.write(- f"**Generated:** {datetime.now(UTC).strftime('%Y-%m-%d %H:%M:%S UTC')}\n\n"- )- f.write(f"{self.final_scan_result}\n")- logger.info(- "Saved final penetration test report to: %s",- penetration_test_report_file,- )-- if self.vulnerability_reports:- vuln_dir = run_dir / "vulnerabilities"- vuln_dir.mkdir(exist_ok=True)-- new_reports = [- report- for report in self.vulnerability_reports- if report["id"] not in self._saved_vuln_ids- ]-- severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}- sorted_reports = sorted(- self.vulnerability_reports,- key=lambda report: (- severity_order.get(report["severity"], 5),- report["timestamp"],- ),- )-- for report in new_reports:- vuln_file = vuln_dir / f"{report['id']}.md"- with vuln_file.open("w", encoding="utf-8") as f:- f.write(f"# {report.get('title', 'Untitled Vulnerability')}\n\n")- f.write(f"**ID:** {report.get('id', 'unknown')}\n")- f.write(f"**Severity:** {report.get('severity', 'unknown').upper()}\n")- f.write(f"**Found:** {report.get('timestamp', 'unknown')}\n")-- metadata_fields: list[tuple[str, Any]] = [- ("Target", report.get("target")),- ("Endpoint", report.get("endpoint")),- ("Method", report.get("method")),- ("CVE", report.get("cve")),- ("CWE", report.get("cwe")),- ]- cvss_score = report.get("cvss")- if cvss_score is not None:- metadata_fields.append(("CVSS", cvss_score))-- for label, value in metadata_fields:- if value:- f.write(f"**{label}:** {value}\n")-- f.write("\n## Description\n\n")- description = report.get("description") or "No description provided."- f.write(f"{description}\n\n")-- if report.get("impact"):- f.write("## Impact\n\n")- f.write(f"{report['impact']}\n\n")-- if report.get("technical_analysis"):- f.write("## Technical Analysis\n\n")- f.write(f"{report['technical_analysis']}\n\n")-- if report.get("poc_description") or report.get("poc_script_code"):- f.write("## Proof of Concept\n\n")- if report.get("poc_description"):- f.write(f"{report['poc_description']}\n\n")- if report.get("poc_script_code"):- f.write("```\n")- f.write(f"{report['poc_script_code']}\n")- f.write("```\n\n")-- if report.get("code_locations"):- f.write("## Code Analysis\n\n")- for i, loc in enumerate(report["code_locations"]):- prefix = f"**Location {i + 1}:**"- file_ref = loc.get("file", "unknown")- line_ref = ""- if loc.get("start_line") is not None:- if loc.get("end_line") and loc["end_line"] != loc["start_line"]:- line_ref = f" (lines {loc['start_line']}-{loc['end_line']})"- else:- line_ref = f" (line {loc['start_line']})"- f.write(f"{prefix} `{file_ref}`{line_ref}\n")- if loc.get("label"):- f.write(f" {loc['label']}\n")- if loc.get("snippet"):- f.write(f" ```\n {loc['snippet']}\n ```\n")- if loc.get("fix_before") or loc.get("fix_after"):- f.write("\n **Suggested Fix:**\n")- f.write("```diff\n")- if loc.get("fix_before"):- for line in loc["fix_before"].splitlines():- f.write(f"- {line}\n")- if loc.get("fix_after"):- for line in loc["fix_after"].splitlines():- f.write(f"+ {line}\n")- f.write("```\n")- f.write("\n")-- if report.get("remediation_steps"):- f.write("## Remediation\n\n")- f.write(f"{report['remediation_steps']}\n\n")-- self._saved_vuln_ids.add(report["id"])-- vuln_csv_file = run_dir / "vulnerabilities.csv"- with vuln_csv_file.open("w", encoding="utf-8", newline="") as f:- import csv-- fieldnames = ["id", "title", "severity", "timestamp", "file"]- writer = csv.DictWriter(f, fieldnames=fieldnames)- writer.writeheader()-- for report in sorted_reports:- writer.writerow(- {- "id": report["id"],- "title": report["title"],- "severity": report["severity"].upper(),- "timestamp": report["timestamp"],- "file": f"vulnerabilities/{report['id']}.md",- }- )-- if new_reports:- logger.info(- "Saved %d new vulnerability report(s) to: %s",- len(new_reports),- vuln_dir,- )- logger.info("Updated vulnerability index: %s", vuln_csv_file)-- logger.info("📊 Essential scan data saved to: %s", run_dir)-- except (OSError, RuntimeError):- logger.exception("Failed to save scan data")+ if mark_complete:+ if self.end_time is None:+ self.end_time = datetime.now(UTC).isoformat()+ self.run_metadata["end_time"] = self.end_time+ self.run_metadata["status"] = "completed"++ self._get_writer().save(+ vulnerability_reports=self.vulnerability_reports,+ final_scan_result=self.final_scan_result,+ )def log_tool_start(self, agent_id: str, tool_name: str) -> int:"""Record a tool invocation in flight. Returns an exec_id."""