Submit reports to HackerOne

The HackerOne integration creates one report in a configured program after a person reviews and confirms the rendered payload.

Before you begin

You need:

• a HackerOne organization and self-service sandbox program
• the program’s team handle
• permission to manage API tokens and token groups in HackerOne
• permission to create integration connections in Dreadnode

The API worker also needs outbound HTTPS access to api.hackerone.com. If your HackerOne organization restricts API traffic by IP, allow the API worker’s egress IP before testing the connection.

Create a sandbox program

Open HackerOne’s sandbox program form while logged in and create a program for integration testing. Keep required custom fields disabled because HackerOne’s create-report API cannot supply them.

Copy the program’s team handle from its URL:

https://hackerone.com/<team_handle>

Use the segment after hackerone.com/. Do not use the organization handle from a URL such as hackerone.com/organizations/<organization_handle>/settings.

Grant report access to a group

Create a dedicated group before creating the API token:

1. Open Organization Settings → Groups, then choose Add new group.
2. Enter a name such as Dreadnode sandbox API.
3. Under Engagements and reports permissions, add the sandbox program to Engagements access.
4. Under Permissions, add Read only and Report.
5. Save the group.

HackerOne’s UI labels the write permission Report. Its API documentation calls the same permission Report Management. Organization administrator, reward, and asset permissions are not required to create reports.

Create a least-privilege API token

In HackerOne, open Organization Settings → API Tokens, choose Create API token, and create a dedicated token for Dreadnode. Assign it to the group you created above. A token with no groups has no program access.

Copy both values shown during creation:

• API token identifier — the HTTP Basic username, not an email address
• API token — the HTTP Basic password

HackerOne shows the token value once. Store both values in your secret manager before leaving the page. See API Tokens for HackerOne’s current token-management flow.

Create and test the connection

1. Open Org Settings → Integrations.
2. In Connections, choose Add connection.
3. Set Destination to HackerOne.
4. Enter a descriptive name, API token identifier, API token, and the program’s exact team handle.
5. Choose Create.
6. Choose Test connection on the saved connection.

For API clients, use these fields:

{
  "name": "HackerOne sandbox",
  "type": "hackerone",
  "config": {
    "team_handle": "dreadnode-sandbox"
  },
  "credentials": {
    "api_token_identifier": "REPLACE_WITH_TOKEN_IDENTIFIER",
    "api_token": "REPLACE_WITH_TOKEN"
  }
}

The test follows every page from GET /v1/me/programs and requires an exact team-handle match. It verifies authentication and access to the configured program.

The test cannot prove report creation permission

HackerOne does not expose a non-destructive write-permission check. The token group still needs Report permission in the HackerOne UI. Verify it by creating one synthetic report in a sandbox.

Create a submission action

Connect project findings to the saved HackerOne connection:

1. Open Org Settings → Integrations.
2. Select the target project in Projects.
3. In Actions, choose the + button (Add project action).
4. Enter a name, set Item type to finding, and select the HackerOne connection.
5. Keep Enabled on. Turn on Allow agents to stage only when agents should stage findings for human review.
6. Review the Template JSON, then choose Create.

New HackerOne actions start with this template:

{
  "title": "{{title}}",
  "description": "{{data.description}}",
  "evidence": "{{data.evidence}}",
  "impact": "{{data.impact}}",
  "severity": "{{data.severity}}"
}

If an existing action contains only title, replace its template with the example above. Missing item paths render as empty editable fields and produce a preview warning. Before submitting, enter a non-empty title, description or vulnerability information, and impact. Evidence and severity are optional; an empty severity defaults to info, which HackerOne receives as none.

Add weakness_id or structured_scope_id to the template when your findings provide positive HackerOne integer IDs. The adapter omits empty, invalid, and zero values.

Map findings to HackerOne reports

The adapter sends a JSON:API report with these mappings:

Dreadnode payload	HackerOne report
configured team_handle	team_handle
title	title
description, evidence, item URL	combined into vulnerability_information
impact	impact
severity	severity_rating; info becomes none
constant	source: "dreadnode"
positive integer weakness_id	weakness_id; invalid, empty, or zero values are omitted
positive integer structured_scope_id	structured_scope_id; invalid, empty, or zero values are omitted

Dreadnode adds the item URL during local preview. Reviewers can edit report content and optional IDs, but they cannot replace that backlink.

After HackerOne accepts the report, Dreadnode stores the report ID and https://hackerone.com/reports/{id} under External References and in Submission Audit.

Required custom fields are unsupported

HackerOne’s create-report API cannot submit custom-field values. A program with required custom fields rejects API-created reports with 400 Bad Request. Remove the required constraint in the sandbox or create those reports directly in HackerOne.

Verify the workflow in a sandbox

Run this acceptance pass before using a production program:

1. Create a self-service HackerOne sandbox program with no required custom fields.
2. Create a dedicated token group with Read only and Report, then create its API token.
3. Save and test the Dreadnode connection. Confirm that changing the team handle to a partial or inaccessible handle fails.
4. Create an action with the template above and preview one synthetic, non-production finding.
5. Confirm that preview shows the evidence, impact, severity, and Dreadnode item URL without creating a HackerOne report.
6. Submit the finding and verify the report fields, source: "dreadnode", report ID, external link, and Dreadnode audit entry. Use info severity to verify that HackerOne receives none.
7. Attempt the same action again and confirm that Dreadnode requires duplicate acknowledgement.
8. Select several staged findings and verify that bulk submission creates one report per finding.

Repeat the connection test with a wrong identifier or token to exercise 401. Remove program access or Report, or use a blocked egress IP, to exercise 403. Make a custom field required to exercise the documented 400 limitation, then remove the requirement.

Handle limits and ambiguous timeouts

HackerOne allows 25 write requests per 20 seconds. Dreadnode serializes HackerOne bulk writes below that limit. A 429 response remains a failed attempt and includes the safe Retry-After delay when HackerOne supplies one.

A timed-out report request has an unknown outcome because HackerOne does not support an idempotency key for report creation. Dreadnode marks that attempt as requiring reconciliation and blocks blind retries. Check the configured HackerOne program, then explicitly acknowledge the reconciliation only when creating another report is safe.

Connection and submission errors never store HackerOne response bodies, token identifiers, or token values. The API returns only masked credential placeholders after save.

Troubleshoot HackerOne submissions

Symptom	Check
Connection test returns 401	Replace both the token identifier and token.
Configured program is not found	Use the program handle, not the organization handle. Match case and punctuation.
Connection test returns 403	Check group program access and the HackerOne IP allowlist.
Test passes but report submission returns 403	Add Report under the group’s Engagements and reports permissions → Permissions.
Report validation says a required field is empty	Add the field to the action template or enter it in the submission preview.
Submission returns 400	Remove required custom fields or create the report in HackerOne.
Submission returns 422	Review required strings, severity, weakness ID, and structured scope ID.
Submission requires reconciliation	Check HackerOne for the report before any retry.