pi-hackerone 0.3.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 a HackerOne report fetcher and commenter 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,6 +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_change_state`
71
+
72
+ Change a specific report's state when explicitly requested: triage it, ask the reporter for more information, close it, or reopen it.
73
+
74
+ ```text
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.
78
+ ```
79
+
80
+ Parameters:
81
+
82
+ - `reportId` - HackerOne report number/id.
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.
87
+
88
+ This action requires the API user's Report Management permission and may notify the reporter.
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
+
70
106
  ### Command: `/hackerone-report`
71
107
 
72
108
  Fetch a report directly from the pi prompt:
@@ -78,6 +114,20 @@ Fetch a report directly from the pi prompt:
78
114
 
79
115
  The command inserts the fetched report into the session as a displayed custom message.
80
116
 
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.
120
+
121
+ ```text
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
127
+ ```
128
+
129
+ Use any state from [Report states](#report-states). The command inserts the updated report state into the session.
130
+
81
131
  ### Command: `/hackerone-comment`
82
132
 
83
133
  Post a comment directly from the pi prompt:
@@ -4,18 +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
+ changeReportState,
8
+ changeableReportStates,
7
9
  createComment,
8
10
  filterComments,
9
11
  getReport,
10
12
  isAppError,
11
13
  listAllActivities,
14
+ reportStates,
15
+ validateStateChange,
12
16
  type Activity,
17
+ type ChangeableReportState,
13
18
  type Report,
14
19
  } from "@matteo.collina/hackerone";
15
20
  import { Type } from "typebox";
16
21
 
17
22
  const TOOL_NAME = "hackerone_report";
18
23
  const COMMENT_TOOL_NAME = "hackerone_comment";
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]";
19
36
 
20
37
  const reportParameters = Type.Object({
21
38
  reportId: Type.Integer({
@@ -64,6 +81,39 @@ interface CommentToolParams {
64
81
  attachmentIds?: number[];
65
82
  }
66
83
 
84
+ const stateParameters = Type.Object({
85
+ reportId: Type.Integer({
86
+ minimum: 1,
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}`,
94
+ }),
95
+ message: Type.Optional(Type.String({
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.",
106
+ })),
107
+ });
108
+
109
+ interface StateToolParams {
110
+ reportId: number;
111
+ state: ChangeableReportState;
112
+ message?: string;
113
+ originalReportId?: number;
114
+ attachmentIds?: number[];
115
+ }
116
+
67
117
  interface FetchReportResult {
68
118
  report: Report;
69
119
  comments?: Activity[];
@@ -130,7 +180,7 @@ function createClient(cwd: string): HackerOneClient {
130
180
  return new HackerOneClient(readCredentials(cwd));
131
181
  }
132
182
 
133
- function normalizeReportId(value: unknown): number | undefined {
183
+ function parsePositiveInteger(value: unknown): number | undefined {
134
184
  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
135
185
  return value;
136
186
  }
@@ -142,22 +192,41 @@ function normalizeReportId(value: unknown): number | undefined {
142
192
  return undefined;
143
193
  }
144
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
+
145
205
  function normalizeToolArguments<T extends object>(args: unknown): T {
146
206
  if (!args || typeof args !== "object") {
147
207
  return args as T;
148
208
  }
149
209
 
150
210
  const record = args as Record<string, unknown>;
151
- const reportId = normalizeReportId(record.reportId)
152
- ?? normalizeReportId(record.reportNumber)
153
- ?? normalizeReportId(record.number)
154
- ?? 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
+ }
155
222
 
156
- if (reportId === undefined || record.reportId === reportId) {
157
- return args as T;
223
+ const state = normalizeState(record.state);
224
+ if (state !== undefined && record.state !== state) {
225
+ normalized.state = state;
226
+ changed = true;
158
227
  }
159
228
 
160
- return { ...record, reportId } as T;
229
+ return (changed ? normalized : args) as T;
161
230
  }
162
231
 
163
232
  function getProgramHandle(report: Report, fallback?: string): string | undefined {
@@ -197,6 +266,15 @@ async function postComment(options: CommentToolParams, cwd: string): Promise<Act
197
266
  });
198
267
  }
199
268
 
269
+ async function changeState(options: StateToolParams, cwd: string): Promise<Report> {
270
+ const client = createClient(cwd);
271
+ return changeReportState(client, options.reportId, options.state, {
272
+ message: options.message,
273
+ originalReportId: options.originalReportId,
274
+ attachmentIds: options.attachmentIds,
275
+ });
276
+ }
277
+
200
278
  function formatActor(activity: Activity): string {
201
279
  const actor = activity.relationships?.actor?.data;
202
280
  return actor?.attributes?.username ?? actor?.attributes?.handle ?? actor?.id ?? "unknown";
@@ -278,7 +356,16 @@ function formatReportMarkdown(result: FetchReportResult): string {
278
356
  return lines.join("\n");
279
357
  }
280
358
 
359
+ function formatStateChange(report: Report): string {
360
+ return `# HackerOne report #${report.id}\n\n- State: ${report.attributes.state}`;
361
+ }
362
+
281
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
+
282
369
  if (isAppError(error)) {
283
370
  const retry = error.retryAfter === undefined ? "" : ` Retry after ${error.retryAfter} seconds.`;
284
371
  return `HackerOne API error (${error.code}, HTTP ${error.statusCode}): ${error.message}.${retry}`;
@@ -349,6 +436,38 @@ export default function hackerOneExtension(pi: ExtensionAPI) {
349
436
  },
350
437
  });
351
438
 
439
+ pi.registerTool({
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`,
444
+ promptGuidelines: [
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.",
450
+ "Do not call this tool for a request to merely inspect a report.",
451
+ ],
452
+ parameters: stateParameters,
453
+ prepareArguments: normalizeToolArguments,
454
+ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
455
+ try {
456
+ const report = await changeState(params, ctx.cwd);
457
+ return {
458
+ content: [{ type: "text", text: formatStateChange(report) }],
459
+ details: report,
460
+ };
461
+ } catch (error) {
462
+ return {
463
+ content: [{ type: "text", text: formatError(error) }],
464
+ isError: true,
465
+ details: undefined,
466
+ };
467
+ }
468
+ },
469
+ });
470
+
352
471
  pi.registerCommand("hackerone-report", {
353
472
  description: "Fetch a HackerOne report: /hackerone-report <number> [--comments] [--program handle]",
354
473
  handler: async (args, ctx) => {
@@ -373,6 +492,51 @@ export default function hackerOneExtension(pi: ExtensionAPI) {
373
492
  },
374
493
  });
375
494
 
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
+ },
511
+ handler: async (args, ctx) => {
512
+ const parsed = parseStateArgs(args);
513
+ if (!parsed) {
514
+ ctx.ui.notify(`Usage: ${STATE_COMMAND_USAGE}\nStates: ${changeableReportStates.join(", ")}`, "warning");
515
+ return;
516
+ }
517
+
518
+ try {
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);
528
+ pi.sendMessage({
529
+ customType: "hackerone-state",
530
+ content: formatStateChange(report),
531
+ display: true,
532
+ details: report,
533
+ });
534
+ } catch (error) {
535
+ ctx.ui.notify(formatError(error), "error");
536
+ }
537
+ },
538
+ });
539
+
376
540
  pi.registerCommand("hackerone-comment", {
377
541
  description: "Post a comment on a HackerOne report: /hackerone-comment <number> --message \"text\" [--internal] [--attachment-id id]",
378
542
  handler: async (args, ctx) => {
@@ -443,9 +607,59 @@ function tokenizeCommand(input: string): string[] {
443
607
  return tokens;
444
608
  }
445
609
 
610
+ function parseStateArgs(args: string): StateToolParams | undefined {
611
+ const tokens = tokenizeCommand(args);
612
+ const reportId = parsePositiveInteger(tokens[0]);
613
+ const state = normalizeState(tokens[1]);
614
+
615
+ if (reportId === undefined || state === undefined) {
616
+ return undefined;
617
+ }
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;
658
+ }
659
+
446
660
  function parseCommentArgs(args: string): CommentToolParams | undefined {
447
661
  const tokens = tokenizeCommand(args);
448
- const reportId = normalizeReportId(tokens[0]);
662
+ const reportId = parsePositiveInteger(tokens[0]);
449
663
 
450
664
  if (reportId === undefined) {
451
665
  return undefined;
@@ -496,7 +710,7 @@ function parseCommentArgs(args: string): CommentToolParams | undefined {
496
710
 
497
711
  function parseCommandArgs(args: string): FetchReportOptions | undefined {
498
712
  const tokens = args.trim().split(/\s+/).filter(Boolean);
499
- const reportId = normalizeReportId(tokens[0]);
713
+ const reportId = parsePositiveInteger(tokens[0]);
500
714
 
501
715
  if (reportId === undefined) {
502
716
  return undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-hackerone",
3
- "version": "0.3.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": [
@@ -16,10 +16,11 @@
16
16
  "README.md"
17
17
  ],
18
18
  "scripts": {
19
+ "test": "node --test 'test/*.test.mjs'",
19
20
  "typecheck": "tsc --noEmit"
20
21
  },
21
22
  "dependencies": {
22
- "@matteo.collina/hackerone": "^0.2.0"
23
+ "@matteo.collina/hackerone": "^0.4.0"
23
24
  },
24
25
  "peerDependencies": {
25
26
  "@earendil-works/pi-coding-agent": "*",
@@ -29,7 +30,8 @@
29
30
  "@earendil-works/pi-coding-agent": "*",
30
31
  "@types/node": "^24.0.0",
31
32
  "typebox": "*",
32
- "typescript": "^5.9.0"
33
+ "typescript": "^5.9.0",
34
+ "undici": "^7.30.2"
33
35
  },
34
36
  "pi": {
35
37
  "extensions": [