@rafter-security/cli 0.11.7 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist/commands/agent/auto-update.js +171 -0
  2. package/dist/commands/agent/components.js +50 -176
  3. package/dist/commands/agent/enable.js +11 -1
  4. package/dist/commands/agent/index.js +2 -0
  5. package/dist/commands/agent/init.js +654 -764
  6. package/dist/commands/agent/install-files.js +689 -0
  7. package/dist/commands/agent/instruction-block.js +82 -40
  8. package/dist/commands/agent/scan.js +70 -21
  9. package/dist/commands/agent/status.js +11 -0
  10. package/dist/commands/agent/update.js +179 -0
  11. package/dist/commands/agent/verify.js +11 -0
  12. package/dist/commands/backend/get.js +5 -10
  13. package/dist/commands/backend/run.js +10 -20
  14. package/dist/commands/backend/scan-status.js +16 -3
  15. package/dist/commands/backend/usage.js +3 -6
  16. package/dist/commands/brief.js +6 -12
  17. package/dist/commands/counters.js +146 -0
  18. package/dist/commands/gates.js +36 -0
  19. package/dist/commands/hook/pretool.js +22 -9
  20. package/dist/commands/mcp/server.js +1 -1
  21. package/dist/commands/skill/registry.js +48 -0
  22. package/dist/core/usage-counters.js +439 -0
  23. package/dist/index.js +36 -0
  24. package/dist/scanners/gate-scanner.js +721 -0
  25. package/dist/scanners/regex-scanner.js +26 -25
  26. package/dist/utils/skill-manager.js +8 -338
  27. package/package.json +1 -1
  28. package/resources/continue-rules/rafter-code-review.md +6 -6
  29. package/resources/continue-rules/rafter-secure-design.md +3 -4
  30. package/resources/continue-rules/rafter-skill-review.md +4 -4
  31. package/resources/continue-rules/rafter.md +2 -2
  32. package/resources/cursor-rules/rafter-code-review.mdc +6 -6
  33. package/resources/cursor-rules/rafter-secure-design.mdc +3 -4
  34. package/resources/cursor-rules/rafter-skill-review.mdc +4 -4
  35. package/resources/cursor-rules/rafter.mdc +2 -2
  36. package/resources/rafter-security-skill.md +1 -1
  37. package/resources/shipped-hashes.json +332 -0
  38. package/resources/skills/rafter/SKILL.md +7 -7
  39. package/resources/skills/rafter/docs/cli-reference.md +37 -10
  40. package/resources/skills/rafter/docs/finding-triage.md +1 -1
  41. package/resources/skills/rafter/docs/guardrails.md +2 -2
  42. package/resources/skills/rafter/docs/shift-left.md +4 -4
  43. package/resources/skills/rafter-code-review/SKILL.md +43 -14
  44. package/resources/skills/rafter-code-review/docs/llm.md +2 -2
  45. package/resources/skills/rafter-code-review/docs/security-gates.md +53 -0
  46. package/resources/skills/rafter-secure-design/SKILL.md +1 -0
  47. package/resources/skills/rafter-skill-review/SKILL.md +1 -0
  48. package/resources/windsurf-rules/rafter-code-review.md +6 -6
  49. package/resources/windsurf-rules/rafter-secure-design.md +3 -4
  50. package/resources/windsurf-rules/rafter-skill-review.md +4 -4
  51. package/resources/windsurf-rules/rafter.md +2 -2
@@ -5,7 +5,8 @@ import { resolveKey, EXIT_GENERAL_ERROR, EXIT_QUOTA_EXHAUSTED, EXIT_CONFIRMATION
5
5
  import { ConfigManager } from "../../core/config-manager.js";
6
6
  import { loadPolicy } from "../../core/policy-loader.js";
7
7
  import { askYesNo } from "../../utils/prompt.js";
8
- import { handleScanStatus } from "./scan-status.js";
8
+ import { fmt } from "../../utils/formatter.js";
9
+ import { handleScanStatus, describeHttpError } from "./scan-status.js";
9
10
  /**
10
11
  * sable-9ddf — is the Plus-scan approval gate enabled?
11
12
  *
@@ -78,10 +79,10 @@ export async function runRemoteScan(opts) {
78
79
  }
79
80
  catch (e) {
80
81
  if (e instanceof Error) {
81
- console.error(e.message);
82
+ console.error(fmt.error(e.message));
82
83
  }
83
84
  else {
84
- console.error(e);
85
+ console.error(fmt.error(describeHttpError(e)));
85
86
  }
86
87
  process.exit(EXIT_GENERAL_ERROR);
87
88
  }
@@ -90,8 +91,8 @@ export async function runRemoteScan(opts) {
90
91
  if (localBranch) {
91
92
  const remoteSha = remoteBranchSha(branch);
92
93
  if (remoteSha === null) {
93
- console.error(`Branch "${branch}" does not exist on the remote (origin). Rafter scans the remote ` +
94
- "repository: push the branch first, or pass --branch to scan one that exists.");
94
+ console.error(fmt.error(`Branch "${branch}" does not exist on the remote (origin). Rafter scans the remote ` +
95
+ "repository: push the branch first, or pass --branch to scan one that exists."));
95
96
  process.exit(EXIT_GENERAL_ERROR);
96
97
  }
97
98
  if (remoteSha && !opts.quiet) {
@@ -141,17 +142,11 @@ export async function runRemoteScan(opts) {
141
142
  process.exit(forbiddenCode);
142
143
  }
143
144
  else if (e.response?.status === 429) {
144
- console.error("Quota exhausted");
145
+ console.error(fmt.error("Quota exhausted"));
145
146
  process.exit(EXIT_QUOTA_EXHAUSTED);
146
147
  }
147
- else if (e.response?.data) {
148
- console.error(e.response.data);
149
- }
150
- else if (e instanceof Error) {
151
- console.error(e.message);
152
- }
153
148
  else {
154
- console.error(e);
149
+ console.error(fmt.error(describeHttpError(e)));
155
150
  }
156
151
  process.exit(EXIT_GENERAL_ERROR);
157
152
  }
@@ -170,16 +165,11 @@ export async function runRemoteScan(opts) {
170
165
  process.exit(forbiddenCode);
171
166
  }
172
167
  else if (e.response?.status === 429) {
168
+ console.error(fmt.error("Quota exhausted"));
173
169
  process.exit(EXIT_QUOTA_EXHAUSTED);
174
170
  }
175
- else if (e.response?.data) {
176
- console.error(e.response.data);
177
- }
178
- else if (e instanceof Error) {
179
- console.error(e.message);
180
- }
181
171
  else {
182
- console.error(e);
172
+ console.error(fmt.error(describeHttpError(e)));
183
173
  }
184
174
  process.exit(EXIT_GENERAL_ERROR);
185
175
  }
@@ -1,4 +1,5 @@
1
1
  import ora from "ora";
2
+ import { inspect } from "node:util";
2
3
  import { API_TIMEOUT_SHORT_MS, writePayload, EXIT_GENERAL_ERROR, EXIT_SCAN_NOT_FOUND, apiClient, apiUrl } from "../../utils/api.js";
3
4
  import { fmt as output } from "../../utils/formatter.js";
4
5
  /**
@@ -107,13 +108,23 @@ function truncate(value) {
107
108
  // A server is free to answer {"error": {"message": "..."}}. Coerce before
108
109
  // touching string methods — this used to throw, which turned a retryable
109
110
  // failure into an immediate crash with a nonsense message.
110
- const s = typeof value === "string" ? value : JSON.stringify(value) ?? String(value);
111
+ let json;
112
+ if (typeof value !== "string") {
113
+ try {
114
+ json = JSON.stringify(value);
115
+ }
116
+ catch {
117
+ // Circular references and BigInt values make JSON.stringify throw;
118
+ // inspect renders both instead of crashing the error path.
119
+ }
120
+ }
121
+ const s = typeof value === "string" ? value : json ?? inspect(value, { breakLength: Infinity });
111
122
  const flat = s.replace(/[\r\n]+/g, " ").trim();
112
123
  return flat.length > MAX_ERROR_DETAIL_CHARS
113
124
  ? `${flat.slice(0, MAX_ERROR_DETAIL_CHARS)}…`
114
125
  : flat;
115
126
  }
116
- function describeHttpError(e) {
127
+ export function describeHttpError(e) {
117
128
  const status = e?.response?.status;
118
129
  const data = e?.response?.data;
119
130
  let detail = "";
@@ -127,9 +138,11 @@ function describeHttpError(e) {
127
138
  detail = e.message;
128
139
  }
129
140
  const detailText = truncate(detail);
141
+ // A non-Error throw (string, plain object) carries its detail in the value
142
+ // itself; String() would reduce a plain object to "[object Object]".
130
143
  return status
131
144
  ? `HTTP ${status}${detailText ? ` — ${detailText}` : ""}`
132
- : detailText || String(e);
145
+ : detailText || (e instanceof Error ? String(e) : truncate(e));
133
146
  }
134
147
  /**
135
148
  * The message a customer actually sees when the report never becomes readable.
@@ -1,5 +1,7 @@
1
1
  import { Command } from "commander";
2
2
  import { resolveKey, EXIT_GENERAL_ERROR, apiClient, apiUrl } from "../../utils/api.js";
3
+ import { fmt } from "../../utils/formatter.js";
4
+ import { describeHttpError } from "./scan-status.js";
3
5
  export function createUsageCommand() {
4
6
  return new Command("usage")
5
7
  .option("-k, --api-key <key>", "API key or RAFTER_API_KEY env var")
@@ -10,12 +12,7 @@ export function createUsageCommand() {
10
12
  console.log(JSON.stringify(data, null, 2));
11
13
  }
12
14
  catch (e) {
13
- if (e.response?.data) {
14
- console.error(e.response.data);
15
- }
16
- else {
17
- console.error(e.message);
18
- }
15
+ console.error(fmt.error(describeHttpError(e)));
19
16
  process.exit(EXIT_GENERAL_ERROR);
20
17
  }
21
18
  });
@@ -67,21 +67,15 @@ function buildTopics() {
67
67
  description: "Condensed command reference for all rafter commands",
68
68
  render: () => {
69
69
  const rafter = loadSkill("rafter");
70
- const cmds = extractSections(rafter, [
71
- "Core Commands",
72
- "Commands",
73
- "Trigger",
74
- "Get Scan",
75
- "Check API",
76
- "/rafter-scan",
77
- "/rafter-bash",
78
- "/rafter-audit-skill",
79
- "/rafter-audit",
80
- ]);
70
+ const fastPath = extractSections(rafter, ["Fast Path"]);
71
+ const cliReference = loadSkillDoc("rafter", "cli-reference");
72
+ const decisionTable = extractSections(cliReference, ["Quick Decision Table"]);
81
73
  return [
82
74
  "# Rafter Command Reference",
83
75
  "",
84
- cmds,
76
+ fastPath,
77
+ "",
78
+ decisionTable,
85
79
  ].join("\n");
86
80
  },
87
81
  },
@@ -0,0 +1,146 @@
1
+ import { Command } from "commander";
2
+ import { createRequire } from "module";
3
+ import fs from "fs";
4
+ import { USAGE_FAMILIES, USAGE_NOTICE, USAGE_STORE_DISPLAY, USAGE_ALLOWLIST, clearStore, discardPending, readCounters, usageStatus, } from "../core/usage-counters.js";
5
+ import { getConfigPath } from "../core/config-defaults.js";
6
+ import { listBundledSkills, readSkillFrontmatter, skillDestPath, SKILL_PLATFORMS } from "./skill/registry.js";
7
+ const require = createRequire(import.meta.url);
8
+ const { version: VERSION } = require("../../package.json");
9
+ const FAMILY_TITLES = {
10
+ unknown_command: "Unknown commands",
11
+ unknown_option: "Unknown options",
12
+ command: "Command results",
13
+ hook: "Hook decisions",
14
+ scan_engine: "Scan engines",
15
+ scan_fallback: "Scan fall-backs",
16
+ scan_duration: "Scan durations",
17
+ error_class: "Errors",
18
+ };
19
+ const VERSION_RE = /^[0-9A-Za-z.+-]{1,32}$/;
20
+ const cleanVersion = (v) => typeof v === "string" && VERSION_RE.test(v) ? v : v == null ? null : "other";
21
+ /** Installed rafter skills vs the versions this CLI ships. Names and platforms are enumerated, never read from disk. */
22
+ function skillStaleness() {
23
+ const rows = [];
24
+ for (const skill of listBundledSkills()) {
25
+ for (const platform of SKILL_PLATFORMS) {
26
+ const dest = skillDestPath(platform, skill.name);
27
+ if (!fs.existsSync(dest))
28
+ continue;
29
+ const fm = readSkillFrontmatter(dest);
30
+ const installed = cleanVersion(fm.version ?? null);
31
+ const pinned = cleanVersion(fm.rafter_cli_version ?? null);
32
+ rows.push({
33
+ name: skill.name,
34
+ platform,
35
+ installed_version: installed,
36
+ current_version: skill.version,
37
+ stale: installed !== skill.version || (pinned !== null && pinned !== VERSION),
38
+ });
39
+ }
40
+ }
41
+ let openclaw;
42
+ try {
43
+ const cfg = JSON.parse(fs.readFileSync(getConfigPath(), "utf-8"));
44
+ openclaw = cfg?.agent?.skills?.installedVersion ?? cfg?.agent?.skills?.installed_version;
45
+ }
46
+ catch {
47
+ openclaw = undefined;
48
+ }
49
+ if (typeof openclaw === "string" && openclaw) {
50
+ const installed = cleanVersion(openclaw);
51
+ rows.push({
52
+ name: "rafter-security",
53
+ platform: "openclaw",
54
+ installed_version: installed,
55
+ current_version: VERSION,
56
+ stale: installed !== VERSION,
57
+ });
58
+ }
59
+ return rows.sort((a, b) => (a.name + "\0" + a.platform < b.name + "\0" + b.platform ? -1 : 1));
60
+ }
61
+ export function buildCountersReport(days) {
62
+ const status = usageStatus();
63
+ const { since, counters } = readCounters(days);
64
+ return {
65
+ schema: USAGE_ALLOWLIST.schema,
66
+ notice: USAGE_NOTICE,
67
+ cli_version: VERSION,
68
+ runtime: "node",
69
+ runtime_major: Number(process.versions.node.split(".")[0]),
70
+ os: process.platform,
71
+ enabled: status.enabled,
72
+ enabled_source: status.source,
73
+ store: USAGE_STORE_DISPLAY,
74
+ days,
75
+ since,
76
+ counters,
77
+ skills: skillStaleness(),
78
+ };
79
+ }
80
+ function printText(r) {
81
+ const out = [];
82
+ out.push(`Rafter usage counters, last ${r.days} day(s) (since ${r.since} UTC)`);
83
+ out.push(r.notice);
84
+ out.push("");
85
+ out.push(`CLI version: ${r.cli_version}`);
86
+ out.push(`Runtime: ${r.runtime} ${r.runtime_major}`);
87
+ out.push(`OS: ${r.os}`);
88
+ out.push(`Counting: ${r.enabled ? "enabled" : "disabled"} (${r.enabled_source})`);
89
+ out.push(`Store: ${r.store}`);
90
+ let any = false;
91
+ for (const fam of USAGE_FAMILIES) {
92
+ const entries = Object.entries(r.counters[fam]);
93
+ if (entries.length === 0)
94
+ continue;
95
+ any = true;
96
+ out.push("");
97
+ out.push(FAMILY_TITLES[fam] ?? fam);
98
+ for (const [k, n] of entries)
99
+ out.push(` ${k.padEnd(48)} ${n}`);
100
+ }
101
+ if (!any) {
102
+ out.push("");
103
+ out.push("No counts recorded.");
104
+ }
105
+ out.push("");
106
+ out.push("Skills");
107
+ if (r.skills.length === 0)
108
+ out.push(" (no rafter skills installed)");
109
+ for (const s of r.skills) {
110
+ const label = `${s.name} (${s.platform})`.padEnd(36);
111
+ out.push(` ${label} installed ${s.installed_version ?? "unknown"}, current ${s.current_version}: ${s.stale ? "stale" : "up to date"}`);
112
+ }
113
+ process.stdout.write(out.join("\n") + "\n");
114
+ }
115
+ export function createCountersCommand() {
116
+ const counters = new Command("counters")
117
+ .description(`Show or clear local usage counters. ${USAGE_NOTICE}`);
118
+ counters
119
+ .command("show")
120
+ .description(`Print the local usage counters for the last N days. ${USAGE_NOTICE}`)
121
+ .option("--json", "Output machine-readable JSON")
122
+ .option("--days <n>", "Days to include, 1 to 7", "7")
123
+ .action((opts) => {
124
+ const days = Number(opts.days);
125
+ if (!/^\d+$/.test(String(opts.days)) || days < 1 || days > USAGE_ALLOWLIST.retention_days) {
126
+ console.error(`Error: --days must be an integer from 1 to ${USAGE_ALLOWLIST.retention_days}`);
127
+ process.exit(2);
128
+ }
129
+ const report = buildCountersReport(days);
130
+ if (opts.json)
131
+ process.stdout.write(JSON.stringify(report, null, 2) + "\n");
132
+ else
133
+ printText(report);
134
+ });
135
+ counters
136
+ .command("clear")
137
+ .description(`Delete the local usage counters (${USAGE_STORE_DISPLAY})`)
138
+ .action(() => {
139
+ discardPending();
140
+ const existed = clearStore();
141
+ process.stdout.write(existed
142
+ ? `Deleted local usage counters (${USAGE_STORE_DISPLAY}).\n`
143
+ : `No local usage counters to delete (${USAGE_STORE_DISPLAY}).\n`);
144
+ });
145
+ return counters;
146
+ }
@@ -0,0 +1,36 @@
1
+ import { Command } from "commander";
2
+ import fs from "fs";
3
+ import path from "path";
4
+ import { mapGates, formatGateMap } from "../scanners/gate-scanner.js";
5
+ export function createGatesCommand() {
6
+ return new Command("gates")
7
+ .description("Map a codebase's security gates (functions that decide whether something is allowed) and their twins, for an audit")
8
+ .argument("[path]", "Directory or file to map", ".")
9
+ .option("--json", "Output JSON")
10
+ .option("--limit <n>", "Number of ranked gates to show", "60")
11
+ .option("--no-gitignore", "Do not honor .gitignore")
12
+ .action((target, opts) => {
13
+ const limit = /^\d+$/.test(opts.limit) ? Number(opts.limit) : NaN;
14
+ if (!Number.isInteger(limit) || limit < 1) {
15
+ console.error(`Error: --limit must be a positive integer, got: ${opts.limit}`);
16
+ process.exit(2);
17
+ }
18
+ const resolved = path.resolve(target);
19
+ if (!fs.existsSync(resolved)) {
20
+ console.error(`Error: Path not found: ${resolved}`);
21
+ process.exit(2);
22
+ }
23
+ const map = mapGates(resolved, { limit, respectGitignore: opts.gitignore });
24
+ if (map.stats.files_scanned === 0) {
25
+ console.error(`Warning: no source files scanned under ${resolved} (none found, unreadable, oversize or generated)`);
26
+ }
27
+ if (opts.json) {
28
+ process.stdout.write(JSON.stringify(map, null, 2) + "\n");
29
+ }
30
+ else {
31
+ process.stdout.write(formatGateMap(map));
32
+ }
33
+ // exitCode, not exit(): exit() can cut off output still buffered for a pipe.
34
+ process.exitCode = 0;
35
+ });
36
+ }
@@ -10,11 +10,13 @@ import { applySuppressions } from "../../core/custom-patterns.js";
10
10
  import { resolveHookControl } from "../../core/hook-control.js";
11
11
  import { collectSuppressions, applyExcludePaths } from "../agent/scan.js";
12
12
  import { shellQuote } from "../agent/exec.js";
13
+ import { runHookAutoUpdate } from "../agent/auto-update.js";
13
14
  import { scanAddedDiffLines } from "../../scanners/git-diff-scan.js";
14
15
  import { parseUnifiedDiffAddedLines, gitDiffMaxBuffer } from "../../utils/git-diff.js";
15
16
  import { execSync } from "child_process";
16
17
  import fs from "fs";
17
18
  import path from "path";
19
+ import { countHook } from "../../core/usage-counters.js";
18
20
  /**
19
21
  * Load the policy-merged scan config + suppression list the same way scan.ts
20
22
  * does, so hook decisions match `rafter secrets`. Policy discovery and
@@ -99,7 +101,10 @@ export function createHookPretoolCommand() {
99
101
  catch (e) {
100
102
  decision = denyOnError(e);
101
103
  }
104
+ countHook(decision.tool, decision.error ? "error" : decision.decision, decision.risk);
102
105
  writeDecision(decision, format);
106
+ // Once a day after an upgrade: bring installed skill and rule files up to this version.
107
+ runHookAutoUpdate();
103
108
  });
104
109
  }
105
110
  /**
@@ -132,7 +137,7 @@ function denyOnError(e) {
132
137
  const msg = e instanceof Error ? e.message : String(e);
133
138
  const reason = `rafter hook error: ${type}: ${msg}; denying to be safe`;
134
139
  console.error(reason);
135
- return { decision: "deny", reason };
140
+ return { decision: "deny", reason, error: true };
136
141
  }
137
142
  /**
138
143
  * Normalize platform-specific stdin JSON into a common HookInput shape.
@@ -185,18 +190,19 @@ function evaluateToolCall(payload) {
185
190
  // Honor the (trusted-source-only) hook off-switch before doing any work.
186
191
  // Master switch off → allow everything; otherwise the two concerns are gated
187
192
  // independently inside evaluateBash (command policy + git-commit secret scan).
193
+ const tool = SHELL_TOOLS.has(tool_name) ? "shell" : WRITE_TOOLS.has(tool_name) ? "write" : "other";
188
194
  const control = resolveHookControl();
189
195
  if (!control.hookEnabled)
190
- return { decision: "allow" };
191
- if (SHELL_TOOLS.has(tool_name)) {
192
- return evaluateBash(tool_input?.command || "", control);
196
+ return { decision: "allow", tool };
197
+ if (tool === "shell") {
198
+ return { ...evaluateBash(tool_input?.command || "", control), tool };
193
199
  }
194
- if (WRITE_TOOLS.has(tool_name)) {
200
+ if (tool === "write") {
195
201
  if (!control.secretScanEnabled)
196
- return { decision: "allow" };
197
- return evaluateWrite(normalizeWriteInput(tool_name, tool_input || {}));
202
+ return { decision: "allow", tool };
203
+ return { ...evaluateWrite(normalizeWriteInput(tool_name, tool_input || {})), tool };
198
204
  }
199
- return { decision: "allow" };
205
+ return { decision: "allow", tool };
200
206
  }
201
207
  /**
202
208
  * Shell and file-write tools under each platform's own name, so the same
@@ -251,18 +257,21 @@ function applyPatchPaths(patch) {
251
257
  }
252
258
  function evaluateBash(command, control) {
253
259
  const audit = new AuditLogger();
260
+ let risk = "none";
254
261
  // Command-risk interception — gated by commandPolicy. When disabled, skip the
255
262
  // block/approval logic but still fall through to the staged-secret scan below
256
263
  // (a user may keep secret scanning while silencing command prompts).
257
264
  if (control.commandPolicyEnabled) {
258
265
  const interceptor = new CommandInterceptor();
259
266
  const evaluation = interceptor.evaluate(command);
267
+ risk = evaluation.riskLevel;
260
268
  // Blocked — hard deny
261
269
  if (!evaluation.allowed && !evaluation.requiresApproval) {
262
270
  audit.logCommandIntercepted(command, false, "blocked", evaluation.reason);
263
271
  return {
264
272
  decision: "deny",
265
273
  reason: formatBlockedMessage(command, evaluation),
274
+ risk,
266
275
  };
267
276
  }
268
277
  // Requires approval — deny (agent can't provide interactive approval)
@@ -271,6 +280,7 @@ function evaluateBash(command, control) {
271
280
  return {
272
281
  decision: "deny",
273
282
  reason: formatApprovalMessage(command, evaluation),
283
+ risk,
274
284
  };
275
285
  }
276
286
  }
@@ -285,6 +295,7 @@ function evaluateBash(command, control) {
285
295
  decision: "deny",
286
296
  reason: `Rafter: secret scan of the staged diff could not run (${scanResult.scanError}); ` +
287
297
  "commit blocked rather than allowed unscanned. Run 'rafter secrets --staged' to investigate.",
298
+ risk,
288
299
  };
289
300
  }
290
301
  if (scanResult.secretsFound) {
@@ -297,11 +308,12 @@ function evaluateBash(command, control) {
297
308
  return {
298
309
  decision: "deny",
299
310
  reason: formatStagedSecretReason(scanResult),
311
+ risk,
300
312
  };
301
313
  }
302
314
  }
303
315
  audit.logCommandIntercepted(command, true, "allowed");
304
- return { decision: "allow" };
316
+ return { decision: "allow", risk };
305
317
  }
306
318
  /**
307
319
  * True if this write targets rafter's own configuration directory.
@@ -355,6 +367,7 @@ function evaluateWrite(toolInput) {
355
367
  " Risk: CRITICAL\u2014editing this file reconfigures or removes the\n" +
356
368
  " guardrail. The gate cannot approve its own disarming. A\n" +
357
369
  " person must make this change outside an agent session.",
370
+ risk: "critical",
358
371
  };
359
372
  }
360
373
  // Write uses "content", Edit uses "new_string"
@@ -129,7 +129,7 @@ export function createServer() {
129
129
  rules: {
130
130
  type: "array",
131
131
  items: { type: "string" },
132
- description: "Specific rules to suppress, matched case-insensitively against a finding's rule name OR rule id — e.g. 'AWS Access Key' (local pattern name) or 'R-6D5E2' (remote SAST/SCA rule id). Omit to suppress all rules for the path. Honored by both local scans and remote `rafter run`.",
132
+ description: "Specific rules to suppress, matched case-insensitively against a finding's rule name OR rule id — e.g. 'AWS Access Key' (local pattern name) or 'R-6D5E2' (the hashed id the hosted report shows; the native rule id works too). Omit to suppress all rules for the path. Honored by both local scans and remote `rafter run`. With a reason, the hosted scanner will hide even a must-fix or secret-scanner finding and lists it prominently in suppressed.json under `protected_suppressions`. Without a reason the rule still hides ordinary findings but is held at the floor for must-fix and secret-scanner ones, so always give one.",
133
133
  },
134
134
  reason: { type: "string", description: "Why this is a false positive — persisted with the rule. Strongly recommended." },
135
135
  },
@@ -53,6 +53,54 @@ export function readSkillFrontmatter(filePath) {
53
53
  return {};
54
54
  }
55
55
  }
56
+ /**
57
+ * Frontmatter value that marks a SKILL.md as rafter-authored. Every bundled
58
+ * skill under `resources/skills/` carries `publisher: rafter-security` for
59
+ * exactly this check — so retired-skill cleanup (below) can tell "an old
60
+ * rafter skill we renamed away from" from "a user's own skill that happens to
61
+ * share a directory name" before deleting anything.
62
+ */
63
+ export const RAFTER_SKILL_PUBLISHER = "rafter-security";
64
+ /** True if the SKILL.md at `skillDir/SKILL.md` identifies itself as rafter's. */
65
+ export function isRafterAuthoredSkillDir(skillDir) {
66
+ const fm = readSkillFrontmatter(path.join(skillDir, "SKILL.md"));
67
+ return fm.publisher === RAFTER_SKILL_PUBLISHER;
68
+ }
69
+ /**
70
+ * Names of rafter skills that USED to ship but no longer do (renamed or
71
+ * removed). Empty today — add a name here when retiring a skill, and every
72
+ * install path that manages a skills directory (`removeRetiredSkills` below)
73
+ * cleans up the old copy on the next install/enable instead of needing new
74
+ * hand-written unlink code per rename.
75
+ */
76
+ export const RETIRED_SKILL_NAMES = [];
77
+ /**
78
+ * Remove any retired-skill directories found under `skillsBaseDir` (a
79
+ * `<platform>/skills` style directory containing one subdir per skill, each
80
+ * holding a SKILL.md). Only removes a directory whose SKILL.md identifies
81
+ * itself as rafter-authored — a user skill that happens to reuse a retired
82
+ * name is left alone. Returns the names actually removed.
83
+ *
84
+ * `isOwned` is a second proof of ownership for directories without the tag
85
+ * (older releases shipped none): agent init passes a check that every file
86
+ * hashes to content rafter shipped or recorded in its install manifest.
87
+ *
88
+ * `retiredNames` defaults to `RETIRED_SKILL_NAMES`; tests pass an explicit
89
+ * list to simulate a rename without needing a real retired skill yet.
90
+ */
91
+ export function removeRetiredSkills(skillsBaseDir, retiredNames = RETIRED_SKILL_NAMES, isOwned) {
92
+ const removed = [];
93
+ for (const name of retiredNames) {
94
+ const dir = path.join(skillsBaseDir, name);
95
+ if (!fs.existsSync(path.join(dir, "SKILL.md")))
96
+ continue;
97
+ if (!isRafterAuthoredSkillDir(dir) && !(isOwned?.(dir, name) ?? false))
98
+ continue;
99
+ fs.rmSync(dir, { recursive: true, force: true });
100
+ removed.push(name);
101
+ }
102
+ return removed;
103
+ }
56
104
  /** Enumerate bundled rafter-authored skills present in this installation. */
57
105
  export function listBundledSkills() {
58
106
  const root = skillsResourcesRoot();