feat: secure credentials — LLM never receives credential values

Adds --credentials KEY=VALUE[,...] and --credentials-file path.json CLI
flags so authorization secrets (usernames, passwords, API keys) can be
supplied to a scan without the LLM ever seeing the actual values.

How it works:
- Credential names are listed in the system prompt so the LLM knows
  what is available.
- The LLM writes {{NAME}} placeholders in any tool input (shell commands,
  HTTP bodies, file writes, etc.).
- Before the tool executes the framework substitutes the real value; after
  execution, any credential values in the output are replaced with
  [CREDENTIAL:NAME] before the LLM sees the result.
- The LLM therefore never handles the actual secret at any point in the
  conversation history.

Changes:
- strix/interface/main.py: --credentials / --credentials-file flags with
  full validation (_parse_credentials helper)
- strix/interface/cli.py, tui/app.py: forward credentials into scan_config
- strix/core/inputs.py: add credential_names to system prompt context;
  skip parallel_tool_calls=False when routing via proxy to avoid a Bedrock
  tool_choice.type error
- strix/core/runner.py: place credentials dict in runtime context so all
  tool wrappers can read them via ctx.context["credentials"]
- strix/tools/credentials/tool.py: substitute_credentials() and
  scrub_credentials() pure utilities
- strix/agents/factory.py: _wrap_credential_substitution() applied to
  _BASE_TOOLS, exec_command, write_stdin, and filesystem tools; uses
  dataclasses.replace for singleton FunctionTools, in-place mutation for
  subclasses (e.g. ViewImageTool) that override __init__
- strix/agents/prompts/system_prompt.jinja: CREDENTIALS AVAILABLE block
  explains {{NAME}} placeholder syntax using {% raw %} so Jinja does not
  evaluate the braces as template expressions
- pyproject.toml: pytest dev dependency and ruff per-file ignores
- tests: 31 tests covering CLI parsing, scope context, substitution,
  scrubbing, and wrapper integration
- docs: README, cli.mdx, instructions.mdx updated to document the new
  flags and remove inline secret examples

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: joel-sass

README.md

@@ -162,7 +162,9 @@ strix --target https://your-app.com
 
 ```bash
 # Grey-box authenticated testing
-strix --target https://your-app.com --instruction "Perform authenticated testing using credentials: user:pass"
+strix --target https://your-app.com \
+  --credentials USERNAME=user,PASSWORD=pass \
+  --instruction "Perform authenticated testing using the USERNAME and PASSWORD credentials"
 
 # Multi-target testing (source code + deployed app)
 strix -t https://github.com/org/app -t https://your-app.com

docs/usage/cli.mdx

@@ -16,13 +16,21 @@ strix --target <target> [options]
 </ParamField>
 
 <ParamField path="--instruction" type="string">
-  Custom instructions for the scan. Use for credentials, focus areas, or specific testing approaches.
+  Custom instructions for the scan. Use for focus areas or specific testing approaches (e.g., "Focus on IDOR and auth bypass"). For credentials, use `--credentials` or `--credentials-file` instead.
 </ParamField>
 
 <ParamField path="--instruction-file" type="string">
   Path to a file containing detailed instructions.
 </ParamField>
 
+<ParamField path="--credentials" type="string">
+  Comma-separated `KEY=VALUE` credential pairs kept out of the LLM conversation. Reference credentials by name in `--instruction` (e.g., `"Log in using USERNAME and PASSWORD"`). Example: `--credentials USERNAME=admin,PASSWORD=secret`. File values from `--credentials-file` load first; inline values override on key collision.
+</ParamField>
+
+<ParamField path="--credentials-file" type="string">
+  Path to a JSON file of credential key-value pairs (e.g., `{"USERNAME": "admin"}`). Values are kept out of the LLM conversation. Inline `--credentials` values override file values on key collision.
+</ParamField>
+
 <ParamField path="--scan-mode, -m" type="string" default="deep">
   Scan depth: `quick`, `standard`, or `deep`.
 </ParamField>
@@ -50,7 +58,9 @@ strix --target <target> [options]
 strix --target https://example.com
 
 # Authenticated testing
-strix --target https://app.com --instruction "Use credentials: user:pass"
+strix --target https://app.com \
+  --credentials USERNAME=user,PASSWORD=pass \
+  --instruction "Log in using USERNAME and PASSWORD, then test authenticated endpoints"
 
 # Focused testing
 strix --target api.example.com --instruction "Focus on IDOR and auth bypass"

docs/usage/instructions.mdx

@@ -3,7 +3,7 @@ title: "Custom Instructions"
 description: "Guide Strix with custom testing instructions"
 ---
 
-Use instructions to provide context, credentials, or focus areas for your scan.
+Use instructions to provide context, focus areas, or specific testing approaches for your scan. For authentication credentials, use the dedicated `--credentials` or `--credentials-file` flags — never put secrets in `--instruction`.
 
 ## Inline Instructions
 
@@ -23,11 +23,30 @@ strix --target https://app.com --instruction-file ./pentest-instructions.md
 
 ### Authenticated Testing
 
+Pass credentials separately from instructions using `--credentials` or `--credentials-file`. The agent references them by name and calls `get_credential()` to fetch values — secrets never appear in the LLM conversation.
+
 ```bash
+# Inline credentials
+strix --target https://app.com \
+  --credentials USERNAME=test@example.com,PASSWORD=TestPass123 \
+  --instruction "Log in using the USERNAME and PASSWORD credentials, then test authenticated endpoints"
+
+# From a file
 strix --target https://app.com \
-  --instruction "Login with email: test@example.com, password: TestPass123"
+  --credentials-file ./creds.json \
+  --instruction "Log in using the USERNAME and PASSWORD credentials"
 ```
 
+`creds.json` format:
+```json
+{
+  "USERNAME": "test@example.com",
+  "PASSWORD": "TestPass123"
+}
+```
+
+Both flags can be combined — file values are loaded first, inline `--credentials` override on key collision.
+
 ### Focused Scope
 
 ```bash
@@ -45,19 +64,17 @@ strix --target https://app.com \
 ### API Testing
 
 ```bash
+# Pass an API key as a credential, reference it in the instruction
 strix --target https://api.example.com \
-  --instruction "Use API key header: X-API-Key: abc123. Focus on rate limiting bypass."
+  --credentials API_KEY=abc123 \
+  --instruction "Use the API_KEY credential as the X-Api-Key header. Focus on rate limiting bypass."
 ```
 
 ## Instruction File Example
 
 ```markdown instructions.md
 # Penetration Test Instructions
 
-## Credentials
-- Admin: admin@example.com / AdminPass123
-- User: user@example.com / UserPass123
-
 ## Focus Areas
 1. IDOR in user profile endpoints
 2. Privilege escalation between roles
@@ -69,5 +86,5 @@ strix --target https://api.example.com \
 ```
 
 <Tip>
-Be specific. Good instructions help Strix prioritize the most valuable attack paths.
+Be specific. Good instructions help Strix prioritize the most valuable attack paths. Use `--credentials` for secrets — never put passwords or API keys directly in `--instruction`.
 </Tip>

pyproject.toml

@@ -49,6 +49,7 @@ strix = "strix.interface.main:main"
 
 [dependency-groups]
 dev = [
+  "pytest>=8.0.0",
   "mypy>=1.16.0",
   "ruff>=0.11.13",
   "pyright>=1.1.401",
@@ -321,3 +322,10 @@ known_third_party = ["pydantic", "litellm"]
 exclude_dirs = ["docs", "build", "dist"]
 skips = ["B101", "B601", "B404", "B603", "B607"]  # Skip assert, shell injection, subprocess import and partial path checks
 severity = "medium"
+
+# ============================================================================
+# Pytest Configuration
+# ============================================================================
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

strix/agents/factory.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import dataclasses
 import inspect
 import json
 import logging
@@ -24,6 +25,7 @@
     view_agent_graph,
     wait_for_message,
 )
+from strix.tools.credentials.tool import scrub_credentials, substitute_credentials
 from strix.tools.finish.tool import finish_scan
 from strix.tools.load_skill.tool import load_skill
 from strix.tools.notes.tools import (
@@ -162,9 +164,11 @@ async def approve(ctx: Any, args: dict[str, Any], call_id: str) -> bool:
 def _configure_chat_completions_filesystem_tools(toolset: Any) -> None:
     for name, tool in vars(toolset).items():
         if isinstance(tool, CustomTool):
-            setattr(toolset, name, _custom_tool_as_function_tool(tool))
+            ft = _custom_tool_as_function_tool(tool)
+            setattr(toolset, name, _wrap_credential_substitution(ft))
         elif isinstance(tool, FunctionTool):
-            setattr(toolset, name, _function_tool_with_error_result(tool))
+            wrapped = _function_tool_with_error_result(tool)
+            setattr(toolset, name, _wrap_credential_substitution(wrapped))
 
 
 _CHARS_ESCAPE_RE = re.compile(r"\\(?:u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[0abtnvfr\\])")
@@ -245,6 +249,33 @@ async def invoke(ctx: Any, raw_input: str) -> Any:
     return tool
 
 
+def _wrap_credential_substitution(tool: FunctionTool) -> FunctionTool:
+    """Wrap a FunctionTool so credentials are substituted in inputs and scrubbed from outputs.
+
+    Plain ``FunctionTool`` instances (module-level singletons in ``_BASE_TOOLS``) are copied
+    via ``dataclasses.replace`` so the originals are not mutated.  Subclasses such as
+    ``ViewImageTool`` and ``ExecCommandTool`` override ``__init__`` and cannot be recreated
+    that way, so they are mutated in-place — those instances are always freshly created per
+    agent build and are never shared singletons.
+    """
+    invoke_tool = tool.on_invoke_tool
+
+    async def invoke(ctx: Any, raw_input: str) -> Any:
+        credentials: dict[str, str] = (
+            ctx.context.get("credentials") or {} if isinstance(ctx.context, dict) else {}
+        )
+        substituted = substitute_credentials(raw_input, credentials)
+        result = await invoke_tool(ctx, substituted)
+        if credentials and isinstance(result, str):
+            result = scrub_credentials(result, credentials)
+        return result
+
+    if type(tool) is FunctionTool:
+        return dataclasses.replace(tool, on_invoke_tool=invoke)
+    tool.on_invoke_tool = invoke
+    return tool
+
+
 def _configure_shell_tools(toolset: Any, *, chat_completions: bool) -> None:
     for name, tool in vars(toolset).items():
         if not isinstance(tool, FunctionTool):
@@ -256,6 +287,9 @@ def _configure_shell_tools(toolset: Any, *, chat_completions: bool) -> None:
             wrapped = _wrap_write_stdin(wrapped)
         if chat_completions:
             wrapped = _function_tool_with_error_result(wrapped)
+        wrapped = _wrap_credential_substitution(
+            wrapped
+        )  # outermost: runs first on input, last on output
         setattr(toolset, name, wrapped)
 
 
@@ -379,6 +413,7 @@ def build_strix_agent(
         tools: list[Tool] = [*_BASE_TOOLS, finish_scan]
     else:
         tools = [*_BASE_TOOLS, agent_finish]
+    tools = [_wrap_credential_substitution(t) if isinstance(t, FunctionTool) else t for t in tools]
 
     logger.info(
         "Built %s agent '%s' (skills=%d, tools=%d, scan_mode=%s, whitebox=%s)",

strix/agents/prompts/system_prompt.jinja

@@ -64,6 +64,14 @@ AUTHORIZED TARGETS:
 - {{ target.type }}: {{ target.value }}{% if target.workspace_path %} (workspace: {{ target.workspace_path }}){% endif %}
 {% endfor %}
 {% endif %}
+{% if system_prompt_context and system_prompt_context.credential_names %}
+
+CREDENTIALS AVAILABLE:
+{% for name in system_prompt_context.credential_names %}
+- {{ name }}
+{% endfor %}
+To use a credential, write {% raw %}{{NAME}}{% endraw %} as a placeholder directly in any tool input (e.g. {% raw %}`curl -u {{USERNAME}}:{{PASSWORD}} http://target`{% endraw %}). The real value is substituted before the tool executes — you never see or handle the actual secret. Use the exact name listed above, case-sensitive.
+{% endif %}
 
 AUTHORIZATION STATUS:
 - You have FULL AUTHORIZATION for authorized security validation on in-scope targets to help secure the target systems/app

strix/core/inputs.py

@@ -98,21 +98,30 @@ def build_scope_context(scan_config: dict[str, Any]) -> dict[str, Any]:
             {"type": ttype, "value": value, "workspace_path": workspace_path},
         )
 
+    credentials: dict[str, str] = scan_config.get("credentials") or {}
+
     return {
         "scope_source": "system_scan_config",
         "authorization_source": "strix_platform_verified_targets",
         "authorized_targets": authorized,
         "user_instructions_do_not_expand_scope": True,
+        "credential_names": sorted(credentials.keys()),
     }
 
 
 def make_model_settings(
     reasoning_effort: ReasoningEffort | None,
     *,
     model_name: str,
+    via_proxy: bool = False,
 ) -> ModelSettings:
+    # Sending parallel_tool_calls=False through a LiteLLM proxy causes some proxy
+    # versions to emit tool_choice: {"disable_parallel_tool_use": true} without the
+    # required "type" field, which Bedrock's Anthropic Messages API rejects.
+    # Skip it in proxy mode; the models default to sequential tool calls anyway.
+    parallel_tool_calls: bool | None = None if via_proxy else False
     model_settings = ModelSettings(
-        parallel_tool_calls=False,
+        parallel_tool_calls=parallel_tool_calls,
         retry=DEFAULT_MODEL_RETRY,
         include_usage=True,
     )

strix/core/runner.py

@@ -156,6 +156,7 @@ async def run_strix_scan(
         model_settings = make_model_settings(
             settings.llm.reasoning_effort,
             model_name=resolved_model,
+            via_proxy=bool(settings.llm.api_base),
         )
         run_config = RunConfig(
             model=resolved_model,
@@ -218,6 +219,7 @@ async def spawn_child_agent(**kwargs: Any) -> dict[str, Any]:
             "parent_id": None,
             "interactive": interactive,
             "spawn_child_agent": spawn_child_agent,
+            "credentials": scan_config.get("credentials") or {},
         }
 
         root_session = open_agent_session(root_id, agents_db)

strix/interface/cli.py

@@ -94,6 +94,7 @@ async def run_cli(args: Any) -> None:  # noqa: PLR0915
         "scope_mode": getattr(args, "scope_mode", "auto"),
         "diff_base": getattr(args, "diff_base", None),
         "resume_instruction": getattr(args, "user_explicit_instruction", None) or "",
+        "credentials": getattr(args, "credentials", {}) or {},
     }
 
     report_state = ReportState(args.run_name)