strix-agent 0.1.1__py3-none-any.whl

strix/tools/reporting/reporting_actions.py

@@ -0,0 +1,63 @@
+from typing import Any
+
+from strix.tools.registry import register_tool
+
+
+@register_tool(sandbox_execution=False)
+def create_vulnerability_report(
+    title: str,
+    content: str,
+    severity: str,
+) -> dict[str, Any]:
+    validation_error = None
+    if not title or not title.strip():
+        validation_error = "Title cannot be empty"
+    elif not content or not content.strip():
+        validation_error = "Content cannot be empty"
+    elif not severity or not severity.strip():
+        validation_error = "Severity cannot be empty"
+    else:
+        valid_severities = ["critical", "high", "medium", "low", "info"]
+        if severity.lower() not in valid_severities:
+            validation_error = (
+                f"Invalid severity '{severity}'. Must be one of: {', '.join(valid_severities)}"
+            )
+
+    if validation_error:
+        return {"success": False, "message": validation_error}
+
+    try:
+        from strix.cli.tracer import get_global_tracer
+
+        tracer = get_global_tracer()
+        if tracer:
+            report_id = tracer.add_vulnerability_report(
+                title=title,
+                content=content,
+                severity=severity,
+            )
+
+            return {
+                "success": True,
+                "message": f"Vulnerability report '{title}' created successfully",
+                "report_id": report_id,
+                "severity": severity.lower(),
+            }
+        import logging
+
+        logging.warning("Global tracer not available - vulnerability report not stored")
+
+        return {  # noqa: TRY300
+            "success": True,
+            "message": f"Vulnerability report '{title}' created successfully (not persisted)",
+            "warning": "Report could not be persisted - tracer unavailable",
+        }
+
+    except ImportError:
+        return {
+            "success": True,
+            "message": f"Vulnerability report '{title}' created successfully (not persisted)",
+            "warning": "Report could not be persisted - tracer module unavailable",
+        }
+    except (ValueError, TypeError) as e:
+        return {"success": False, "message": f"Failed to create vulnerability report: {e!s}"}

strix/tools/reporting/reporting_actions_schema.xml

@@ -0,0 +1,30 @@
+<tools>
+  <tool name="create_vulnerability_report">
+    <description>Create a vulnerability report for a discovered security issue.
+
+Use this tool to document a specific verified security vulnerability.
+Put ALL details in the content field - affected URLs, parameters, proof of concept, remediation steps, CVE references, CVSS scores, technical details, impact assessment, etc.
+
+DO NOT USE:
+- For general security observations without specific vulnerabilities
+- When you don't have concrete vulnerability details
+- When you don't have a proof of concept, or still not 100% sure if it's a vulnerability
+- For tracking multiple vulnerabilities (create separate reports)
+- For reporting multiple vulnerabilities at once. Use a separate create_vulnerability_report for each vulnerability.
+</description>
+    <parameters>
+      <parameter name="title" type="string" required="true">
+        <description>Clear, concise title of the vulnerability</description>
+      </parameter>
+      <parameter name="content" type="string" required="true">
+        <description>Complete vulnerability details including affected URLs, technical details, impact, proof of concept, remediation steps, and any relevant references. Be comprehensive and include everything relevant.</description>
+      </parameter>
+      <parameter name="severity" type="string" required="true">
+        <description>Severity level: critical, high, medium, low, or info</description>
+      </parameter>
+    </parameters>
+    <returns type="Dict[str, Any]">
+      <description>Response containing success status and message</description>
+    </returns>
+  </tool>
+</tools>

strix/tools/terminal/__init__.py

@@ -0,0 +1,4 @@
+from .terminal_actions import terminal_action
+
+
+__all__ = ["terminal_action"]

strix/tools/terminal/terminal_actions.py

@@ -0,0 +1,53 @@
+from typing import Any, Literal
+
+from strix.tools.registry import register_tool
+
+from .terminal_manager import get_terminal_manager
+
+
+TerminalAction = Literal["new_terminal", "send_input", "wait", "close"]
+
+
+@register_tool
+def terminal_action(
+    action: TerminalAction,
+    inputs: list[str] | None = None,
+    time: float | None = None,
+    terminal_id: str | None = None,
+) -> dict[str, Any]:
+    def _validate_inputs(action_name: str, inputs: list[str] | None) -> None:
+        if not inputs:
+            raise ValueError(f"inputs parameter is required for {action_name} action")
+
+    def _validate_time(time_param: float | None) -> None:
+        if time_param is None:
+            raise ValueError("time parameter is required for wait action")
+
+    def _validate_action(action_name: str) -> None:
+        raise ValueError(f"Unknown action: {action_name}")
+
+    manager = get_terminal_manager()
+
+    try:
+        match action:
+            case "new_terminal":
+                return manager.create_terminal(terminal_id, inputs)
+
+            case "send_input":
+                _validate_inputs(action, inputs)
+                assert inputs is not None
+                return manager.send_input(terminal_id, inputs)
+
+            case "wait":
+                _validate_time(time)
+                assert time is not None
+                return manager.wait_terminal(terminal_id, time)
+
+            case "close":
+                return manager.close_terminal(terminal_id)
+
+            case _:
+                _validate_action(action)  # type: ignore[unreachable]
+
+    except (ValueError, RuntimeError) as e:
+        return {"error": str(e), "terminal_id": terminal_id, "snapshot": "", "is_running": False}

strix/tools/terminal/terminal_actions_schema.xml

@@ -0,0 +1,114 @@
+<tools>
+  <tool name="terminal_action">
+    <description>Perform terminal actions using a terminal emulator instance. Each terminal instance
+  is PERSISTENT and remains active until explicitly closed, allowing for multi-step
+  workflows and long-running processes.</description>
+    <parameters>
+      <parameter name="action" type="string" required="true">
+        <description>The terminal action to perform: - new_terminal: Create a new terminal instance. This MUST be the first action   for each terminal tab. - send_input: Send keyboard input to the specified terminal. - wait: Pause execution for specified number of seconds. Can be also used to get   the current terminal state (screenshot, output, etc.) after using other tools. - close: Close the specified terminal instance. This MUST be the final action   for each terminal tab.</description>
+      </parameter>
+      <parameter name="inputs" type="string" required="false">
+        <description>Required for 'new_terminal' and 'send_input' actions: - List of inputs to send to terminal.   Each element in the list MUST be one of the following:   - Regular text: "hello", "world", etc.   - Literal text (not interpreted as special keys): prefix with "literal:"     e.g., "literal:Home", "literal:Escape", "literal:Enter" to send these as text   - Enter   - Space   - Backspace   - Escape: "Escape", "^[", "C-["   - Tab: "Tab"   - Arrow keys: "Left", "Right", "Up", "Down"   - Navigation: "Home", "End", "PageUp", "PageDown"   - Function keys: "F1" through "F12"   Modifier keys supported with prefixes:   - ^ or C- : Control (e.g., "^c", "C-c")   - S- : Shift (e.g., "S-F6")   - A- : Alt (e.g., "A-Home")   - Combined modifiers for arrows: "S-A-Up", "C-S-Left"   - Inputs MUST in all cases be sent as a LIST of strings, even if you are only     sending one input.   - Sending Inputs as a single string will NOT work.</description>
+      </parameter>
+      <parameter name="time" type="string" required="false">
+        <description>Required for 'wait' action. Number of seconds to pause execution. Can be fractional (e.g., 0.5 for half a second).</description>
+      </parameter>
+      <parameter name="terminal_id" type="string" required="false">
+        <description>Identifier for the terminal instance. Required for all actions except the first 'new_terminal' action. Allows managing multiple concurrent terminal tabs. - For 'new_terminal': if not provided, a default terminal is created. If provided,   creates a new terminal with that ID. - For other actions: specifies which terminal instance to operate on. - Default terminal ID is "default" if not specified.</description>
+      </parameter>
+    </parameters>
+    <returns type="Dict[str, Any]">
+      <description>Response containing: - snapshot: raw representation of current terminal state where you can see the   output of the command - terminal_id: the ID of the terminal instance that was operated on</description>
+    </returns>
+    <notes>
+  Important usage rules:
+  1. PERSISTENCE: Terminal instances remain active and maintain their state (environment
+     variables, current directory, running processes) until explicitly closed with the
+     'close' action. This allows for multi-step workflows across multiple tool calls.
+  2. MULTIPLE TERMINALS: You can run multiple terminal instances concurrently by using
+     different terminal_id values. Each terminal operates independently.
+  3. Terminal interaction MUST begin with 'new_terminal' action for each terminal instance.
+  4. Only one action can be performed per call.
+  5. Input handling:
+     - Regular text is sent as-is
+     - Literal text: prefix with "literal:" to send special key names as literal text
+     - Special keys must match supported key names
+     - Modifier combinations follow specific syntax
+     - Control can be specified as ^ or C- prefix
+     - Shift (S-) works with special keys only
+     - Alt (A-) works with any character/key
+  6. Wait action:
+      - Time is specified in seconds
+      - Can be used to wait for command completion
+      - Can be fractional (e.g., 0.5 seconds)
+      - Snapshot and output are captured after the wait
+      - You should estimate the time it will take to run the command and set the wait time accordingly.
+      - It can be from a few seconds to a few minutes, choose wisely depending on the command you are running and the task.
+  7. The terminal can operate concurrently with other tools. You may invoke
+     browser, proxy, or other tools (in separate assistant messages) while maintaining
+     active terminal sessions.
+  8. You do not need to close terminals after you are done, but you can if you want to
+     free up resources.
+  9. You MUST end the inputs list with an "Enter" if you want to run the command, as
+     it is not sent automatically.
+  10. AUTOMATIC SPACING BEHAVIOR:
+      - Consecutive regular text inputs have spaces automatically added between them
+      - This is helpful for shell commands: ["ls", "-la"] becomes "ls -la"
+      - This causes problems for compound commands: [":", "w", "q"] becomes ": w q"
+      - Use "literal:" prefix to bypass spacing: [":", "literal:wq"] becomes ":wq"
+      - Special keys (Enter, Space, etc.) and literal strings never trigger spacing
+  11. WHEN TO USE LITERAL PREFIX:
+      - Vim commands: [":", "literal:wq", "Enter"] instead of [":", "w", "q", "Enter"]
+      - Any sequence where exact character positioning matters
+      - When you need multiple characters sent as a single unit
+  12. Do NOT use terminal actions for file editing or writing. Use the replace_in_file,
+      write_to_file, or read_file tools instead.
+    </notes>
+    <examples>
+  # Create new terminal with Node.js (default terminal)
+  <function=terminal_action>
+  <parameter=action>new_terminal</parameter>
+  <parameter=inputs>["node", "Enter"]</parameter>
+  </function>
+
+  # Create a second (parallel) terminal instance for Python
+  <function=terminal_action>
+  <parameter=action>new_terminal</parameter>
+  <parameter=terminal_id>python_terminal</parameter>
+  <parameter=inputs>["python3", "Enter"]</parameter>
+  </function>
+
+  # Send command to the default terminal
+  <function=terminal_action>
+  <parameter=action>send_input</parameter>
+  <parameter=inputs>["require('crypto').randomBytes(1000000).toString('hex')",
+                     "Enter"]</parameter>
+  </function>
+
+  # Wait for previous action on default terminal
+  <function=terminal_action>
+  <parameter=action>wait</parameter>
+  <parameter=time>2.0</parameter>
+  </function>
+
+  # Send multiple inputs with special keys to current terminal
+  <function=terminal_action>
+  <parameter=action>send_input</parameter>
+  <parameter=inputs>["sqlmap -u 'http://example.com/page.php?id=1' --batch", "Enter", "y",
+               "Enter", "n", "Enter", "n", "Enter"]</parameter>
+  </function>
+
+  # WRONG: Vim command with automatic spacing (becomes ": w q")
+  <function=terminal_action>
+  <parameter=action>send_input</parameter>
+  <parameter=inputs>[":", "w", "q", "Enter"]</parameter>
+  </function>
+
+  # CORRECT: Vim command using literal prefix (becomes ":wq")
+  <function=terminal_action>
+  <parameter=action>send_input</parameter>
+  <parameter=inputs>[":", "literal:wq", "Enter"]</parameter>
+  </function>
+    </examples>
+  </tool>
+</tools>

strix/tools/terminal/terminal_instance.py

@@ -0,0 +1,231 @@
+import contextlib
+import os
+import pty
+import select
+import signal
+import subprocess
+import threading
+import time
+from typing import Any
+
+import pyte
+
+
+MAX_TERMINAL_SNAPSHOT_LENGTH = 10_000
+
+
+class TerminalInstance:
+    def __init__(self, terminal_id: str, initial_command: str | None = None) -> None:
+        self.terminal_id = terminal_id
+        self.process: subprocess.Popen[bytes] | None = None
+        self.master_fd: int | None = None
+        self.is_running = False
+        self._output_lock = threading.Lock()
+        self._reader_thread: threading.Thread | None = None
+
+        self.screen = pyte.HistoryScreen(80, 24, history=1000)
+        self.stream = pyte.ByteStream()
+        self.stream.attach(self.screen)
+
+        self._start_terminal(initial_command)
+
+    def _start_terminal(self, initial_command: str | None = None) -> None:
+        try:
+            self.master_fd, slave_fd = pty.openpty()
+
+            shell = "/bin/bash"
+
+            self.process = subprocess.Popen(  # noqa: S603
+                [shell, "-i"],
+                stdin=slave_fd,
+                stdout=slave_fd,
+                stderr=slave_fd,
+                cwd="/workspace",
+                preexec_fn=os.setsid,  # noqa: PLW1509 - Required for PTY functionality
+            )
+
+            os.close(slave_fd)
+
+            self.is_running = True
+
+            self._reader_thread = threading.Thread(target=self._read_output, daemon=True)
+            self._reader_thread.start()
+
+            time.sleep(0.5)
+
+            if initial_command:
+                self._write_to_terminal(initial_command)
+
+        except (OSError, ValueError) as e:
+            raise RuntimeError(f"Failed to start terminal: {e}") from e
+
+    def _read_output(self) -> None:
+        while self.is_running and self.master_fd:
+            try:
+                ready, _, _ = select.select([self.master_fd], [], [], 0.1)
+                if ready:
+                    data = os.read(self.master_fd, 4096)
+                    if data:
+                        with self._output_lock, contextlib.suppress(TypeError):
+                            self.stream.feed(data)
+                    else:
+                        break
+            except (OSError, ValueError):
+                break
+
+    def _write_to_terminal(self, data: str) -> None:
+        if self.master_fd and self.is_running:
+            try:
+                os.write(self.master_fd, data.encode("utf-8"))
+            except (OSError, ValueError) as e:
+                raise RuntimeError("Terminal is no longer available") from e
+
+    def send_input(self, inputs: list[str]) -> None:
+        if not self.is_running:
+            raise RuntimeError("Terminal is not running")
+
+        for i, input_item in enumerate(inputs):
+            if input_item.startswith("literal:"):
+                literal_text = input_item[8:]
+                self._write_to_terminal(literal_text)
+            else:
+                key_sequence = self._get_key_sequence(input_item)
+                if key_sequence:
+                    self._write_to_terminal(key_sequence)
+                else:
+                    self._write_to_terminal(input_item)
+
+            time.sleep(0.05)
+
+            if (
+                i < len(inputs) - 1
+                and not input_item.startswith("literal:")
+                and not self._is_special_key(input_item)
+                and not inputs[i + 1].startswith("literal:")
+                and not self._is_special_key(inputs[i + 1])
+            ):
+                self._write_to_terminal(" ")
+
+    def get_snapshot(self) -> dict[str, Any]:
+        with self._output_lock:
+            history_lines = [
+                "".join(char.data for char in line_dict.values())
+                for line_dict in self.screen.history.top
+            ]
+
+            current_lines = self.screen.display
+
+            all_lines = history_lines + current_lines
+            rendered_output = "\n".join(all_lines)
+
+            if len(rendered_output) > MAX_TERMINAL_SNAPSHOT_LENGTH:
+                rendered_output = rendered_output[-MAX_TERMINAL_SNAPSHOT_LENGTH:]
+                truncated = True
+            else:
+                truncated = False
+
+        return {
+            "terminal_id": self.terminal_id,
+            "snapshot": rendered_output,
+            "is_running": self.is_running,
+            "process_id": self.process.pid if self.process else None,
+            "truncated": truncated,
+        }
+
+    def wait(self, duration: float) -> dict[str, Any]:
+        time.sleep(duration)
+        return self.get_snapshot()
+
+    def close(self) -> None:
+        self.is_running = False
+
+        if self.process:
+            with contextlib.suppress(OSError, ProcessLookupError):
+                os.killpg(os.getpgid(self.process.pid), signal.SIGTERM)
+
+                try:
+                    self.process.wait(timeout=2)
+                except subprocess.TimeoutExpired:
+                    os.killpg(os.getpgid(self.process.pid), signal.SIGKILL)
+                    self.process.wait()
+
+        if self.master_fd:
+            with contextlib.suppress(OSError):
+                os.close(self.master_fd)
+            self.master_fd = None
+
+        if self._reader_thread and self._reader_thread.is_alive():
+            self._reader_thread.join(timeout=1)
+
+    def _is_special_key(self, key: str) -> bool:
+        special_keys = {
+            "Enter",
+            "Space",
+            "Backspace",
+            "Tab",
+            "Escape",
+            "Up",
+            "Down",
+            "Left",
+            "Right",
+            "Home",
+            "End",
+            "PageUp",
+            "PageDown",
+            "Insert",
+            "Delete",
+        } | {f"F{i}" for i in range(1, 13)}
+
+        if key in special_keys:
+            return True
+
+        return bool(key.startswith(("^", "C-", "S-", "A-")))
+
+    def _get_key_sequence(self, key: str) -> str | None:
+        key_map = {
+            "Enter": "\r",
+            "Space": " ",
+            "Backspace": "\x08",
+            "Tab": "\t",
+            "Escape": "\x1b",
+            "Up": "\x1b[A",
+            "Down": "\x1b[B",
+            "Right": "\x1b[C",
+            "Left": "\x1b[D",
+            "Home": "\x1b[H",
+            "End": "\x1b[F",
+            "PageUp": "\x1b[5~",
+            "PageDown": "\x1b[6~",
+            "Insert": "\x1b[2~",
+            "Delete": "\x1b[3~",
+            "F1": "\x1b[11~",
+            "F2": "\x1b[12~",
+            "F3": "\x1b[13~",
+            "F4": "\x1b[14~",
+            "F5": "\x1b[15~",
+            "F6": "\x1b[17~",
+            "F7": "\x1b[18~",
+            "F8": "\x1b[19~",
+            "F9": "\x1b[20~",
+            "F10": "\x1b[21~",
+            "F11": "\x1b[23~",
+            "F12": "\x1b[24~",
+        }
+
+        if key in key_map:
+            return key_map[key]
+
+        if key.startswith("^") and len(key) == 2:
+            char = key[1].lower()
+            return chr(ord(char) - ord("a") + 1) if "a" <= char <= "z" else None
+
+        if key.startswith("C-") and len(key) == 3:
+            char = key[2].lower()
+            return chr(ord(char) - ord("a") + 1) if "a" <= char <= "z" else None
+
+        return None
+
+    def is_alive(self) -> bool:
+        if not self.process:
+            return False
+        return self.process.poll() is None