pi-hackerone 0.5.0 → 0.6.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.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # pi-hackerone
2
2
 
3
- A pi package that adds HackerOne report fetching, commenting, and triaging powered by [`@matteo.collina/hackerone`](https://www.npmjs.com/package/@matteo.collina/hackerone).
3
+ A pi package that adds HackerOne report fetching, commenting, and state changes (triage, close, reopen) powered by [`@matteo.collina/hackerone`](https://www.npmjs.com/package/@matteo.collina/hackerone).
4
4
 
5
5
  ## Install
6
6
 
@@ -67,21 +67,42 @@ Parameters:
67
67
  - `internal` - Post as an internal (team-only) comment instead of a public one.
68
68
  - `attachmentIds` - Optional attachment IDs to attach to the comment.
69
69
 
70
- ### Tool: `hackerone_triage`
70
+ ### Tool: `hackerone_change_state`
71
71
 
72
- Move a specific report to triaged when explicitly requested:
72
+ Change a specific report's state when explicitly requested: triage it, ask the reporter for more information, close it, or reopen it.
73
73
 
74
74
  ```text
75
75
  Move HackerOne report 12345 to triaged.
76
+ Close HackerOne report 12345 as informative, telling the reporter this is an accepted risk.
77
+ Mark HackerOne report 12345 as a duplicate of 11111.
76
78
  ```
77
79
 
78
80
  Parameters:
79
81
 
80
82
  - `reportId` - HackerOne report number/id.
81
- - `message` - Optional public message visible to the reporter; use `hackerone_comment` with `internal: true` for team-only notes.
83
+ - `state` - The state to move the report to. See [Report states](#report-states).
84
+ - `message` - Message posted with the state change. It is visible to the reporter; use `hackerone_comment` with `internal: true` for team-only notes. Required for `needs-more-info`, `informative`, and `duplicate`.
85
+ - `originalReportId` - Only for `duplicate`: the ID of the original report.
86
+ - `attachmentIds` - Optional attachment IDs to include with the message.
82
87
 
83
88
  This action requires the API user's Report Management permission and may notify the reporter.
84
89
 
90
+ #### Report states
91
+
92
+ | State | Status | Message required | Definition |
93
+ | --- | --- | --- | --- |
94
+ | `new` | Open | No | The report is pending validation. Moving a closed report here reopens it for a fresh review. |
95
+ | `pending-program-review` | Open | No | HackerOne triage has initially validated the report, and it awaits review and severity validation by the program team. Only applies to programs that use HackerOne's triage services. |
96
+ | `triaged` | Open | No | The report is validated and escalated for remediation. The vulnerability is treated as live and reproducible until it is fixed. |
97
+ | `needs-more-info` | Open | Yes | The reporter must provide more information to reproduce the issue or demonstrate impact. HackerOne closes the report as informative, with no reputation change, after 30 days without a reply. |
98
+ | `resolved` | Closed | No | The vulnerability is fixed and no longer reproducible; no further action is needed. The reporter gains 7 reputation and is credited in the program's hall of fame. |
99
+ | `not-applicable` | Closed | No | The report has no valid, reproducible issue and no demonstrated security impact; explain why so the reporter can improve. The reporter loses 5 reputation and their signal drops. |
100
+ | `informative` | Closed | Yes | The report contains valid information that needs no action, such as an out-of-scope finding, a known issue, or an accepted risk. The reporter's reputation does not change. |
101
+ | `duplicate` | Closed | Yes | The issue was already reported or is otherwise known, or one fix resolves several reports. The reporter's reputation change depends on how the original report is closed. |
102
+ | `spam` | Closed | No | The report does not describe a legitimate security vulnerability, or it is incomprehensible, abusive, harassing, or selling a product or service. The reporter loses 10 reputation. |
103
+
104
+ Closed reports can only move back to `new` or `triaged`. `retesting` is not offered because HackerOne sets it through its separate retest flow. The states, definitions, and message rules come from [`@matteo.collina/hackerone`](https://www.npmjs.com/package/@matteo.collina/hackerone), which follows HackerOne's [report states](https://docs.hackerone.com/en/articles/8475030-report-states) and [change state API](https://api.hackerone.com/customer-resources/#reports-change-state) documentation.
105
+
85
106
  ### Command: `/hackerone-report`
86
107
 
87
108
  Fetch a report directly from the pi prompt:
@@ -93,14 +114,19 @@ Fetch a report directly from the pi prompt:
93
114
 
94
115
  The command inserts the fetched report into the session as a displayed custom message.
95
116
 
96
- ### Command: `/hackerone-triage`
117
+ ### Command: `/hackerone-state`
118
+
119
+ Change a report's state directly from the pi prompt. After the report number, press Tab to pick a state; each suggestion shows the state's definition.
97
120
 
98
121
  ```text
99
- /hackerone-triage 12345
100
- /hackerone-triage 12345 --message "Confirmed"
122
+ /hackerone-state 12345 triaged
123
+ /hackerone-state 12345 needs-more-info --message "Can you share the request that triggers the crash?"
124
+ /hackerone-state 12345 informative --message "This is an accepted risk."
125
+ /hackerone-state 12345 duplicate --message "Already reported" --original-report-id 11111
126
+ /hackerone-state 12345 not-applicable --message "Not reproducible" --attachment-id 42
101
127
  ```
102
128
 
103
- The command inserts the updated report state into the session.
129
+ Use any state from [Report states](#report-states). The command inserts the updated report state into the session.
104
130
 
105
131
  ### Command: `/hackerone-comment`
106
132
 
@@ -4,21 +4,35 @@ import { join } from "node:path";
4
4
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
5
5
  import {
6
6
  HackerOneClient,
7
- ReportState,
8
7
  changeReportState,
8
+ changeableReportStates,
9
9
  createComment,
10
10
  filterComments,
11
11
  getReport,
12
12
  isAppError,
13
13
  listAllActivities,
14
+ reportStates,
15
+ validateStateChange,
14
16
  type Activity,
17
+ type ChangeableReportState,
15
18
  type Report,
16
19
  } from "@matteo.collina/hackerone";
17
20
  import { Type } from "typebox";
18
21
 
19
22
  const TOOL_NAME = "hackerone_report";
20
23
  const COMMENT_TOOL_NAME = "hackerone_comment";
21
- const TRIAGE_TOOL_NAME = "hackerone_triage";
24
+ const STATE_TOOL_NAME = "hackerone_change_state";
25
+
26
+ // States and their definitions come from the client library, so the tool,
27
+ // the command, and the README stay in step with it.
28
+ const STATE_INFO = reportStates.filter((info) => info.changeable).map(({ state, status, requiresMessage, definition }) => {
29
+ const summary = `${status === "open" ? "Open" : "Closed"}${requiresMessage ? ", message required" : ""}. ${definition}`;
30
+ return { state, requiresMessage, summary };
31
+ });
32
+ const STATE_DEFINITIONS = STATE_INFO.map(({ state, summary }) => `- ${state}: ${summary}`).join("\n");
33
+ const MESSAGE_STATES = STATE_INFO.filter((info) => info.requiresMessage).map((info) => info.state).join(", ");
34
+ const STATE_TRANSITION_RULE = "Closed reports (resolved, informative, duplicate, not-applicable, spam) can only move back to new or triaged.";
35
+ const STATE_COMMAND_USAGE = "/hackerone-state <number> <state> [--message \"text\"] [--original-report-id id] [--attachment-id id]";
22
36
 
23
37
  const reportParameters = Type.Object({
24
38
  reportId: Type.Integer({
@@ -67,19 +81,37 @@ interface CommentToolParams {
67
81
  attachmentIds?: number[];
68
82
  }
69
83
 
70
- const triageParameters = Type.Object({
84
+ const stateParameters = Type.Object({
71
85
  reportId: Type.Integer({
72
86
  minimum: 1,
73
- description: "HackerOne report number/id to move to triaged.",
87
+ description: "HackerOne report number/id whose state should change.",
88
+ }),
89
+ // A plain string enum (not anyOf/const) so every model provider accepts it.
90
+ state: Type.Unsafe<ChangeableReportState>({
91
+ type: "string",
92
+ enum: [...changeableReportStates],
93
+ description: `The state to move the report to. ${STATE_TRANSITION_RULE} One of:\n${STATE_DEFINITIONS}`,
74
94
  }),
75
95
  message: Type.Optional(Type.String({
76
- description: "Optional public message visible to the reporter when the state changes. Do not include team-only notes.",
96
+ description: `Message posted on the report with the state change. It is visible to the reporter, so never include team-only notes. Required for ${MESSAGE_STATES}.`,
97
+ })),
98
+ originalReportId: Type.Optional(Type.Integer({
99
+ minimum: 1,
100
+ description: "Only for the duplicate state: the ID of the original report this one duplicates.",
101
+ })),
102
+ attachmentIds: Type.Optional(Type.Array(Type.Integer({
103
+ minimum: 1,
104
+ }), {
105
+ description: "Optional attachment IDs to include with the state change message.",
77
106
  })),
78
107
  });
79
108
 
80
- interface TriageToolParams {
109
+ interface StateToolParams {
81
110
  reportId: number;
111
+ state: ChangeableReportState;
82
112
  message?: string;
113
+ originalReportId?: number;
114
+ attachmentIds?: number[];
83
115
  }
84
116
 
85
117
  interface FetchReportResult {
@@ -148,7 +180,7 @@ function createClient(cwd: string): HackerOneClient {
148
180
  return new HackerOneClient(readCredentials(cwd));
149
181
  }
150
182
 
151
- function normalizeReportId(value: unknown): number | undefined {
183
+ function parsePositiveInteger(value: unknown): number | undefined {
152
184
  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
153
185
  return value;
154
186
  }
@@ -160,22 +192,41 @@ function normalizeReportId(value: unknown): number | undefined {
160
192
  return undefined;
161
193
  }
162
194
 
195
+ // Accepts case and separator variants such as "Not_Applicable" or "needs more info".
196
+ function normalizeState(value: unknown): ChangeableReportState | undefined {
197
+ if (typeof value !== "string") {
198
+ return undefined;
199
+ }
200
+
201
+ const candidate = value.trim().toLowerCase().replace(/[\s_]+/g, "-");
202
+ return changeableReportStates.find((state) => state === candidate);
203
+ }
204
+
163
205
  function normalizeToolArguments<T extends object>(args: unknown): T {
164
206
  if (!args || typeof args !== "object") {
165
207
  return args as T;
166
208
  }
167
209
 
168
210
  const record = args as Record<string, unknown>;
169
- const reportId = normalizeReportId(record.reportId)
170
- ?? normalizeReportId(record.reportNumber)
171
- ?? normalizeReportId(record.number)
172
- ?? normalizeReportId(record.id);
211
+ const normalized: Record<string, unknown> = { ...record };
212
+ let changed = false;
213
+
214
+ const reportId = parsePositiveInteger(record.reportId)
215
+ ?? parsePositiveInteger(record.reportNumber)
216
+ ?? parsePositiveInteger(record.number)
217
+ ?? parsePositiveInteger(record.id);
218
+ if (reportId !== undefined && record.reportId !== reportId) {
219
+ normalized.reportId = reportId;
220
+ changed = true;
221
+ }
173
222
 
174
- if (reportId === undefined || record.reportId === reportId) {
175
- return args as T;
223
+ const state = normalizeState(record.state);
224
+ if (state !== undefined && record.state !== state) {
225
+ normalized.state = state;
226
+ changed = true;
176
227
  }
177
228
 
178
- return { ...record, reportId } as T;
229
+ return (changed ? normalized : args) as T;
179
230
  }
180
231
 
181
232
  function getProgramHandle(report: Report, fallback?: string): string | undefined {
@@ -215,10 +266,12 @@ async function postComment(options: CommentToolParams, cwd: string): Promise<Act
215
266
  });
216
267
  }
217
268
 
218
- async function triageReport(options: TriageToolParams, cwd: string): Promise<Report> {
269
+ async function changeState(options: StateToolParams, cwd: string): Promise<Report> {
219
270
  const client = createClient(cwd);
220
- return changeReportState(client, options.reportId, ReportState.Triaged, {
271
+ return changeReportState(client, options.reportId, options.state, {
221
272
  message: options.message,
273
+ originalReportId: options.originalReportId,
274
+ attachmentIds: options.attachmentIds,
222
275
  });
223
276
  }
224
277
 
@@ -303,11 +356,16 @@ function formatReportMarkdown(result: FetchReportResult): string {
303
356
  return lines.join("\n");
304
357
  }
305
358
 
306
- function formatTriagedReport(report: Report): string {
359
+ function formatStateChange(report: Report): string {
307
360
  return `# HackerOne report #${report.id}\n\n- State: ${report.attributes.state}`;
308
361
  }
309
362
 
310
363
  function formatError(error: unknown): string {
364
+ // Rejected by the client library before any request was sent.
365
+ if (isAppError(error) && error.code === "VALIDATION_ERROR") {
366
+ return error.message;
367
+ }
368
+
311
369
  if (isAppError(error)) {
312
370
  const retry = error.retryAfter === undefined ? "" : ` Retry after ${error.retryAfter} seconds.`;
313
371
  return `HackerOne API error (${error.code}, HTTP ${error.statusCode}): ${error.message}.${retry}`;
@@ -379,23 +437,25 @@ export default function hackerOneExtension(pi: ExtensionAPI) {
379
437
  });
380
438
 
381
439
  pi.registerTool({
382
- name: TRIAGE_TOOL_NAME,
383
- label: "HackerOne Triage",
384
- description: "Move a HackerOne report to triaged using the HackerOne API.",
385
- promptSnippet: "Move a HackerOne report to triaged by report number/id",
440
+ name: STATE_TOOL_NAME,
441
+ label: "HackerOne Change State",
442
+ description: `Change the state of a HackerOne report: triage it, ask the reporter for more information, close it, or reopen it. The optional message is posted on the report and is visible to the reporter. ${STATE_TRANSITION_RULE}\n\nStates:\n${STATE_DEFINITIONS}`,
443
+ promptSnippet: `Change a HackerOne report's state (${changeableReportStates.join(", ")}) by report number/id`,
386
444
  promptGuidelines: [
387
- "Use hackerone_triage only when the user explicitly requests moving a specific report to triaged.",
388
- "Before using hackerone_triage, ensure the user supplied the report number/id.",
389
- "A state change can notify the reporter; its optional message is visible to the reporter. Use hackerone_comment with internal: true for team-only notes.",
445
+ "Use hackerone_change_state only when the user explicitly asks to change a specific report's state, such as triaging it, requesting more information, closing it as resolved, informative, duplicate, not-applicable, or spam, or reopening it.",
446
+ "Before using hackerone_change_state, ensure the user supplied the report number/id and which state to move it to. If the target state is ambiguous (for example, \"close it\"), ask which closed state they mean.",
447
+ "A state change can notify the reporter, and its message is visible to the reporter. Use hackerone_comment with internal: true for team-only notes.",
448
+ `${MESSAGE_STATES} require a message. For duplicate, set originalReportId when the user names the original report.`,
449
+ "Closing as not-applicable or spam lowers the reporter's reputation, and resolved raises it; informative does not change it.",
390
450
  "Do not call this tool for a request to merely inspect a report.",
391
451
  ],
392
- parameters: triageParameters,
452
+ parameters: stateParameters,
393
453
  prepareArguments: normalizeToolArguments,
394
454
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
395
455
  try {
396
- const report = await triageReport(params, ctx.cwd);
456
+ const report = await changeState(params, ctx.cwd);
397
457
  return {
398
- content: [{ type: "text", text: formatTriagedReport(report) }],
458
+ content: [{ type: "text", text: formatStateChange(report) }],
399
459
  details: report,
400
460
  };
401
461
  } catch (error) {
@@ -432,21 +492,42 @@ export default function hackerOneExtension(pi: ExtensionAPI) {
432
492
  },
433
493
  });
434
494
 
435
- pi.registerCommand("hackerone-triage", {
436
- description: "Move a report to triaged: /hackerone-triage <number> [--message \"text\"]",
495
+ pi.registerCommand("hackerone-state", {
496
+ description: `Change a report's state: ${STATE_COMMAND_USAGE}. ${STATE_TRANSITION_RULE} States:\n${STATE_DEFINITIONS}`,
497
+ // Completes the state after the report number, showing each state's definition.
498
+ getArgumentCompletions: (prefix: string) => {
499
+ const match = /^(\s*\d+\s+)(\S*)$/.exec(prefix);
500
+ if (!match) {
501
+ return null;
502
+ }
503
+
504
+ const [, head, partial] = match;
505
+ const typed = partial.toLowerCase();
506
+ const items = STATE_INFO
507
+ .filter(({ state }) => state.startsWith(typed))
508
+ .map(({ state, summary }) => ({ value: `${head}${state} `, label: state, description: summary }));
509
+ return items.length > 0 ? items : null;
510
+ },
437
511
  handler: async (args, ctx) => {
438
- const parsed = parseTriageArgs(args);
512
+ const parsed = parseStateArgs(args);
439
513
  if (!parsed) {
440
- ctx.ui.notify("Usage: /hackerone-triage <number> [--message \"text\"]", "warning");
514
+ ctx.ui.notify(`Usage: ${STATE_COMMAND_USAGE}\nStates: ${changeableReportStates.join(", ")}`, "warning");
441
515
  return;
442
516
  }
443
517
 
444
518
  try {
445
- ctx.ui.notify(`Triaging HackerOne report #${parsed.reportId}...`, "info");
446
- const report = await triageReport(parsed, ctx.cwd);
519
+ validateStateChange(parsed.state, parsed);
520
+ } catch (error) {
521
+ ctx.ui.notify(formatError(error), "warning");
522
+ return;
523
+ }
524
+
525
+ try {
526
+ ctx.ui.notify(`Moving HackerOne report #${parsed.reportId} to ${parsed.state}...`, "info");
527
+ const report = await changeState(parsed, ctx.cwd);
447
528
  pi.sendMessage({
448
- customType: "hackerone-triage",
449
- content: formatTriagedReport(report),
529
+ customType: "hackerone-state",
530
+ content: formatStateChange(report),
450
531
  display: true,
451
532
  details: report,
452
533
  });
@@ -526,20 +607,59 @@ function tokenizeCommand(input: string): string[] {
526
607
  return tokens;
527
608
  }
528
609
 
529
- function parseTriageArgs(args: string): TriageToolParams | undefined {
610
+ function parseStateArgs(args: string): StateToolParams | undefined {
530
611
  const tokens = tokenizeCommand(args);
531
- const reportId = normalizeReportId(tokens[0]);
532
- if (reportId === undefined) return undefined;
533
- if (tokens.length === 1) return { reportId };
534
- if (tokens.length === 3 && tokens[1] === "--message" && tokens[2]) {
535
- return { reportId, message: tokens[2] };
612
+ const reportId = parsePositiveInteger(tokens[0]);
613
+ const state = normalizeState(tokens[1]);
614
+
615
+ if (reportId === undefined || state === undefined) {
616
+ return undefined;
536
617
  }
537
- return undefined;
618
+
619
+ const options: StateToolParams = { reportId, state };
620
+ for (let index = 2; index < tokens.length; index += 1) {
621
+ const token = tokens[index];
622
+ const value = tokens[index + 1];
623
+
624
+ if (token === "--message") {
625
+ if (!value) {
626
+ return undefined;
627
+ }
628
+ options.message = value;
629
+ index += 1;
630
+ continue;
631
+ }
632
+
633
+ if (token === "--original-report-id") {
634
+ const originalReportId = parsePositiveInteger(value);
635
+ if (originalReportId === undefined) {
636
+ return undefined;
637
+ }
638
+ options.originalReportId = originalReportId;
639
+ index += 1;
640
+ continue;
641
+ }
642
+
643
+ if (token === "--attachment-id") {
644
+ const attachmentId = parsePositiveInteger(value);
645
+ if (attachmentId === undefined) {
646
+ return undefined;
647
+ }
648
+ options.attachmentIds ??= [];
649
+ options.attachmentIds.push(attachmentId);
650
+ index += 1;
651
+ continue;
652
+ }
653
+
654
+ return undefined;
655
+ }
656
+
657
+ return options;
538
658
  }
539
659
 
540
660
  function parseCommentArgs(args: string): CommentToolParams | undefined {
541
661
  const tokens = tokenizeCommand(args);
542
- const reportId = normalizeReportId(tokens[0]);
662
+ const reportId = parsePositiveInteger(tokens[0]);
543
663
 
544
664
  if (reportId === undefined) {
545
665
  return undefined;
@@ -590,7 +710,7 @@ function parseCommentArgs(args: string): CommentToolParams | undefined {
590
710
 
591
711
  function parseCommandArgs(args: string): FetchReportOptions | undefined {
592
712
  const tokens = args.trim().split(/\s+/).filter(Boolean);
593
- const reportId = normalizeReportId(tokens[0]);
713
+ const reportId = parsePositiveInteger(tokens[0]);
594
714
 
595
715
  if (reportId === undefined) {
596
716
  return undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-hackerone",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Pi package that adds a HackerOne report tool and slash command.",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -20,7 +20,7 @@
20
20
  "typecheck": "tsc --noEmit"
21
21
  },
22
22
  "dependencies": {
23
- "@matteo.collina/hackerone": "^0.3.0"
23
+ "@matteo.collina/hackerone": "^0.4.0"
24
24
  },
25
25
  "peerDependencies": {
26
26
  "@earendil-works/pi-coding-agent": "*",