Crate hackerone_api

Expand description

§hackerone-api

Unofficial, dependency-light Rust client for the HackerOne API (v1).

Built for the boring, reliable half of bug-bounty tooling: sign in, browse your programs and their scopes, read your reports, submit a report, search hacktivity, and read your balance and earnings — with HTTP Basic auth and no async runtime.

§Hacker surface

Report submission is a hacker operation. It lives under /v1/hackers/…, not the customer /v1/reports surface. These endpoints work with a researcher’s API token:

Method	Endpoint
`Client::create_report`	`POST /v1/hackers/reports`
`Client::my_reports`	`GET /v1/hackers/me/reports`
`Client::my_report`	`GET /v1/hackers/reports/{id}`
`Client::hacktivity`	`GET /v1/hackers/hacktivity`
`Client::balance`	`GET /v1/hackers/payments/balance`
`Client::earnings`	`GET /v1/hackers/payments/earnings`

§Customer surface

Client::me, Client::programs, Client::program, Client::structured_scopes, Client::reports, Client::report, Client::add_comment, Client::change_state and Client::weaknesses are the customer/program API. A hacker-only API token receives 401 on those routes (they require program access), even though the token is valid.

§Submit a report

use hackerone_api::{Client, CreateHackerReport, SeverityRating};

fn main() -> Result<(), hackerone_api::Error> {
    let client = Client::new("api-identifier", "api-token");

    let report = CreateHackerReport::new("sec", "Stored XSS in the profile page")
        .vulnerability_information("## Steps\n1. …")
        .impact("Session theft for any user who views the profile.")
        .severity(SeverityRating::High)
        .weakness_id(1337)
        .structured_scope_id(57);

    let created = client.create_report(&report)?;
    println!("filed: {} [{}]", created.title.unwrap_or_default(), created.state.unwrap_or_default());
    Ok(())
}

The created report’s numeric id is returned on the response envelope’s data.id; Client::create_report returns the report attributes (Report), matching Client::report. To read ids for existing reports, use Client::my_reports and Page::ids.

§Auth

The API uses HTTP Basic auth: the username is your API token identifier and the password is the token value. Create one in your HackerOne account settings. The examples read them from the HACKERONE_API_IDENTIFIER / HACKERONE_API_TOKEN environment variables.

§Design

Blocking, no async runtime. ureq under the hood.
Injectable transport. The client is generic over Transport, so tests use a mock and embedders can swap the HTTP stack.
Forward-compatible types. Domain structs keep the documented fields and stash unknown ones in a flattened extra map.

§Disclaimer

This crate is unofficial and not affiliated with or endorsed by HackerOne. “HackerOne” is a trademark of its owner; the name is used only to describe what the library talks to.

Structs§

ApiError: A single entry from the HackerOne API’s errors array.
Balance: The authenticated hacker’s payment balance (GET /v1/hackers/payments/balance).
Client: A HackerOne API client.
CollectionDoc: A collection response (GET /v1/reports, GET /v1/me/programs, …).
CreateHackerReport: A hacker report to create (POST /v1/hackers/reports).
DataDoc: A bare { "data": … } envelope whose data is not a JSON:API resource.
Earning: See the HackerOne API reference for Earning.
Hacktivity: See the HackerOne API reference for Hacktivity.
HacktivityQuery: Query for Client::hacktivity.
Links: JSON:API links object (pagination URLs).
Meta: JSON:API meta object, kept loose.
Page: A decoded page: the items plus the links needed to fetch more.
PageQuery: Pagination for the hacker list endpoints (page[number], page[size]).
Program: See the HackerOne API reference for Program.
Report: See the HackerOne API reference for Report.
ReportQuery: Filters for Client::reports.
Request: A fully-built request handed to a Transport.
Resource: A single JSON:API resource: id + type + attributes.
Response: A raw HTTP response.
Severity: See the HackerOne API reference for Severity.
SingleDoc: A single-object response (GET /v1/me, GET /v1/reports/{id}, …).
StructuredScope: See the HackerOne API reference for StructuredScope.
UreqTransport: Default transport backed by blocking ureq.
User: See the HackerOne API reference for User.
Weakness: See the HackerOne API reference for Weakness.

Enums§

Error: Everything that can go wrong talking to the HackerOne API.
Method: HTTP method.
ReportState: Report states accepted by a state change.
SeverityRating: Severity rating supplied when creating a report.

Constants§

DEFAULT_BASE_URL: Default API root.

Traits§

Transport: Anything that can turn a Request into a Response.

Type Aliases§

Result: Convenience alias.