hackerone-mcp-server 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,150 @@
-# 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.
+> **Disclaimer:** This is an unofficial, community-built project. It is not affiliated with, endorsed by, or maintained by HackerOne. "HackerOne" is a trademark of HackerOne, Inc. This project integrates with their publicly documented [Hacker API](https://api.hackerone.com/hacker-resources/) and uses the website's public GraphQL API for program signal requirements.
+
+MCP server that gives 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
+
+### 1. Get your HackerOne API token
+
+Go to **HackerOne > Settings > API Token** and generate one.
+
+### 2. Install and build
+
+```bash
+git clone https://github.com/Sicks3c/hackerone-mcp-server.git
+cd hackerone-mcp-server
+npm install
+npm run build
+```
+
+### 3. Add to Claude Code
+
+```bash
+claude mcp add hackerone \
+  -e H1_USERNAME=your-username \
+  -e H1_API_TOKEN=your-api-token \
+  -s user \
+  -- node /path/to/hackerone-mcp-server/dist/index.js
+```
+
+Or add manually to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "hackerone": {
+      "command": "node",
+      "args": ["/path/to/hackerone-mcp-server/dist/index.js"],
+      "env": {
+        "H1_USERNAME": "your-username",
+        "H1_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+### 4. Verify
+
+```bash
+claude
+> /mcp
+# You should see "hackerone" listed with 17 tools
+```
+
+## 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_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?
+```
+
+**Track earnings:**
+```
+Show my recent bounty earnings and current balance
+```
+
+**Analyze patterns:**
+```
+Analyze my report patterns — what severity gets resolved most?
+```
+
+## How It Works
+
+- Connects to the [HackerOne Hacker API v1](https://api.hackerone.com/hacker-resources/) using your personal API token
+- Runs locally over stdio — your credentials never leave your machine
+- Supports both read and write operations (submit reports, add comments, close reports)
+- Auto-paginates programs, scope, and weakness endpoints so nothing gets silently truncated
+- Uses server-side API filters where available (program, severity, state) for faster searches
+- Built-in retry with exponential backoff for rate limit handling
+- 60-second response cache to reduce redundant API calls
+
+## License
+
+MIT

package/dist/h1client.d.ts

@@ -0,0 +1,179 @@
+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>;
+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>;