@murk-security/cli 0.3.2 → 0.5.0

package/README.md

@@ -0,0 +1,93 @@
+# @murk-security/cli
+
+Run [MURK](https://murk.sh)'s MCP server for your AI agent, and scan your
+locally-running apps with MURK's **hosted** runner over a secure **outbound** tunnel.
+
+- **No local runner, no model key** — scanning happens on MURK's infrastructure.
+- **Nothing inbound** to your network. You choose exactly which `localhost` URLs are
+  exposed; this process forwards **only** those, **read-only** (GET/HEAD), and refuses
+  everything else. The allowlist is enforced on your machine — it's the trust boundary.
+
+## Install
+
+```sh
+npm i -g @murk-security/cli
+# or run without installing:
+npx @murk-security/cli --help
+```
+
+Requires Node ≥ 20.
+
+## Quickstart
+
+```sh
+murk login                              # browser sign-in; authorizes this machine
+murk add murk-security/northwind-store  # add an app from a connected GitHub repo
+murk apps                               # list your applications + ids
+murk scan http://localhost:3000         # scan a locally-running app (full depth)
+```
+
+## Use it from an AI agent (MCP)
+
+**Hosted** (recommended) — no local process to keep running:
+
+```sh
+claude mcp add --transport http murk https://api.murk.sh/mcp
+```
+
+**Local** — also bridges any `--expose`'d local apps so the hosted runner can reach them:
+
+```sh
+murk mcp --expose http://localhost:3000
+```
+
+Either way the agent gets these tools:
+
+| Tool | What it does |
+| --- | --- |
+| `murk_list_applications` | List your apps (targets). |
+| `murk_add_application` | Add an app from a connected GitHub repo. |
+| `murk_scan` | Start a scan. Accepts an app **id or name**; `scanProfile: pr\|full`. |
+| `murk_retest` | Re-verify known findings; fixed ones are closed. |
+| `murk_create_patch` | Generate a code patch for a finding and open a PR. |
+| `murk_list_findings` | List findings, filtered by app / status / severity. |
+| `murk_get_finding` | One finding, with its reproduction recipe and any patch. |
+| `murk_get_run` | A run and its findings — poll this for scan progress. |
+
+Scans and patches run **asynchronously** — the start tools return a run id; poll
+`murk_get_run` / `murk_get_finding` for results.
+
+## Commands
+
+```
+murk login                                      browser sign-in; authorizes this machine
+murk logout                                     revoke this machine's credential
+murk whoami                                     show login status
+murk apps                                       list your applications (id, name, source)
+murk add <owner/repo> [--name NAME]             add an app from a connected GitHub repo
+murk scan <http://localhost:PORT> [--pr|--full] one-shot: connect, scan, disconnect
+murk mcp [--expose <http://localhost:PORT> ...] run the MCP server for your agent
+murk connect --expose <http://localhost:PORT>   open the tunnel only (no MCP)
+```
+
+### Scan depth
+
+- `--full` — deep whole-repo audit with the model council (~45 min). **Default.**
+- `--pr` — fast, cheaper scan, no council (~10 min).
+
+## GitHub apps
+
+`murk add owner/repo` requires the **MURK GitHub App** to be installed on that repository
+(and granted access). Connect it from the MURK dashboard, then the repo becomes available
+to `murk add` and `murk_add_application`.
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MURK_API_URL` | `https://api.murk.sh` | API origin (set to `http://localhost:8788` for dev). |
+| `MURK_DASHBOARD_URL` | `https://app.murk.sh` | Dashboard origin for login. |
+| `MURK_API_TOKEN` | — | Org API token (`murk_…`) for CI; overrides the stored login. |
+| `MURK_NO_BROWSER` | — | Set to print the login URL instead of opening a browser (headless/SSH). |
+
+The login credential is stored at `~/.murk/credentials.json` (mode `600`).

package/mcp-server.mjs

@@ -14,22 +14,71 @@ import { z } from 'zod';
 const ok = (data) => ({
   content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
 });
-const fail = (error) => ({
-  content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
-  isError: true,
-});
+const fail = (error) => {
+  // Free-pentest gate (402): give the agent a clear, actionable message + link so
+  // it tells the user to subscribe rather than reporting a generic error.
+  if (error && error.upgrade) {
+    const url = error.upgradeUrl || 'the MURK billing page in the dashboard';
+    return {
+      content: [{
+        type: 'text',
+        text: `This MURK organization has used its one free pentest. To run more pentests the user needs to subscribe. Tell the user to open ${url} and choose a plan, then retry.`,
+      }],
+      isError: true,
+    };
+  }
+  return {
+    content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+    isError: true,
+  };
+};
+
+/** Resolve an application by id, or by exact name (case-insensitive), or a unique name
+ * substring — so callers can pass a friendly name instead of an opaque id. Exported so the
+ * CLI and the MCP tools share one resolution rule. Throws a clear, actionable error. */
+export async function resolveApplication(api, idOrName) {
+  const want = String(idOrName ?? '').trim();
+  if (!want) throw new Error('no application id or name given');
+  const apps = await api('GET', '/api/applications');
+  const list = Array.isArray(apps) ? apps : (apps.applications ?? []);
+  let app = list.find((a) => a.id === want)
+    || list.find((a) => String(a.name).toLowerCase() === want.toLowerCase());
+  if (!app) {
+    const matches = list.filter((a) => String(a.name).toLowerCase().includes(want.toLowerCase()));
+    if (matches.length === 1) [app] = matches;
+    else if (matches.length > 1) {
+      throw new Error(`"${idOrName}" matches ${matches.length} applications (${matches.map((m) => m.name).join(', ')}); use the exact name or id.`);
+    }
+  }
+  if (!app) throw new Error(`no application matches "${idOrName}". List them with murk_list_applications (or \`murk apps\`).`);
+  return app;
+}
+
+/** Add an application from a connected GitHub repo (owner/name, grey-box source form).
+ * Exported so the CLI's `murk add` and the MCP `murk_add_application` tool share one path. */
+export async function addGithubApplication(api, { githubRepo, name }) {
+  const want = String(githubRepo).trim().toLowerCase();
+  const conns = await api('GET', '/api/connections');
+  const active = (Array.isArray(conns) ? conns : conns.connections ?? []).filter((c) => c.status === 'active');
+  let match;
+  for (const c of active) {
+    const repos = await api('GET', `/api/connections/${encodeURIComponent(c.id)}/repositories`).catch(() => []);
+    const r = (Array.isArray(repos) ? repos : repos.repositories ?? []).find((x) => String(x.fullName).toLowerCase() === want);
+    if (r) { match = { connectionId: c.id, repositoryId: r.id, fullName: r.fullName }; break; }
+  }
+  if (!match) throw new Error(`No connected GitHub repository matches "${githubRepo}". Install the MURK GitHub app on that repo (and grant it access), then retry.`);
+  const asset = await api('POST', '/api/assets/github', { connectionId: match.connectionId, repositoryId: match.repositoryId });
+  return api('POST', '/api/applications', {
+    name: name || match.fullName, description: '', context: '',
+    sourceAssetId: asset.id, environments: [], identities: [],
+  });
+}
 
 /** Build the MURK MCP server with all tools, backed by the given authenticated `api`. */
 export function buildMurkMcpServer(api, opts = {}) {
   const RUNNER_MODE = opts.runnerMode ?? 'basic-harness';
 
-  async function getApplication(applicationId) {
-    const apps = await api('GET', '/api/applications');
-    const list = Array.isArray(apps) ? apps : (apps.applications ?? []);
-    const app = list.find((a) => a.id === applicationId);
-    if (!app) throw new Error(`application ${applicationId} not found`);
-    return app;
-  }
+  const getApplication = (idOrName) => resolveApplication(api, idOrName);
 
   // Create -> preflight -> launch an assessment of the given kind (the flow the dashboard
   // uses), returning the started run.
@@ -47,6 +96,7 @@ export function buildMurkMcpServer(api, opts = {}) {
       policy: { profile: 'standard', destructiveActions: false, maxConcurrency: 2, maxDurationMinutes: 20 },
       packs: ['surface', 'sast', 'intel', 'scan', 'authz'],
       kind: o.kind,
+      ...(o.scanProfile ? { scanProfile: o.scanProfile } : {}),
       ...(o.remediateFindingId ? { remediateFindingId: o.remediateFindingId } : {}),
     };
     const created = await api('POST', '/api/assessments', config);
@@ -68,11 +118,23 @@ export function buildMurkMcpServer(api, opts = {}) {
     },
   );
 
+  server.registerTool(
+    'murk_add_application',
+    {
+      title: 'Add an application',
+      description: 'Add an application from a connected GitHub repository (source-only, grey-box — the form factor for PR scans and patches). The MURK GitHub App must already be installed on the repo. Returns the created application.',
+      inputSchema: { githubRepo: z.string().describe('owner/name, e.g. murk-security/northwind-store'), name: z.string().optional() },
+    },
+    async ({ githubRepo, name }) => {
+      try { return ok(await addGithubApplication(api, { githubRepo, name })); } catch (e) { return fail(e); }
+    },
+  );
+
   server.registerTool(
     'murk_list_findings',
     {
       title: 'List findings',
-      description: 'List findings, optionally filtered by application, status (open/fixed/regressed/accepted) or severity.',
+      description: 'List findings, optionally filtered by application, status (open/in_progress/ready_for_retest/fixed/regressed/accepted) or severity.',
       inputSchema: { applicationId: z.string().optional(), status: z.string().optional(), severity: z.string().optional() },
     },
     async ({ applicationId, status, severity }) => {
@@ -120,15 +182,32 @@ export function buildMurkMcpServer(api, opts = {}) {
 
   server.registerTool(
     'murk_scan',
-    { title: 'Scan an application', description: 'Start a security assessment of an application (public or locally-connected). Returns the started run.', inputSchema: { applicationId: z.string() } },
-    async ({ applicationId }) => {
-      try { return ok(await launchAssessment(await getApplication(applicationId), { kind: 'assess', name: 'Scan (via MCP)' })); } catch (e) { return fail(e); }
+    {
+      title: 'Scan an application',
+      description: 'Start a security assessment of an application (public or locally-connected). Returns the started run; the scan runs asynchronously — poll murk_get_run with the returned run id for status and findings.',
+      inputSchema: {
+        applicationId: z.string().describe('Application id OR name (e.g. "northwind-store"); names are resolved for you.'),
+        scanProfile: z.enum(['pr', 'full']).optional().describe(
+          "Scan depth. 'full' (default): deep whole-repo audit with the model council (~45 min). " +
+          "'pr': fast, cheaper scan with no council (~10 min) — scoped to a pull-request diff when one " +
+          'is available, otherwise a light whole-repo pass.',
+        ),
+      },
+    },
+    async ({ applicationId, scanProfile }) => {
+      try {
+        return ok(await launchAssessment(await getApplication(applicationId), {
+          kind: 'assess',
+          name: `Scan (via MCP${scanProfile ? `, ${scanProfile}` : ''})`,
+          scanProfile,
+        }));
+      } catch (e) { return fail(e); }
     },
   );
 
   server.registerTool(
     'murk_retest',
-    { title: 'Retest findings', description: 'Re-verify an application’s known findings; findings that no longer reproduce are marked fixed.', inputSchema: { applicationId: z.string() } },
+    { title: 'Retest findings', description: 'Re-verify an application’s known findings; findings that no longer reproduce are marked fixed.', inputSchema: { applicationId: z.string().describe('Application id OR name.') } },
     async ({ applicationId }) => {
       try { return ok(await launchAssessment(await getApplication(applicationId), { kind: 'retest', name: 'Retest (via MCP)' })); } catch (e) { return fail(e); }
     },
@@ -136,7 +215,7 @@ export function buildMurkMcpServer(api, opts = {}) {
 
   server.registerTool(
     'murk_create_patch',
-    { title: 'Create a patch', description: 'Generate a code patch for one finding (requires a connected source repo) and open a PR.', inputSchema: { findingId: z.string(), applicationId: z.string() } },
+    { title: 'Create a patch', description: 'Generate a code patch for one finding (requires a connected source repo) and open a PR. The patch is generated asynchronously — poll murk_get_finding to see the diff and PR link when ready.', inputSchema: { findingId: z.string(), applicationId: z.string().describe('Application id OR name.') } },
     async ({ findingId, applicationId }) => {
       try {
         return ok(await launchAssessment(await getApplication(applicationId), { kind: 'remediate', name: 'Patch (via MCP)', remediateFindingId: findingId }));

package/murk.mjs

@@ -6,8 +6,12 @@
  * those, read-only, and refuses everything else.
  *
  *   murk login                                       # browser sign-in; authorizes this machine
+ *   murk logout                                      # revoke this machine's credential
+ *   murk whoami                                      # show login status
+ *   murk apps                                        # list your applications
+ *   murk add owner/repo [--name NAME]                # add an app from a connected GitHub repo
  *   murk mcp --expose http://localhost:3000          # MCP server for your agent + tunnel
- *   murk scan http://localhost:3000                  # one-shot: connect, scan, disconnect
+ *   murk scan http://localhost:3000 [--pr|--full]    # one-shot: connect, scan, disconnect
  *   murk connect --expose http://localhost:3000      # tunnel only (no MCP)
  *
  * Env:
@@ -21,7 +25,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 // Default to the hosted MURK service; devs point these at a local control-plane/dashboard.
@@ -79,10 +83,36 @@ async function api(method, path, body) {
   });
   const text = await res.text();
   let data; try { data = text ? JSON.parse(text) : {}; } catch { data = { raw: text }; }
-  if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+  if (!res.ok) {
+    const err = new Error(data.error ?? `HTTP ${res.status}`);
+    err.status = res.status;
+    err.upgrade = Boolean(data.upgrade);     // free-pentest gate (402)
+    err.upgradeUrl = data.upgradeUrl;
+    throw err;
+  }
   return data;
 }
 
+/** Free-tier gate, surfaced early and clearly. Returns before scanning when the
+ * org has spent its free pentest; notes the free run on the first scan. Billing
+ * being off (self-host) or unreachable never blocks a scan — the launch stays
+ * the authoritative gate. */
+async function ensureCanLaunch() {
+  let s;
+  try { s = await api('GET', '/api/billing/status'); }
+  catch (e) { if (e.status === 503 || e.status === 409) return; throw e; }
+  const ent = s.entitlement;
+  if (!ent || !ent.gated) return;
+  if (!ent.canLaunch) {
+    log('you’ve used your free pentest. Subscribe to run more:');
+    log(`  ${s.billingUrl || API_URL}`);
+    process.exit(2);
+  }
+  if (!ent.subscribed && !ent.freePentestUsed) {
+    log(`free trial: this is your 1 free pentest (up to ${ent.freeMaxMinutes} min). Subscribe any time for unlimited: ${s.billingUrl || ''}`.trimEnd());
+  }
+}
+
 /** Open the tunnel for a set of exposed origins. `onReady(url, appId)` fires as each target
  * is registered server-side. The scope allowlist is enforced HERE — this process is the
  * trust boundary on the customer side. */
@@ -145,7 +175,7 @@ async function cmdConnect(exposed) {
   process.on('SIGTERM', stop);
 }
 
-async function launchScan(applicationId) {
+async function launchScan(applicationId, scanProfile) {
   const apps = await api('GET', '/api/applications');
   const list = Array.isArray(apps) ? apps : (apps.applications ?? []);
   const app = list.find((a) => a.id === applicationId);
@@ -156,6 +186,7 @@ async function launchScan(applicationId) {
     target: { environmentAssetIds: assetIds }, scope: {}, identities: app.identities ?? [],
     policy: { profile: 'standard', destructiveActions: false, maxConcurrency: 1, maxDurationMinutes: 15 },
     packs: ['surface', 'sast', 'intel', 'scan', 'authz'], kind: 'assess',
+    ...(scanProfile ? { scanProfile } : {}),
   };
   const created = await api('POST', '/api/assessments', config);
   const pre = await api('POST', `/api/assessments/${created.id}/preflight`, { runnerMode: 'basic-harness' });
@@ -164,15 +195,16 @@ async function launchScan(applicationId) {
   return run.runId ?? run.id ?? run.run?.id;
 }
 
-async function cmdScan(url) {
+async function cmdScan(url, scanProfile) {
   await ensureAuth();
   preflightChecks([url]);
+  await ensureCanLaunch(); // fail fast + note the free trial before opening the tunnel
   let done = false;
   const ws = openTunnel([url], {
     onReady: async (_u, applicationId) => {
       try {
-        log('starting hosted scan ...');
-        const runId = await launchScan(applicationId);
+        log(`starting hosted ${scanProfile === 'pr' ? 'PR (fast)' : 'full'} scan ...`);
+        const runId = await launchScan(applicationId, scanProfile);
         log(`run ${runId} started; watching ...`);
         for (;;) {
           await new Promise((r) => setTimeout(r, 4000));
@@ -183,7 +215,14 @@ async function cmdScan(url) {
             break;
           }
         }
-      } catch (e) { log(`scan failed: ${e instanceof Error ? e.message : e}`); }
+      } catch (e) {
+        if (e && e.upgrade) {
+          log('you’ve used your free pentest. Subscribe to run more:');
+          log(`  ${e.upgradeUrl || API_URL}`);
+        } else {
+          log(`scan failed: ${e instanceof Error ? e.message : e}`);
+        }
+      }
       finally { done = true; try { ws.close(); } catch { /* noop */ } process.exit(0); }
     },
     onClose: () => { if (!done) die('tunnel closed before the scan finished.'); },
@@ -280,6 +319,73 @@ async function ensureAuth() {
   await cmdLogin();
 }
 
+// Revoke the stored credential server-side and remove it locally. Env-provided tokens
+// (MURK_API_TOKEN, for CI) are left alone — unset the variable to "log out" of those.
+async function cmdLogout() {
+  if (process.env.MURK_API_TOKEN) {
+    log('MURK_API_TOKEN is set in your environment — unset it to log out. (No stored credential was changed.)');
+    return;
+  }
+  const stored = readCredential();
+  if (!stored) { log('not logged in.'); return; }
+  try {
+    await fetch(`${API_URL}/api/cli/auth/logout`, { method: 'POST', headers: { Authorization: `Bearer ${stored}` } });
+  } catch { /* offline — still clear the local credential below */ }
+  try { rmSync(CRED_PATH, { force: true }); } catch { /* noop */ }
+  TOKEN = '';
+  log('logged out — credential revoked and removed.');
+}
+
+// Report whether this machine is authenticated, and validate the credential against the API.
+async function cmdWhoami() {
+  if (!TOKEN) { log('not logged in. Run: murk login'); return; }
+  const src = process.env.MURK_API_TOKEN ? 'MURK_API_TOKEN env' : '~/.murk/credentials.json';
+  try {
+    const res = await fetch(`${API_URL}/api/applications`, { headers: { Authorization: `Bearer ${TOKEN}` } });
+    if (res.ok) log(`logged in to ${API_URL}  (credential: ${src})`);
+    else if (res.status === 401) log('stored credential is invalid or revoked — run: murk login');
+    else log(`logged in (${src}), but ${API_URL} returned HTTP ${res.status}`);
+  } catch (e) { log(`could not reach ${API_URL}: ${e instanceof Error ? e.message : e}`); }
+}
+
+// Add a GitHub-connected application from the CLI (mirrors the MCP murk_add_application
+// tool; shares addGithubApplication so the two never diverge). Logs go to stderr; the new
+// application id is printed to stdout so it can be piped into scripts.
+async function cmdAdd(repo, name) {
+  await ensureAuth();
+  if (!repo) die('usage: murk add <owner/repo> [--name NAME]');
+  const { addGithubApplication } = await import('./mcp-server.mjs');
+  const app = await addGithubApplication(api, { githubRepo: repo, name });
+  log(`added application "${app.name}" (${app.id})`);
+  process.stdout.write(`${app.id}\n`);
+}
+
+// List the organization's applications (id, name, source kind) for discovery.
+async function cmdApps() {
+  await ensureAuth();
+  const apps = await api('GET', '/api/applications');
+  const list = Array.isArray(apps) ? apps : (apps.applications ?? []);
+  if (!list.length) { log('no applications yet. Add one:  murk add <owner/repo>'); return; }
+  for (const a of list) {
+    const src = a.sourceAssetId ? 'github' : ((a.environments ?? []).length ? 'env' : '-');
+    process.stdout.write(`${a.id}  ${a.name}  [${src}]\n`);
+  }
+}
+
+// First positional arg that isn't a flag or a flag's value (for `murk add <repo>`).
+function firstPositional(rest, valueFlags = ['--name']) {
+  for (let i = 0; i < rest.length; i++) {
+    if (valueFlags.includes(rest[i])) { i++; continue; }
+    if (!rest[i].startsWith('-')) return rest[i];
+  }
+  return undefined;
+}
+
+function parseFlagValue(rest, flag) {
+  const i = rest.indexOf(flag);
+  return i >= 0 && rest[i + 1] ? rest[i + 1] : undefined;
+}
+
 function parseExposed(rest) {
   const exposed = [];
   for (let i = 0; i < rest.length; i++) {
@@ -289,26 +395,67 @@ function parseExposed(rest) {
   return exposed;
 }
 
+// Scan depth from flags: --pr / --full, or --profile pr|full. Default (undefined) => 'full'
+// server-side. 'pr' is the fast, cheaper, no-council scan.
+function parseScanProfile(rest) {
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--pr') return 'pr';
+    if (rest[i] === '--full') return 'full';
+    if (rest[i] === '--profile' && (rest[i + 1] === 'pr' || rest[i + 1] === 'full')) return rest[i + 1];
+  }
+  return undefined;
+}
+
+const USAGE =
+  'murk — MCP server for your AI agent + scan your local apps with MURK’s hosted runner.\n' +
+  '\n' +
+  'usage:\n' +
+  '  murk login                                      browser sign-in; authorizes this machine\n' +
+  '  murk logout                                     revoke this machine’s credential\n' +
+  '  murk whoami                                     show login status\n' +
+  '  murk apps                                       list your applications (id, name, source)\n' +
+  '  murk add <owner/repo> [--name NAME]             add an app from a connected GitHub repo\n' +
+  '  murk scan <http://localhost:PORT> [--pr|--full] one-shot: connect, scan, disconnect (default: full)\n' +
+  '  murk mcp [--expose <http://localhost:PORT> ...] run the MCP server for your agent; exposes local apps\n' +
+  '  murk connect --expose <http://localhost:PORT>   open the tunnel only (no MCP)\n' +
+  '\n' +
+  'scan depth:\n' +
+  '  --full   deep whole-repo audit with the model council (~45 min)   [default]\n' +
+  '  --pr     fast, cheaper scan, no council (~10 min)\n' +
+  '\n' +
+  'env:\n' +
+  '  MURK_API_URL        API origin (default https://api.murk.sh)\n' +
+  '  MURK_DASHBOARD_URL  dashboard origin for login (default https://app.murk.sh)\n' +
+  '  MURK_API_TOKEN      org API token (murk_…) for CI; overrides the stored login\n' +
+  '  MURK_NO_BROWSER     set to print the login URL instead of opening a browser\n' +
+  '\n' +
+  'agents: add the hosted MCP with   claude mcp add --transport http murk https://api.murk.sh/mcp\n' +
+  '        or run it locally with    murk mcp\n';
+
 function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const fatal = (e) => die(e instanceof Error ? e.message : String(e));
   if (cmd === 'login') {
     void cmdLogin().catch(fatal);
+  } else if (cmd === 'logout') {
+    void cmdLogout().catch(fatal);
+  } else if (cmd === 'whoami') {
+    void cmdWhoami().catch(fatal);
+  } else if (cmd === 'add') {
+    void cmdAdd(firstPositional(rest), parseFlagValue(rest, '--name')).catch(fatal);
+  } else if (cmd === 'apps' || cmd === 'ls') {
+    void cmdApps().catch(fatal);
   } else if (cmd === 'mcp') {
     void cmdMcp(parseExposed(rest)).catch(fatal);
   } else if (cmd === 'connect') {
     void cmdConnect(parseExposed(rest)).catch(fatal);
   } else if (cmd === 'scan') {
-    void cmdScan(rest.find((a) => a.startsWith('http'))).catch(fatal);
+    void cmdScan(rest.find((a) => a.startsWith('http')), parseScanProfile(rest)).catch(fatal);
   } else {
-    process.stdout.write(
-      'usage:\n' +
-      '  murk login                                      # browser sign-in; authorizes this machine\n' +
-      '  murk mcp [--expose http://localhost:3000 ...]   # MCP server for your agent; exposes local apps\n' +
-      '  murk scan http://localhost:3000                 # one-shot: connect, scan, disconnect\n' +
-      '  murk connect --expose http://localhost:3000     # tunnel only (no MCP)\n',
-    );
-    process.exit(cmd ? 1 : 0);
+    const unknown = cmd && cmd !== 'help' && cmd !== '-h' && cmd !== '--help';
+    if (unknown) process.stderr.write(`murk: unknown command "${cmd}"\n\n`);
+    process.stdout.write(USAGE);
+    process.exit(unknown ? 1 : 0);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@murk-security/cli",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Run MURK's MCP server for your AI agent and scan locally-running apps with MURK's hosted runner over a secure outbound tunnel — no local runner, no model key.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "murk.mjs",
-    "mcp-server.mjs"
+    "mcp-server.mjs",
+    "README.md"
   ],
   "keywords": [
     "murk",