pi-hackerone 0.1.1 → 0.5.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 powered by [`@matteo.collina/hackerone`](https://www.npmjs.com/package/@matteo.collina/hackerone).
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).
4
4
 
5
5
  ## Install
6
6
 
@@ -52,6 +52,36 @@ Parameters:
52
52
  - `includeComments` - Fetch comments from the activity API.
53
53
  - `program` - Program handle override, useful when fetching comments.
54
54
 
55
+ ### Tool: `hackerone_comment`
56
+
57
+ The agent can call this tool to post a comment on a report:
58
+
59
+ ```text
60
+ Post a public comment on HackerOne report 12345 saying the fix is deployed.
61
+ ```
62
+
63
+ Parameters:
64
+
65
+ - `reportId` - HackerOne report number/id.
66
+ - `message` - The comment message to post.
67
+ - `internal` - Post as an internal (team-only) comment instead of a public one.
68
+ - `attachmentIds` - Optional attachment IDs to attach to the comment.
69
+
70
+ ### Tool: `hackerone_triage`
71
+
72
+ Move a specific report to triaged when explicitly requested:
73
+
74
+ ```text
75
+ Move HackerOne report 12345 to triaged.
76
+ ```
77
+
78
+ Parameters:
79
+
80
+ - `reportId` - HackerOne report number/id.
81
+ - `message` - Optional public message visible to the reporter; use `hackerone_comment` with `internal: true` for team-only notes.
82
+
83
+ This action requires the API user's Report Management permission and may notify the reporter.
84
+
55
85
  ### Command: `/hackerone-report`
56
86
 
57
87
  Fetch a report directly from the pi prompt:
@@ -63,4 +93,25 @@ Fetch a report directly from the pi prompt:
63
93
 
64
94
  The command inserts the fetched report into the session as a displayed custom message.
65
95
 
96
+ ### Command: `/hackerone-triage`
97
+
98
+ ```text
99
+ /hackerone-triage 12345
100
+ /hackerone-triage 12345 --message "Confirmed"
101
+ ```
102
+
103
+ The command inserts the updated report state into the session.
104
+
105
+ ### Command: `/hackerone-comment`
106
+
107
+ Post a comment directly from the pi prompt:
108
+
109
+ ```text
110
+ /hackerone-comment 12345 --message "A fix has been deployed, can you retest?"
111
+ /hackerone-comment 12345 --message "Internal triage note" --internal
112
+ /hackerone-comment 12345 --message "See attached POC" --attachment-id 42
113
+ ```
114
+
115
+ When a comment is posted, the inserted message is a Markdown summary of the posted comment.
116
+
66
117
  > HackerOne reports can contain sensitive vulnerability details and attachments metadata. Only load this extension in trusted pi sessions.
@@ -4,6 +4,9 @@ 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
+ changeReportState,
9
+ createComment,
7
10
  filterComments,
8
11
  getReport,
9
12
  isAppError,
@@ -14,6 +17,8 @@ import {
14
17
  import { Type } from "typebox";
15
18
 
16
19
  const TOOL_NAME = "hackerone_report";
20
+ const COMMENT_TOOL_NAME = "hackerone_comment";
21
+ const TRIAGE_TOOL_NAME = "hackerone_triage";
17
22
 
18
23
  const reportParameters = Type.Object({
19
24
  reportId: Type.Integer({
@@ -35,7 +40,47 @@ interface FetchReportOptions {
35
40
  program?: string;
36
41
  }
37
42
 
38
- type ReportToolParams = FetchReportOptions;
43
+ const commentParameters = Type.Object({
44
+ reportId: Type.Integer({
45
+ minimum: 1,
46
+ description: "HackerOne report number/id to comment on.",
47
+ }),
48
+ message: Type.String({
49
+ minLength: 1,
50
+ description: "The comment message to post.",
51
+ }),
52
+ internal: Type.Optional(Type.Boolean({
53
+ default: false,
54
+ description: "Post as an internal (team-only) comment instead of a public one.",
55
+ })),
56
+ attachmentIds: Type.Optional(Type.Array(Type.Integer({
57
+ minimum: 1,
58
+ }), {
59
+ description: "Optional attachment IDs to attach to the comment.",
60
+ })),
61
+ });
62
+
63
+ interface CommentToolParams {
64
+ reportId: number;
65
+ message: string;
66
+ internal?: boolean;
67
+ attachmentIds?: number[];
68
+ }
69
+
70
+ const triageParameters = Type.Object({
71
+ reportId: Type.Integer({
72
+ minimum: 1,
73
+ description: "HackerOne report number/id to move to triaged.",
74
+ }),
75
+ message: Type.Optional(Type.String({
76
+ description: "Optional public message visible to the reporter when the state changes. Do not include team-only notes.",
77
+ })),
78
+ });
79
+
80
+ interface TriageToolParams {
81
+ reportId: number;
82
+ message?: string;
83
+ }
39
84
 
40
85
  interface FetchReportResult {
41
86
  report: Report;
@@ -115,9 +160,9 @@ function normalizeReportId(value: unknown): number | undefined {
115
160
  return undefined;
116
161
  }
117
162
 
118
- function normalizeToolArguments(args: unknown): ReportToolParams {
163
+ function normalizeToolArguments<T extends object>(args: unknown): T {
119
164
  if (!args || typeof args !== "object") {
120
- return args as ReportToolParams;
165
+ return args as T;
121
166
  }
122
167
 
123
168
  const record = args as Record<string, unknown>;
@@ -127,10 +172,10 @@ function normalizeToolArguments(args: unknown): ReportToolParams {
127
172
  ?? normalizeReportId(record.id);
128
173
 
129
174
  if (reportId === undefined || record.reportId === reportId) {
130
- return args as ReportToolParams;
175
+ return args as T;
131
176
  }
132
177
 
133
- return { ...record, reportId } as ReportToolParams;
178
+ return { ...record, reportId } as T;
134
179
  }
135
180
 
136
181
  function getProgramHandle(report: Report, fallback?: string): string | undefined {
@@ -161,11 +206,43 @@ async function fetchReport(options: FetchReportOptions, cwd: string): Promise<Fe
161
206
  return { report, comments, programHandle, warnings };
162
207
  }
163
208
 
209
+ async function postComment(options: CommentToolParams, cwd: string): Promise<Activity> {
210
+ const client = createClient(cwd);
211
+ return createComment(client, options.reportId, {
212
+ message: options.message,
213
+ internal: options.internal ?? false,
214
+ attachmentIds: options.attachmentIds,
215
+ });
216
+ }
217
+
218
+ async function triageReport(options: TriageToolParams, cwd: string): Promise<Report> {
219
+ const client = createClient(cwd);
220
+ return changeReportState(client, options.reportId, ReportState.Triaged, {
221
+ message: options.message,
222
+ });
223
+ }
224
+
164
225
  function formatActor(activity: Activity): string {
165
226
  const actor = activity.relationships?.actor?.data;
166
227
  return actor?.attributes?.username ?? actor?.attributes?.handle ?? actor?.id ?? "unknown";
167
228
  }
168
229
 
230
+ function formatCommentMarkdown(comment: Activity, reportId: number): string {
231
+ const actor = comment.relationships?.actor?.data;
232
+ const actorName = actor?.attributes?.username ?? actor?.attributes?.handle ?? actor?.id ?? "unknown";
233
+ const visibility = comment.attributes.internal ? "internal" : "public";
234
+ const lines = [
235
+ `# Comment posted on report #${reportId}`,
236
+ "",
237
+ `- Visibility: ${visibility}`,
238
+ `- Author: ${actorName}`,
239
+ `- Created: ${comment.attributes.created_at}`,
240
+ "",
241
+ comment.attributes.message ?? "_(empty comment)_",
242
+ ];
243
+ return lines.join("\n");
244
+ }
245
+
169
246
  function formatReportMarkdown(result: FetchReportResult): string {
170
247
  const { report, comments, programHandle, warnings } = result;
171
248
  const reporter = report.relationships.reporter?.data;
@@ -226,6 +303,10 @@ function formatReportMarkdown(result: FetchReportResult): string {
226
303
  return lines.join("\n");
227
304
  }
228
305
 
306
+ function formatTriagedReport(report: Report): string {
307
+ return `# HackerOne report #${report.id}\n\n- State: ${report.attributes.state}`;
308
+ }
309
+
229
310
  function formatError(error: unknown): string {
230
311
  if (isAppError(error)) {
231
312
  const retry = error.retryAfter === undefined ? "" : ` Retry after ${error.retryAfter} seconds.`;
@@ -268,6 +349,65 @@ export default function hackerOneExtension(pi: ExtensionAPI) {
268
349
  },
269
350
  });
270
351
 
352
+ pi.registerTool({
353
+ name: COMMENT_TOOL_NAME,
354
+ label: "HackerOne Comment",
355
+ description: "Post a public or internal comment on a HackerOne report using the HackerOne API.",
356
+ promptSnippet: "Post a comment on a HackerOne report by report number/id",
357
+ promptGuidelines: [
358
+ "Use hackerone_comment when the user wants to add a comment to a HackerOne report.",
359
+ "Before using hackerone_comment, ensure the user provided the report number/id and the comment message.",
360
+ "Set internal to true when the comment should only be visible to the program's team.",
361
+ ],
362
+ parameters: commentParameters,
363
+ prepareArguments: normalizeToolArguments,
364
+ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
365
+ try {
366
+ const result = { comment: await postComment(params, ctx.cwd), reportId: params.reportId };
367
+ return {
368
+ content: [{ type: "text", text: formatCommentMarkdown(result.comment, result.reportId) }],
369
+ details: result,
370
+ };
371
+ } catch (error) {
372
+ return {
373
+ content: [{ type: "text", text: formatError(error) }],
374
+ isError: true,
375
+ details: undefined,
376
+ };
377
+ }
378
+ },
379
+ });
380
+
381
+ 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",
386
+ 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.",
390
+ "Do not call this tool for a request to merely inspect a report.",
391
+ ],
392
+ parameters: triageParameters,
393
+ prepareArguments: normalizeToolArguments,
394
+ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
395
+ try {
396
+ const report = await triageReport(params, ctx.cwd);
397
+ return {
398
+ content: [{ type: "text", text: formatTriagedReport(report) }],
399
+ details: report,
400
+ };
401
+ } catch (error) {
402
+ return {
403
+ content: [{ type: "text", text: formatError(error) }],
404
+ isError: true,
405
+ details: undefined,
406
+ };
407
+ }
408
+ },
409
+ });
410
+
271
411
  pi.registerCommand("hackerone-report", {
272
412
  description: "Fetch a HackerOne report: /hackerone-report <number> [--comments] [--program handle]",
273
413
  handler: async (args, ctx) => {
@@ -291,6 +431,161 @@ export default function hackerOneExtension(pi: ExtensionAPI) {
291
431
  }
292
432
  },
293
433
  });
434
+
435
+ pi.registerCommand("hackerone-triage", {
436
+ description: "Move a report to triaged: /hackerone-triage <number> [--message \"text\"]",
437
+ handler: async (args, ctx) => {
438
+ const parsed = parseTriageArgs(args);
439
+ if (!parsed) {
440
+ ctx.ui.notify("Usage: /hackerone-triage <number> [--message \"text\"]", "warning");
441
+ return;
442
+ }
443
+
444
+ try {
445
+ ctx.ui.notify(`Triaging HackerOne report #${parsed.reportId}...`, "info");
446
+ const report = await triageReport(parsed, ctx.cwd);
447
+ pi.sendMessage({
448
+ customType: "hackerone-triage",
449
+ content: formatTriagedReport(report),
450
+ display: true,
451
+ details: report,
452
+ });
453
+ } catch (error) {
454
+ ctx.ui.notify(formatError(error), "error");
455
+ }
456
+ },
457
+ });
458
+
459
+ pi.registerCommand("hackerone-comment", {
460
+ description: "Post a comment on a HackerOne report: /hackerone-comment <number> --message \"text\" [--internal] [--attachment-id id]",
461
+ handler: async (args, ctx) => {
462
+ const parsed = parseCommentArgs(args);
463
+ if (!parsed) {
464
+ ctx.ui.notify(
465
+ "Usage: /hackerone-comment <number> --message \"text\" [--internal] [--attachment-id id]",
466
+ "warning",
467
+ );
468
+ return;
469
+ }
470
+
471
+ try {
472
+ ctx.ui.notify(`Posting comment on HackerOne report #${parsed.reportId}...`, "info");
473
+ const comment = await postComment(parsed, ctx.cwd);
474
+ pi.sendMessage({
475
+ customType: "hackerone-comment",
476
+ content: formatCommentMarkdown(comment, parsed.reportId),
477
+ display: true,
478
+ details: { comment, reportId: parsed.reportId },
479
+ });
480
+ } catch (error) {
481
+ ctx.ui.notify(formatError(error), "error");
482
+ }
483
+ },
484
+ });
485
+ }
486
+
487
+ function tokenizeCommand(input: string): string[] {
488
+ const tokens: string[] = [];
489
+ let current = "";
490
+ let inSingle = false;
491
+ let inDouble = false;
492
+ let escaping = false;
493
+
494
+ for (const ch of input) {
495
+ if (escaping) {
496
+ current += ch;
497
+ escaping = false;
498
+ continue;
499
+ }
500
+ if (ch === "\\") {
501
+ escaping = true;
502
+ continue;
503
+ }
504
+ if (ch === "'" && !inDouble) {
505
+ inSingle = !inSingle;
506
+ continue;
507
+ }
508
+ if (ch === '"' && !inSingle) {
509
+ inDouble = !inDouble;
510
+ continue;
511
+ }
512
+ if (/\s/.test(ch) && !inSingle && !inDouble) {
513
+ if (current) {
514
+ tokens.push(current);
515
+ current = "";
516
+ }
517
+ continue;
518
+ }
519
+ current += ch;
520
+ }
521
+
522
+ if (current) {
523
+ tokens.push(current);
524
+ }
525
+
526
+ return tokens;
527
+ }
528
+
529
+ function parseTriageArgs(args: string): TriageToolParams | undefined {
530
+ 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] };
536
+ }
537
+ return undefined;
538
+ }
539
+
540
+ function parseCommentArgs(args: string): CommentToolParams | undefined {
541
+ const tokens = tokenizeCommand(args);
542
+ const reportId = normalizeReportId(tokens[0]);
543
+
544
+ if (reportId === undefined) {
545
+ return undefined;
546
+ }
547
+
548
+ const options: Partial<CommentToolParams> = { reportId };
549
+ for (let index = 1; index < tokens.length; index += 1) {
550
+ const token = tokens[index];
551
+ if (token === "--internal") {
552
+ options.internal = true;
553
+ continue;
554
+ }
555
+
556
+ if (token === "--message") {
557
+ const message = tokens[index + 1];
558
+ if (!message) {
559
+ return undefined;
560
+ }
561
+ options.message = message;
562
+ index += 1;
563
+ continue;
564
+ }
565
+
566
+ if (token === "--attachment-id") {
567
+ const value = tokens[index + 1];
568
+ if (!value) {
569
+ return undefined;
570
+ }
571
+ const attachmentId = Number.parseInt(value, 10);
572
+ if (!Number.isInteger(attachmentId) || attachmentId < 1) {
573
+ return undefined;
574
+ }
575
+ options.attachmentIds ??= [];
576
+ options.attachmentIds.push(attachmentId);
577
+ index += 1;
578
+ continue;
579
+ }
580
+
581
+ return undefined;
582
+ }
583
+
584
+ if (!options.message) {
585
+ return undefined;
586
+ }
587
+
588
+ return options as CommentToolParams;
294
589
  }
295
590
 
296
591
  function parseCommandArgs(args: string): FetchReportOptions | undefined {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-hackerone",
3
- "version": "0.1.1",
3
+ "version": "0.5.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.1.0"
23
+ "@matteo.collina/hackerone": "^0.3.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": [