Description

The new bootstrap flow prepends a user prompt prefix that instructs the model to read and follow BOOTSTRAP.md from the workspace before replying normally.

Because BOOTSTRAP.md is a user-controlled workspace file (e.g., can be committed in a repo or otherwise placed in the working directory), this creates a prompt-injection vector where an attacker can influence the agent’s behavior (including tool usage) via file content.

Key concerns grounded in the code change:

• The runtime explicitly tells the agent to read and follow BOOTSTRAP.md (no allowlist/sanitization of instructions).
• BOOTSTRAP.md is removed from injected context (shouldStripBootstrapFromEmbeddedContext() always returns true), making the model more likely to comply by using file tools (read) to fetch and follow the file.
• There are no visible guardrails here ensuring that instructions inside BOOTSTRAP.md cannot:
  • override higher-level safety guidance in practice (LLMs can be socially engineered),
  • coerce exfiltration of sensitive workspace contents via normal chat output,
  • coerce risky tool actions (e.g., exec, edits) under the guise of “bootstrap”.

Vulnerable code (user-visible prompt coercion):

if (userPromptPrefixText) {
  effectivePrompt = `${userPromptPrefixText}\n\n${effectivePrompt}`;
}

And the prefix itself instructs following the file:

"Please read BOOTSTRAP.md from the workspace and follow it before replying normally."

This is a classic prompt injection via untrusted content pattern.

Recommendation

Treat BOOTSTRAP.md as untrusted input and add explicit, enforceable guardrails around bootstrap instruction handling.

Concrete improvements:

1. Add a system-level non-overridable rule: instructions from workspace files (including BOOTSTRAP.md) must not request secrets/exfiltration, credential entry, or unsafe tool actions without explicit user confirmation.

2. Constrain bootstrap to an allowlisted workflow rather than “follow arbitrary instructions”. For example, only allow:

• reading a fixed set of files,
• running a fixed set of safe commands,
• editing/deleting BOOTSTRAP.md after completion.

3. Require explicit confirmation before executing dangerous tools during bootstrap (especially exec, network tools, sending messages). Example pattern:

​// Pseudocode: before executing exec/network tools during bootstrap
if (bootstrapMode !== "none" && toolIsDangerous(toolName)) {
  throw new Error("Bootstrap cannot run dangerous tools without explicit user confirmation.");
}

4. Consider keeping bootstrap instructions in the system prompt as constraints (e.g., "bootstrap may request steps but must not override safety"), while treating file content purely as suggestions/tasks that are validated.

Description

The code determines whether the current run is operating in the canonical workspace by doing a direct string comparison between two path strings:

• resolvedWorkspace comes from resolveRunWorkspaceDir(...) (which uses resolveUserPath(...) only)
• canonicalWorkspace is computed from resolveAgentWorkspaceDir(...) and resolveUserPath(...)
• isCanonicalWorkspace is then canonicalWorkspace === resolvedWorkspace

Because neither side is normalized via realpath (and no consistent normalization/case-folding is applied), two paths that refer to the same directory (e.g., via symlinks, bind mounts, or platform-specific aliases like /tmp vs /private/tmp) can compare as unequal.

This value is then used to compute bootstrapMode:

• When isCanonicalWorkspace is false (or when effectiveWorkspace !== resolvedWorkspace), resolveBootstrapMode(...) returns "limited" instead of "full" (or "none" in other cases).
• A downgraded bootstrapMode changes bootstrap behavior, potentially suppressing or weakening expected bootstrap handling for a workspace that is actually canonical.

Vulnerable code (new behavior):

const canonicalWorkspace = resolveUserPath(
  resolveAgentWorkspaceDir(params.config ?? {}, workspaceResolution.agentId),
);
const isCanonicalWorkspace = canonicalWorkspace === resolvedWorkspace;

And later:

isCanonicalWorkspace:
  (params.isCanonicalWorkspace ?? true) && effectiveWorkspace === resolvedWorkspace,

If an untrusted caller can influence workspaceDir (including supplying a symlinked path to the canonical workspace), they can cause bootstrap mode to be incorrectly downgraded.

Recommendation

Normalize both paths using the same canonicalization routine before comparison.

At minimum:

• path.resolve(...) both paths
• and prefer fs.realpathSync.native(...) (best-effort) to collapse symlinks/platform aliases
• apply Windows case normalization consistently

Example fix:

import fs from "node:fs";
import path from "node:path";

function normalizePathForEquality(p: string): string {
  const resolved = path.resolve(p);
  try {
    return fs.realpathSync.native(resolved);
  } catch {
    return resolved;
  }
}

const canonicalWorkspace = normalizePathForEquality(
  resolveUserPath(resolveAgentWorkspaceDir(params.config ?? {}, workspaceResolution.agentId)),
);
const resolvedWorkspace = normalizePathForEquality(workspaceResolution.workspaceDir);
const isCanonicalWorkspace = canonicalWorkspace === resolvedWorkspace;

Also consider using this same normalization when comparing effectiveWorkspace === resolvedWorkspace in runEmbeddedAttempt, to avoid further downgrade due to aliasing.

Description

resolveWorkspaceBootstrapStatus() trusts setupCompletedAt loaded from a JSON file stored inside the workspace (<workspace>/.openclaw/workspace-state.json). If an untrusted project can place or modify this file (e.g., committed into a repo or written by other tooling), it can force the workspace bootstrap status to complete even when BOOTSTRAP.md is still present.

Impact:

• Bootstrap-pending behavior (e.g., forcing the agent to read/follow BOOTSTRAP.md first, warnings, and any related safety initialization logic) can be skipped.
• This creates an inconsistent “truth source”: existence of BOOTSTRAP.md is ignored when setupCompletedAt is set.

Vulnerable code:

const state = await readWorkspaceSetupStateForDir(resolvedDir);
if (typeof state.setupCompletedAt === "string" && state.setupCompletedAt.trim().length > 0) {
  return "complete";
}
const bootstrapExists = await fileExists(path.join(resolvedDir, DEFAULT_BOOTSTRAP_FILENAME));
return bootstrapExists ? "pending" : "complete";

Because workspace-state.json resides under the workspace root, it may be under attacker influence in common workflows (cloning/opening a repository, copying a template workspace, etc.).

Recommendation

Treat BOOTSTRAP.md presence as authoritative for “pending”, or move bootstrap completion state to a trusted location outside the workspace.

Option A (simple logic fix): if BOOTSTRAP.md exists, report pending regardless of setupCompletedAt.

export async function resolveWorkspaceBootstrapStatus(dir: string): Promise<"pending"|"complete"> {
  const resolvedDir = resolveUserPath(dir);
  const bootstrapExists = await fileExists(path.join(resolvedDir, DEFAULT_BOOTSTRAP_FILENAME));
  if (bootstrapExists) return "pending";

  const state = await readWorkspaceSetupStateForDir(resolvedDir);
  const completed = typeof state.setupCompletedAt === "string" && state.setupCompletedAt.trim().length > 0;
  return completed ? "complete" : "complete"; // or keep additional states if needed
}

(If you need the timestamp, still read it, but do not let it override BOOTSTRAP.md presence.)

Option B (trust boundary fix): store workspace-state.json in a per-user config directory (e.g., ~/.openclaw/state/<workspace-id>.json) not inside the repository/workspace; or validate it (ownership, permissions, not tracked by git) before trusting it for security-relevant decisions.

Description

resolveBareSessionResetPromptState() now calls isWorkspaceBootstrapPending(workspaceDir), which ultimately checks for the presence of BOOTSTRAP.md under the provided workspaceDir.

The workspaceDir passed into this flow can be derived from sessionEntry.spawnedWorkspaceDir (via resolveIngressWorkspaceOverrideForSpawnedRun(...)) in src/gateway/server-methods/agent.ts. spawnedWorkspaceDir is user-controllable through the sessions patch API (no path validation), which means an untrusted client can supply an arbitrary filesystem path.

As a result:

• The server will attempt to read ${workspaceDir}/.openclaw/workspace-state.json and will fs.access() ${workspaceDir}/BOOTSTRAP.md.
• This creates an existence oracle / arbitrary path probing primitive (and can also cause unexpected reads of JSON state files outside the intended workspace root if present).
• resolveUserPath() only expands home-relative paths; it does not confine paths to a safe workspace root or defend against .., absolute paths, Windows drive letters/UNC paths, or symlink escapes.

Vulnerable code:

const resolvedDir = resolveUserPath(dir);
const state = await readWorkspaceSetupStateForDir(resolvedDir);
const bootstrapExists = await fileExists(path.join(resolvedDir, DEFAULT_BOOTSTRAP_FILENAME));

Recommendation

Constrain workspaceDir to an allowlisted root and reject/normalize unsafe paths before any filesystem access.

Options:

1. Validate at the ingestion point (preferred): when accepting spawnedWorkspaceDir via sessions patch (or when deriving workspaceOverride), only allow workspace directories that are:

   • within the configured agent workspace root
   • non-empty, normalized, and absolute after resolution
   • not containing path traversal (..) after normalization
   • not a symlink escape (use realpath and verify it remains under the allowed root)

2. Defensive validation in resolveWorkspaceBootstrapStatus as a backstop.

Example approach:

import path from "node:path";
import fs from "node:fs/promises";

async function resolveWorkspaceDirSafe(input: string, allowedRoot: string): Promise<string> {
  const candidate = path.resolve(input);            // handles ..
  const realCandidate = await fs.realpath(candidate); // resolves symlinks
  const realRoot = await fs.realpath(allowedRoot);
  if (!realCandidate.startsWith(realRoot + path.sep)) {
    throw new Error("workspaceDir outside allowed root");
  }
  return realCandidate;
}

Additionally, consider removing spawnedWorkspaceDir from the public patch surface (or only allow it to be set by trusted internal components).