pi-hackerone 0.1.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 +72 -0
- package/extensions/hackerone.ts +326 -0
- package/package.json +39 -0
package/README.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# pi-hackerone
|
|
2
|
+
|
|
3
|
+
A pi package that adds a HackerOne report fetcher powered by [`@matteo.collina/hackerone`](https://www.npmjs.com/package/@matteo.collina/hackerone).
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm install
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Configure credentials in pi settings. Global settings live at `~/.pi/agent/settings.json`; project settings live at `.pi/settings.json` and override global settings.
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"hackerone": {
|
|
16
|
+
"apiIdentifier": "your_api_identifier",
|
|
17
|
+
"apiToken": "your_api_token",
|
|
18
|
+
"baseUrl": "https://api.hackerone.com/v1"
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`baseUrl` is optional. Environment variables still work and take precedence:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
export HACKERONE_API_IDENTIFIER="your_api_identifier"
|
|
27
|
+
export HACKERONE_API_TOKEN="your_api_token"
|
|
28
|
+
export HACKERONE_API_BASE_URL="https://api.hackerone.com/v1"
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Use locally
|
|
32
|
+
|
|
33
|
+
From this repository:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
pi -e ./extensions/hackerone.ts
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Or install as a local pi package:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
pi install .
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## What it adds
|
|
46
|
+
|
|
47
|
+
### Tool: `hackerone_report`
|
|
48
|
+
|
|
49
|
+
The agent can call this tool when you ask for a report by number, for example:
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
Pull HackerOne report 12345 and summarize the impact.
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Parameters:
|
|
56
|
+
|
|
57
|
+
- `reportId` - HackerOne report number/id.
|
|
58
|
+
- `includeComments` - Fetch comments from the activity API.
|
|
59
|
+
- `program` - Program handle override, useful when fetching comments.
|
|
60
|
+
|
|
61
|
+
### Command: `/hackerone-report`
|
|
62
|
+
|
|
63
|
+
Fetch a report directly from the pi prompt:
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
/hackerone-report 12345
|
|
67
|
+
/hackerone-report 12345 --comments --program myprogram
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The command inserts the fetched report into the session as a displayed custom message.
|
|
71
|
+
|
|
72
|
+
> HackerOne reports can contain sensitive vulnerability details and attachments metadata. Only load this extension in trusted pi sessions.
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
5
|
+
import {
|
|
6
|
+
HackerOneClient,
|
|
7
|
+
filterComments,
|
|
8
|
+
getReport,
|
|
9
|
+
isAppError,
|
|
10
|
+
listAllActivities,
|
|
11
|
+
type Activity,
|
|
12
|
+
type Report,
|
|
13
|
+
} from "@matteo.collina/hackerone";
|
|
14
|
+
import { Type } from "typebox";
|
|
15
|
+
|
|
16
|
+
const TOOL_NAME = "hackerone_report";
|
|
17
|
+
|
|
18
|
+
const reportParameters = Type.Object({
|
|
19
|
+
reportId: Type.Integer({
|
|
20
|
+
minimum: 1,
|
|
21
|
+
description: "HackerOne report number/id to fetch.",
|
|
22
|
+
}),
|
|
23
|
+
includeComments: Type.Optional(Type.Boolean({
|
|
24
|
+
default: false,
|
|
25
|
+
description: "Fetch report comments from HackerOne's activity API when possible.",
|
|
26
|
+
})),
|
|
27
|
+
program: Type.Optional(Type.String({
|
|
28
|
+
description: "Program handle override. Usually inferred from the report; useful when fetching comments.",
|
|
29
|
+
})),
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
interface FetchReportOptions {
|
|
33
|
+
reportId: number;
|
|
34
|
+
includeComments?: boolean;
|
|
35
|
+
program?: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
type ReportToolParams = FetchReportOptions;
|
|
39
|
+
|
|
40
|
+
interface FetchReportResult {
|
|
41
|
+
report: Report;
|
|
42
|
+
comments?: Activity[];
|
|
43
|
+
programHandle?: string;
|
|
44
|
+
warnings: string[];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
interface Credentials {
|
|
48
|
+
apiIdentifier: string;
|
|
49
|
+
apiToken: string;
|
|
50
|
+
baseUrl?: string;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
type HackerOneSettings = Partial<Credentials>;
|
|
54
|
+
|
|
55
|
+
function readSettingsFile(path: string): HackerOneSettings {
|
|
56
|
+
try {
|
|
57
|
+
const raw = JSON.parse(readFileSync(path, "utf8")) as { hackerone?: unknown };
|
|
58
|
+
if (!raw.hackerone || typeof raw.hackerone !== "object") {
|
|
59
|
+
return {};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const settings = raw.hackerone as Record<string, unknown>;
|
|
63
|
+
return {
|
|
64
|
+
apiIdentifier: typeof settings.apiIdentifier === "string" ? settings.apiIdentifier : undefined,
|
|
65
|
+
apiToken: typeof settings.apiToken === "string" ? settings.apiToken : undefined,
|
|
66
|
+
baseUrl: typeof settings.baseUrl === "string" ? settings.baseUrl : undefined,
|
|
67
|
+
};
|
|
68
|
+
} catch {
|
|
69
|
+
return {};
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function readSettingsCredentials(cwd: string): HackerOneSettings {
|
|
74
|
+
const agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
|
|
75
|
+
const globalSettings = readSettingsFile(join(agentDir, "settings.json"));
|
|
76
|
+
const projectSettings = readSettingsFile(join(cwd, ".pi", "settings.json"));
|
|
77
|
+
|
|
78
|
+
return {
|
|
79
|
+
...globalSettings,
|
|
80
|
+
...projectSettings,
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function readCredentials(cwd: string): Credentials {
|
|
85
|
+
const settings = readSettingsCredentials(cwd);
|
|
86
|
+
const apiIdentifier = process.env.HACKERONE_API_IDENTIFIER ?? settings.apiIdentifier;
|
|
87
|
+
const apiToken = process.env.HACKERONE_API_TOKEN ?? settings.apiToken;
|
|
88
|
+
|
|
89
|
+
if (!apiIdentifier || !apiToken) {
|
|
90
|
+
throw new Error(
|
|
91
|
+
"Missing HackerOne credentials. Set hackerone.apiIdentifier and hackerone.apiToken in pi settings.json, or set HACKERONE_API_IDENTIFIER and HACKERONE_API_TOKEN.",
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
return {
|
|
96
|
+
apiIdentifier,
|
|
97
|
+
apiToken,
|
|
98
|
+
baseUrl: process.env.HACKERONE_API_BASE_URL ?? settings.baseUrl,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function createClient(cwd: string): HackerOneClient {
|
|
103
|
+
return new HackerOneClient(readCredentials(cwd));
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function normalizeReportId(value: unknown): number | undefined {
|
|
107
|
+
if (typeof value === "number" && Number.isInteger(value) && value > 0) {
|
|
108
|
+
return value;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
if (typeof value === "string" && /^\d+$/.test(value.trim())) {
|
|
112
|
+
return Number.parseInt(value.trim(), 10);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
return undefined;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function normalizeToolArguments(args: unknown): ReportToolParams {
|
|
119
|
+
if (!args || typeof args !== "object") {
|
|
120
|
+
return args as ReportToolParams;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const record = args as Record<string, unknown>;
|
|
124
|
+
const reportId = normalizeReportId(record.reportId)
|
|
125
|
+
?? normalizeReportId(record.reportNumber)
|
|
126
|
+
?? normalizeReportId(record.number)
|
|
127
|
+
?? normalizeReportId(record.id);
|
|
128
|
+
|
|
129
|
+
if (reportId === undefined || record.reportId === reportId) {
|
|
130
|
+
return args as ReportToolParams;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
return { ...record, reportId } as ReportToolParams;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function getProgramHandle(report: Report, fallback?: string): string | undefined {
|
|
137
|
+
return fallback ?? report.relationships.program.data.attributes?.handle;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
async function fetchReport(options: FetchReportOptions, cwd: string): Promise<FetchReportResult> {
|
|
141
|
+
const client = createClient(cwd);
|
|
142
|
+
const report = await getReport(client, options.reportId);
|
|
143
|
+
const programHandle = getProgramHandle(report, options.program);
|
|
144
|
+
const warnings: string[] = [];
|
|
145
|
+
let comments: Activity[] | undefined;
|
|
146
|
+
|
|
147
|
+
if (options.includeComments) {
|
|
148
|
+
if (programHandle) {
|
|
149
|
+
const activities: Activity[] = [];
|
|
150
|
+
for await (const activity of listAllActivities(client, programHandle, { reportId: options.reportId })) {
|
|
151
|
+
activities.push(activity);
|
|
152
|
+
}
|
|
153
|
+
comments = filterComments(activities);
|
|
154
|
+
} else {
|
|
155
|
+
warnings.push(
|
|
156
|
+
"Could not fetch comments because no program handle was provided or found on the report.",
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
return { report, comments, programHandle, warnings };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function formatActor(activity: Activity): string {
|
|
165
|
+
const actor = activity.relationships?.actor?.data;
|
|
166
|
+
return actor?.attributes?.username ?? actor?.attributes?.handle ?? actor?.id ?? "unknown";
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
function formatReportMarkdown(result: FetchReportResult): string {
|
|
170
|
+
const { report, comments, programHandle, warnings } = result;
|
|
171
|
+
const reporter = report.relationships.reporter?.data;
|
|
172
|
+
const reporterName = reporter?.attributes?.username ?? reporter?.attributes?.handle ?? reporter?.id ?? "unknown";
|
|
173
|
+
const attachments = report.relationships.attachments?.data ?? [];
|
|
174
|
+
const lines = [
|
|
175
|
+
`# HackerOne report #${report.id}: ${report.attributes.title}`,
|
|
176
|
+
"",
|
|
177
|
+
`- State: ${report.attributes.state}`,
|
|
178
|
+
`- Severity: ${report.attributes.severity_rating ?? "unknown"}`,
|
|
179
|
+
`- Program: ${programHandle ?? report.relationships.program.data.id}`,
|
|
180
|
+
`- Reporter: ${reporterName}`,
|
|
181
|
+
`- Submitted: ${report.attributes.submitted_at}`,
|
|
182
|
+
`- Created: ${report.attributes.created_at}`,
|
|
183
|
+
`- Triaged: ${report.attributes.triaged_at ?? "not triaged"}`,
|
|
184
|
+
`- Closed: ${report.attributes.closed_at ?? "not closed"}`,
|
|
185
|
+
`- Last activity: ${report.attributes.last_activity_at ?? "unknown"}`,
|
|
186
|
+
`- Attachments: ${attachments.length}`,
|
|
187
|
+
"",
|
|
188
|
+
"## Vulnerability information",
|
|
189
|
+
"",
|
|
190
|
+
report.attributes.vulnerability_information || "_(empty)_",
|
|
191
|
+
];
|
|
192
|
+
|
|
193
|
+
if (attachments.length > 0) {
|
|
194
|
+
lines.push("", "## Attachments", "");
|
|
195
|
+
for (const attachment of attachments) {
|
|
196
|
+
lines.push(
|
|
197
|
+
`- ${attachment.attributes.file_name} (${attachment.attributes.content_type}, ${attachment.attributes.file_size} bytes)`,
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
if (comments) {
|
|
203
|
+
lines.push("", "## Comments", "");
|
|
204
|
+
if (comments.length === 0) {
|
|
205
|
+
lines.push("_(no comments found)_");
|
|
206
|
+
} else {
|
|
207
|
+
for (const comment of comments) {
|
|
208
|
+
const visibility = comment.attributes.internal ? "internal" : "external";
|
|
209
|
+
lines.push(
|
|
210
|
+
`### ${comment.attributes.created_at} — ${formatActor(comment)} (${visibility})`,
|
|
211
|
+
"",
|
|
212
|
+
comment.attributes.message ?? "_(empty comment)_",
|
|
213
|
+
"",
|
|
214
|
+
);
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
if (warnings.length > 0) {
|
|
220
|
+
lines.push("", "## Warnings", "");
|
|
221
|
+
for (const warning of warnings) {
|
|
222
|
+
lines.push(`- ${warning}`);
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
return lines.join("\n");
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
function formatError(error: unknown): string {
|
|
230
|
+
if (isAppError(error)) {
|
|
231
|
+
const retry = error.retryAfter === undefined ? "" : ` Retry after ${error.retryAfter} seconds.`;
|
|
232
|
+
return `HackerOne API error (${error.code}, HTTP ${error.statusCode}): ${error.message}.${retry}`;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
if (error instanceof Error) {
|
|
236
|
+
return error.message;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
return String(error);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
export default function hackerOneExtension(pi: ExtensionAPI) {
|
|
243
|
+
pi.registerTool({
|
|
244
|
+
name: TOOL_NAME,
|
|
245
|
+
label: "HackerOne Report",
|
|
246
|
+
description: "Fetch a HackerOne report by report number using the HackerOne API.",
|
|
247
|
+
promptSnippet: "Fetch a HackerOne report by report number/id",
|
|
248
|
+
promptGuidelines: [
|
|
249
|
+
"Use hackerone_report when the user asks to fetch, inspect, summarize, or analyze a HackerOne report by number.",
|
|
250
|
+
"Before using hackerone_report, ensure the user provided the report number/id.",
|
|
251
|
+
],
|
|
252
|
+
parameters: reportParameters,
|
|
253
|
+
prepareArguments: normalizeToolArguments,
|
|
254
|
+
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
|
|
255
|
+
try {
|
|
256
|
+
const result = await fetchReport(params, ctx.cwd);
|
|
257
|
+
return {
|
|
258
|
+
content: [{ type: "text", text: formatReportMarkdown(result) }],
|
|
259
|
+
details: result,
|
|
260
|
+
};
|
|
261
|
+
} catch (error) {
|
|
262
|
+
return {
|
|
263
|
+
content: [{ type: "text", text: formatError(error) }],
|
|
264
|
+
isError: true,
|
|
265
|
+
details: undefined,
|
|
266
|
+
};
|
|
267
|
+
}
|
|
268
|
+
},
|
|
269
|
+
});
|
|
270
|
+
|
|
271
|
+
pi.registerCommand("hackerone-report", {
|
|
272
|
+
description: "Fetch a HackerOne report: /hackerone-report <number> [--comments] [--program handle]",
|
|
273
|
+
handler: async (args, ctx) => {
|
|
274
|
+
const parsed = parseCommandArgs(args);
|
|
275
|
+
if (!parsed) {
|
|
276
|
+
ctx.ui.notify("Usage: /hackerone-report <number> [--comments] [--program handle]", "warning");
|
|
277
|
+
return;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
try {
|
|
281
|
+
ctx.ui.notify(`Fetching HackerOne report #${parsed.reportId}...`, "info");
|
|
282
|
+
const result = await fetchReport(parsed, ctx.cwd);
|
|
283
|
+
pi.sendMessage({
|
|
284
|
+
customType: "hackerone-report",
|
|
285
|
+
content: formatReportMarkdown(result),
|
|
286
|
+
display: true,
|
|
287
|
+
details: result,
|
|
288
|
+
});
|
|
289
|
+
} catch (error) {
|
|
290
|
+
ctx.ui.notify(formatError(error), "error");
|
|
291
|
+
}
|
|
292
|
+
},
|
|
293
|
+
});
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
function parseCommandArgs(args: string): FetchReportOptions | undefined {
|
|
297
|
+
const tokens = args.trim().split(/\s+/).filter(Boolean);
|
|
298
|
+
const reportId = normalizeReportId(tokens[0]);
|
|
299
|
+
|
|
300
|
+
if (reportId === undefined) {
|
|
301
|
+
return undefined;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
const options: FetchReportOptions = { reportId };
|
|
305
|
+
for (let index = 1; index < tokens.length; index += 1) {
|
|
306
|
+
const token = tokens[index];
|
|
307
|
+
if (token === "--comments") {
|
|
308
|
+
options.includeComments = true;
|
|
309
|
+
continue;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
if (token === "--program") {
|
|
313
|
+
const program = tokens[index + 1];
|
|
314
|
+
if (!program) {
|
|
315
|
+
return undefined;
|
|
316
|
+
}
|
|
317
|
+
options.program = program;
|
|
318
|
+
index += 1;
|
|
319
|
+
continue;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
return undefined;
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
return options;
|
|
326
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "pi-hackerone",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Pi package that adds a HackerOne report tool and slash command.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"pi-package",
|
|
8
|
+
"pi-extension",
|
|
9
|
+
"hackerone"
|
|
10
|
+
],
|
|
11
|
+
"engines": {
|
|
12
|
+
"node": ">=22.6.0"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"extensions",
|
|
16
|
+
"README.md"
|
|
17
|
+
],
|
|
18
|
+
"scripts": {
|
|
19
|
+
"typecheck": "tsc --noEmit"
|
|
20
|
+
},
|
|
21
|
+
"dependencies": {
|
|
22
|
+
"@matteo.collina/hackerone": "^0.1.0"
|
|
23
|
+
},
|
|
24
|
+
"peerDependencies": {
|
|
25
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
26
|
+
"typebox": "*"
|
|
27
|
+
},
|
|
28
|
+
"devDependencies": {
|
|
29
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
30
|
+
"@types/node": "^24.0.0",
|
|
31
|
+
"typebox": "*",
|
|
32
|
+
"typescript": "^5.9.0"
|
|
33
|
+
},
|
|
34
|
+
"pi": {
|
|
35
|
+
"extensions": [
|
|
36
|
+
"./extensions"
|
|
37
|
+
]
|
|
38
|
+
}
|
|
39
|
+
}
|