hackerone-mcp-server 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# HackerOne MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unofficial MCP server that gives Codex, Claude Code, or any MCP client full access to your HackerOne reports, programs, earnings, and scope data via the HackerOne API — including submitting reports and responding to triage.
+
+## Setup
+
+Install Node.js and npm, then use the published [hackerone-mcp-server package](https://www.npmjs.com/package/hackerone-mcp-server) through `npx`.
+
+### 1. Get your HackerOne API token
+
+Go to **HackerOne > Settings > API Token** and generate one.
+
+### 2. Add to your MCP client
+
+Replace `your-username` and `your-api-token` below with your HackerOne credentials.
+
+#### Codex
+
+```toml
+[mcp_servers.hackerone]
+command = "npx"
+args = ["-y", "hackerone-mcp-server@latest"]
+startup_timeout_sec = 60
+env = { "H1_USERNAME" = "your-username", "H1_API_TOKEN" = "your-api-token" }
+```
+
+#### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "hackerone": {
+      "command": "npx",
+      "args": ["-y", "hackerone-mcp-server@latest"],
+      "env": {
+        "H1_USERNAME": "your-username",
+        "H1_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Build from source
+
+For local development:
+
+```bash
+git clone https://github.com/11philip22/hackerone-mcp-server.git
+cd hackerone-mcp-server
+npm install
+npm run build
+```
+
+Run `npm test` to build and run the fixture tests. Tests use Node's experimental module mocking and require Node.js 22.3+ (or 20.18+ on the Node 20 release line).
+
+To use your local build, set the MCP command to `node` and its arguments to `["/absolute/path/to/hackerone-mcp-server/dist/index.js"]`, keeping the same environment variables.
+
+## Tools
+
+### Read
+
+| Tool | Description |
+|------|-------------|
+| `search_reports` | Search and filter your reports by keyword, program, severity, or state |
+| `get_report` | Get full report details including CVSS vector, bounty amounts, and attachments |
+| `get_report_with_conversation` | Get a report with its triage conversation thread |
+| `get_report_activities` | Get activity timeline (comments, state changes, bounties) |
+| `list_programs` | List all bug bounty programs you have access to (auto-paginates) |
+| `get_program_details` | Get single program info: policy, response times, metrics |
+| `get_program_signal_requirements` | Get a public program's minimum past-year signal threshold and whether requirements are enabled |
+| `get_program_rewards` | Get a public program's currency, severity payout ranges, reward groups, and each group's scope assets |
+| `get_program_scope` | Get all in-scope assets for a program (auto-paginates) |
+| `get_program_weaknesses` | Get accepted CWE/weakness types for a program (auto-paginates) |
+| `get_earnings` | Get your bounty earnings history (amounts, dates, programs) |
+| `get_hacker_profile` | Get your reputation, signal, impact, and rank |
+| `get_balance` | Get your current unpaid bounty balance |
+| `analyze_report_patterns` | Analyze your hunting patterns (severity distribution, top programs, weakness types) |
+| `search_disclosed_reports` | Search publicly disclosed reports on hacktivity — great for recon and learning |
+
+### Write
+
+| Tool | Description |
+|------|-------------|
+| `submit_report` | Submit a new vulnerability report to a program |
+| `add_comment` | Add a comment to an existing report (respond to triage) |
+| `close_report` | Withdraw/close one of your own reports |
+
+## Usage Examples
+
+**Submit a report directly:**
+```
+Submit this SSRF finding to the uber program with critical severity. Here's my writeup: [paste]
+```
+
+**Respond to triage:**
+```
+Add a comment to report #2345678: "Here's the updated PoC with the new endpoint..."
+```
+
+**Draft a report matching your style:**
+```
+Find my resolved critical reports and use the same structure to draft a new report for this SSRF I found.
+```
+
+**Learn from triage conversations:**
+```
+Show me the triage conversation on report #2345678. What questions did they ask?
+```
+
+**Research what gets paid:**
+```
+Search disclosed reports on the uber program for SSRF — what did they pay?
+```
+
+**Check program details before hunting:**
+```
+Show me the uber program details — what are their response times?
+```
+
+**Check your stats:**
+```
+Show my hacker profile — what's my current reputation and signal?
+```
+
+**Check a program's signal requirement:**
+```
+What signal do I need to submit reports to the uber program?
+```
+
+**Compare rewards by asset group:**
+```
+Show TikTok's reward groups, severity payout ranges, and which Android apps and websites belong to each group. Flag any unavailable data.
+```
+
+**Track earnings:**
+```
+Show my recent bounty earnings and current balance
+```
+
+**Analyze patterns:**
+```
+Analyze my report patterns — what severity gets resolved most?
+```

package/dist/h1client.d.ts

@@ -0,0 +1,219 @@
+export interface SearchReportsOpts {
+    query?: string;
+    program?: string;
+    severity?: string;
+    state?: string;
+    page_size?: number;
+    page_number?: number;
+    sort?: string;
+}
+export declare function searchReports(opts?: SearchReportsOpts): Promise<{
+    id: any;
+    title: any;
+    state: any;
+    substate: any;
+    severity: any;
+    created_at: any;
+    disclosed_at: any;
+    bounty_awarded_at: any;
+    bounty_amount: any;
+    bounty_bonus: any;
+    weakness: any;
+    program: any;
+}[]>;
+export declare function getReport(reportId: string): Promise<{
+    id: any;
+    title: any;
+    state: any;
+    created_at: any;
+    closed_at: any;
+    triaged_at: any;
+    bounty_awarded_at: any;
+    disclosed_at: any;
+    severity: any;
+    cvss_score: any;
+    cvss_vector: {
+        attack_vector: any;
+        attack_complexity: any;
+        privileges_required: any;
+        user_interaction: any;
+        scope: any;
+        confidentiality: any;
+        integrity: any;
+        availability: any;
+    } | null;
+    bounty_amount: any;
+    bounty_bonus: any;
+    vulnerability_information: any;
+    impact: any;
+    weakness: any;
+    weakness_id: any;
+    program: any;
+    structured_scope: any;
+    structured_scope_type: any;
+    attachments: any;
+}>;
+export declare function getReportActivities(reportId: string, _pageSize?: number): Promise<any>;
+export declare function listPrograms(pageSize?: number): Promise<{
+    id: any;
+    handle: any;
+    name: any;
+    offers_bounties: any;
+    state: any;
+    started_accepting_at: any;
+    submission_state: any;
+}[]>;
+export declare function getProgramDetails(handle: string): Promise<{
+    id: string;
+    handle: any;
+    name: any;
+    url: any;
+    offers_bounties: any;
+    state: any;
+    submission_state: any;
+    started_accepting_at: any;
+    policy: any;
+    response_efficiency_percentage: any;
+    average_time_to_first_program_response: any;
+    average_time_to_report_resolved: any;
+    average_time_to_bounty_awarded: any;
+    allow_bounty_splitting: any;
+    bookmarked: any;
+}>;
+export declare function getProgramSignalRequirements(handle: string): Promise<any>;
+type RewardAvailability = "available" | "partial" | "unavailable";
+type RewardSeverity = "low" | "medium" | "high" | "critical";
+interface RewardAsset {
+    id: string;
+    asset_identifier: string;
+    asset_type: string | null;
+    eligible_for_submission: boolean | null;
+    eligible_for_bounty: boolean | null;
+}
+interface RewardGroup {
+    id: string;
+    name: string | null;
+    description: string | null;
+    scope_kind: "all_assets" | "asset" | "reward_group" | null;
+    use_range: boolean | null;
+    rewards: Record<RewardSeverity, {
+        label: string | null;
+        minimum: number | null;
+        maximum: number | null;
+    }>;
+    assets: RewardAsset[] | null;
+    assets_availability: RewardAvailability;
+}
+export interface ProgramRewards {
+    handle: string;
+    currency: string | null;
+    source: string;
+    program_url: string;
+    format: "legacy" | "scope_and_rewards" | null;
+    description: string | null;
+    availability: RewardAvailability;
+    issues: {
+        code: string;
+        group_id: string | null;
+        message: string;
+    }[];
+    groups: RewardGroup[] | null;
+}
+export declare function getProgramRewards(handle: string): Promise<ProgramRewards>;
+export declare function getProgramScope(handle: string, pageSize?: number): Promise<{
+    id: any;
+    asset_type: any;
+    asset_identifier: any;
+    eligible_for_bounty: any;
+    eligible_for_submission: any;
+    instruction: any;
+    max_severity: any;
+    created_at: any;
+}[]>;
+export declare function getProgramWeaknesses(handle: string, pageSize?: number): Promise<{
+    id: any;
+    name: any;
+    description: any;
+    external_id: any;
+}[]>;
+export declare function getEarnings(pageSize?: number): Promise<any>;
+export declare function getHackerProfile(): Promise<{
+    id: any;
+    username: any;
+    name: any;
+    bio: any;
+    reputation: any;
+    signal: any;
+    impact: any;
+    rank: any;
+    created_at: any;
+    hackerone_triager: any;
+    source: string;
+    unavailable_reason: string | null;
+}>;
+export declare function getBalance(): Promise<any>;
+export declare function getReportSummary(reportId: string): Promise<{
+    conversation: any;
+    id: any;
+    title: any;
+    state: any;
+    created_at: any;
+    closed_at: any;
+    triaged_at: any;
+    bounty_awarded_at: any;
+    disclosed_at: any;
+    severity: any;
+    cvss_score: any;
+    cvss_vector: {
+        attack_vector: any;
+        attack_complexity: any;
+        privileges_required: any;
+        user_interaction: any;
+        scope: any;
+        confidentiality: any;
+        integrity: any;
+        availability: any;
+    } | null;
+    bounty_amount: any;
+    bounty_bonus: any;
+    vulnerability_information: any;
+    impact: any;
+    weakness: any;
+    weakness_id: any;
+    program: any;
+    structured_scope: any;
+    structured_scope_type: any;
+    attachments: any;
+}>;
+export declare function submitReport(opts: {
+    program_handle: string;
+    title: string;
+    vulnerability_information: string;
+    impact?: string;
+    severity_rating?: string;
+    weakness_id?: string;
+    structured_scope_id?: string;
+}): Promise<{
+    id: any;
+    title: any;
+    state: any;
+    url: string;
+}>;
+export declare function addComment(reportId: string, message: string, internal?: boolean): Promise<{
+    id: any;
+    type: any;
+    message: any;
+    created_at: any;
+}>;
+export declare function closeReport(reportId: string, message?: string): Promise<{
+    id: any;
+    type: any;
+    message: any;
+    created_at: any;
+}>;
+export declare function searchDisclosedReports(opts: {
+    program?: string;
+    query?: string;
+    page_size?: number;
+}): Promise<any>;
+export {};