fix(mastracode-web): validate setup commands and document their trust model

Address the security-scan finding on setupCommand execution: reject
control characters (except newline/tab) at the settings route so escape
sequences and NULs can't reach the sandbox shell or spoof logs, and
document why arbitrary shell is intentional — the command is only
configurable by authenticated org members and runs exclusively inside
the project's isolated sandbox, the same environment where org members
already run arbitrary shell through the agent.

Co-Authored-By: Mastra Code (anthropic/claude-fable-5) <noreply@mastra.ai>

Author: abhiaiyer91

mastracode/web/src/web/github/routes.test.ts

@@ -918,6 +918,22 @@ describe('project settings routes', () => {
     });
     expect(res.status).toBe(400);
   });
+
+  it('400s on a setup command containing control characters', async () => {
+    seedMaterializedProject();
+    const app = buildApp({ workosId: 'u1' });
+    const res = await postJson(app, '/web/github/projects/p1/settings', {
+      setupCommand: 'pnpm i \x1b[31m&& rm -rf /',
+    });
+    expect(res.status).toBe(400);
+    expect(tables.projects[0].setupCommand).toBeNull();
+
+    // Newlines and tabs are legitimate in multi-line setup scripts.
+    const res2 = await postJson(app, '/web/github/projects/p1/settings', {
+      setupCommand: 'pnpm i\npnpm build\t--force',
+    });
+    expect(res2.status).toBe(200);
+  });
 });
 
 describe('worktree route', () => {

mastracode/web/src/web/github/routes.ts

@@ -592,6 +592,12 @@ export function buildGithubRoutes(options: MountGithubRoutesOptions = {}): ApiRo
         if (typeof body.setupCommand === 'string' && body.setupCommand.length > 2000) {
           return c.json({ error: 'setupCommand too long (max 2000 characters)' }, 400);
         }
+        // Reject control characters (except newline/tab). The command is a
+        // shell script by design, but escape sequences and NULs have no
+        // legitimate use and can spoof logs or confuse the sandbox shell.
+        if (typeof body.setupCommand === 'string' && /[\0-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(body.setupCommand)) {
+          return c.json({ error: 'setupCommand contains control characters' }, 400);
+        }
         // An empty/whitespace command means "no setup step".
         const setupCommand =
           typeof body.setupCommand === 'string' && body.setupCommand.trim().length > 0

mastracode/web/src/web/github/sandbox.ts

@@ -845,6 +845,16 @@ export async function ensureWorktree(
  * run so the checkout is ready to build/test. A non-zero exit is a hard error —
  * starting agent work in a half-set-up tree is worse than failing the request.
  *
+ * Security model: the command is intentionally arbitrary shell — that is the
+ * feature (install deps, build, seed fixtures). It is only configurable by
+ * authenticated org members (the settings route is gated by
+ * `resolveOrgTenant` + org-scoped project lookup, with length and
+ * control-character validation), and it executes exclusively inside the
+ * project's isolated sandbox — the same environment where org members already
+ * run arbitrary shell via the agent's command tool. It never runs on the web
+ * server host, so it grants no privilege beyond what sandbox access already
+ * provides.
+ *
  * @param sandbox       live sandbox containing the worktree
  * @param worktreePath  the server-computed worktree path the command runs in
  * @param command       the org-configured setup shell command