> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HackerOne

> Securely connect HackerOne with AirMDR to retrieve vulnerability reports and automate investigation and response workflows.

## Purpose

<Expandable title="Purpose">
  The HackerOne integration enables AirMDR to securely connect to the HackerOne Customer API and retrieve vulnerability reports and related program information for investigation, enrichment, and automated response workflows.

  The integration can help security teams:

  * Centralize HackerOne vulnerability reports within AirMDR.
  * Enrich security investigations with vulnerability and program details.
  * Automate report triage and case-management workflows.
  * Reduce manual switching between HackerOne and AirMDR.
  * Maintain a consistent record of vulnerability-management activities.
</Expandable>

## Supported Versions

<Expandable title="Supported Versions">
  | Component          | Supported version                |
  | :----------------- | :------------------------------- |
  | HackerOne Platform | HackerOne cloud platform         |
  | HackerOne API      | Customer API v1                  |
  | Authentication     | HTTP Basic Authentication        |
  | Transport          | HTTPS                            |
  | AirMDR             | Current supported AirMDR release |
  | Data format        | JSON                             |

  <Note>
    The HackerOne API uses an API token identifier and token value as the username and password for HTTP Basic Authentication. These credentials must be included with each API request. For current API information, see the [HackerOne API documentation](https://api.hackerone.com/getting-started/?utm_source=chatgpt.com).
  </Note>
</Expandable>

## Authentication Method

<Expandable title="Authentication Method">
  The integration uses HTTP Basic Authentication with the following credentials:

  | AirMDR field | HackerOne value       | Description                                                  |
  | :----------- | :-------------------- | :----------------------------------------------------------- |
  | API Username | API token identifier  | The identifier entered when creating the HackerOne API token |
  | API Token    | Generated token value | The secret value displayed after the API token is created    |

  <Tip>
    For an organization-level HackerOne token, the **API Username is the API token identifier**, not necessarily the username used to sign in to HackerOne.
  </Tip>

  The credentials are transmitted in the following logical format:

  **Authorization:** `Basic Base64(<API_TOKEN_IDENTIFIER>:<API_TOKEN_VALUE>)`

  <Note>
    Do not manually Base64-encode the credentials when configuring AirMDR unless the product interface explicitly requests an encoded value.
  </Note>
</Expandable>

<Expandable title="Role-Based Access Recommendations">
  Organization-level API tokens inherit permissions from the HackerOne groups assigned during token creation.

  * If no groups are assigned, the API user is added without access rights.
  * Assign only the groups required for the AirMDR use case.
  * Read-only access is recommended when AirMDR only retrieves vulnerability data.
  * Additional permissions may be required for workflows that update HackerOne reports.
  * Avoid assigning Organization Administrator privileges unless an AirMDR workflow explicitly requires them.

  > **Best Practice:** Create a dedicated API token for AirMDR instead of using a personal API token.
</Expandable>

### Pre-requisites

> <Check>
>   Users must have Administrator access to the **HackerOne** UI with sufficient privileges to create or manage users and has access to the HackerOne Customer API.
> </Check>
>
> <Check>
>   Permission to create organization-level API tokens in **HackerOne**.
> </Check>

<Note>
  HackerOne API access and available endpoints can depend on your HackerOne subscription and assigned permissions.
</Note>

## Setup Steps

<Steps>
  <Step title="Generate the API Username and API Token in HackerOne">
    The following procedure applies to organization-managed HackerOne API tokens.

    1. Open the HackerOne platform.
    2. Enter your organization account credentials.
    3. Complete multi-factor authentication if prompted.
    4. Confirm that you are operating within the correct organization.
  </Step>

  <Step title="Open Organization Settings">
    1. From the HackerOne navigation menu, open **Organization Settings**.
    2. Verify that the displayed organization is the organization you want to connect to AirMDR.
           <Note>
             You must have the appropriate organization administrator permissions to access and manage organization API tokens.
           </Note>
  </Step>

  <Step title="Open the API Tokens page">
    1. In **Organization Settings**, select **API Tokens**.
    2. Review the existing tokens to ensure that an AirMDR-specific token has not already been created.
    3. The verified HackerOne navigation path is: **Organization Settings → API Tokens**.
           <Info>
             The API Tokens page displays the existing organization API tokens.
           </Info>
  </Step>

  <Step title="Create an API token">
    1. Click **Create API Token**.
    2. In the identifier field, enter a descriptive identifier.<br />For example: `airmdr-hackerone-integration`
           <Tip>
             Avoid entering passwords, email addresses, or other sensitive information in the identifier.
           </Tip>
           <Check>
             The identifier entered here becomes the **API Username** used when configuring the integration in AirMDR.
           </Check>
  </Step>

  <Step title="Assign groups">
    1. Select the HackerOne groups that the API token must belong to.
    2. Confirm that the selected groups provide access to the required HackerOne programs and reports.
    3. Apply least-privilege access based on the intended integration functions.
    4. For a read-only integration, the group should generally provide permission to:
       * View the required programs.
       * View vulnerability reports.
       * Read report details and related metadata.
    5. If AirMDR must perform write operations, additional permissions might be required to:
       * Update reports.
       * Add comments.
       * Change report states.
       * Assign users.
       * Manage other HackerOne resources.
             <Warning>
               If no group is selected, the API user is created without access rights. Authentication might succeed, but requests to protected resources can fail.
             </Warning>
  </Step>

  <Step title="Add the API token">
    1. Review the token identifier.
    2. Review the selected groups.
    3. Click **Add API token**.
           <Check>
             HackerOne generates the API token value.
           </Check>
           <Warning>
             **HackerOne displays the generated token only once. Copy it immediately and store it in an approved enterprise secrets-management system.**
           </Warning>
  </Step>

  <Step title="Copy the credentials">
    Record the following values:

    | Required value | Source                                   | What to Enter                                                                                        | Where to Get It                                                                                             |
    | :------------- | :--------------------------------------- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
    | API Username   | Identifier entered during token creation | Enter the API token identifier created for the AirMDR integration, for example, `airmdr-production`. | **HackerOne → Organization Settings → API Tokens → Create API Token → Identifier**                          |
    | API Token      | Token value generated by HackerOne       | Enter the secret API token value generated by HackerOne.                                             | Displayed once after selecting **Add API token**. Copy it before selecting **I have stored the API Token**. |

    **Example mapping:**<br />`API Username: airmdr-production`

    `API Token: <generated-HackerOne-token>`
  </Step>

  <Step title="Confirm that the token is stored">
    1. Store the token in an approved secrets-management system.
    2. Return to HackerOne.
    3. Click **I have stored the API Token**.

    HackerOne may send a confirmation email indicating that an API token was created. The complete official procedure is available in the [HackerOne API Tokens guide](https://docs.hackerone.com/en/articles/8544782-api-tokens?utm_source=chatgpt.com).
  </Step>
</Steps>

### Validate Connectivity

Use the following request only from a secure administrative workstation. Do not expose the token in shared terminal history or logs

<AccordionGroup>
  <Accordion title="Sample Request & Response – /api/parse">
    **Request:**

    ```text theme={null}
    curl --request GET \
      --user "${HACKERONE_API_USERNAME}:${HACKERONE_API_TOKEN}" \
      --header "Accept: application/json" \
      "https://api.hackerone.com/v1/me"
    ```

    <Warning>
      Environment variables reduce accidental exposure in the command itself, but they must still be managed securely.
    </Warning>

    **Sample successful response:**

    ```json theme={null}
    {
      "name": "hackerone-production",
      "type": "hackerone",
      "base_url": "https://api.hackerone.com/v1",
      "authentication": {
        "type": "basic",
        "username": "${HACKERONE_API_USERNAME}",
        "token": "${HACKERONE_API_TOKEN}"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Configure Gravwell in AirMDR Integrations Dashboard

1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login**
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **Integrations**.
3. Use the search option, enter the keyword "**HackerOne**", select the **Connections** tab, and click **+ Create** button.
4. Enter an unique name to the Instance (e.g., `your org name-HackerOne`) to easily identify the user connection by AirMDR.
5. Enter the application credentials like **API Username** and **API Token** in the Authentication Details field params, and click **Save**.

## Skills provided by this Integration

| **Skill ID**                  | **Purpose**                                                                                        |
| :---------------------------- | :------------------------------------------------------------------------------------------------- |
| List HackerOne Activities     | Incrementally pull program activities from HackerOne to detect new reports and report updates      |
| Get HackerOne Report          | Retrieve a single HackerOne report by its ID                                                       |
| Get HackerOne Reports         | Pull vulnerability reports from HackerOne, filtered by program, state, severity, and creation time |
| Change HackerOne Report State | Change the state of a HackerOne report (e.g. triage or resolve)                                    |
| Comment on HackerOne Report   | Post an internal or public comment on a HackerOne report                                           |
| Assign HackerOne Report       | Assign a HackerOne report to a user or group, or clear the assignee                                |

<Tip>
  To view the details of Input Parameters and Output for the respective skills

  * Go to AirMDR → HackerOne Integration page.
  * Select the **Skills** tab and click on the required listed skills.
</Tip>

## Additional Information

<AccordionGroup>
  <Accordion title="🧰 Error Handling">
    | Error                                       | Probable cause                                                   | Recovery                                                      |
    | :------------------------------------------ | :--------------------------------------------------------------- | :------------------------------------------------------------ |
    | `400 Bad Request`                           | Invalid request parameters or malformed payload                  | Review the request fields and HackerOne API schema            |
    | `401 Unauthorized`                          | Incorrect identifier, incorrect token, or revoked token          | Re-enter the credentials or generate a replacement token      |
    | `403 Forbidden`                             | API user lacks the required group or resource permission         | Review the API token’s assigned groups and permissions        |
    | `404 Not Found`                             | Incorrect endpoint, unavailable resource, or restricted resource | Verify the endpoint, resource ID, and access scope            |
    | `409 Conflict`                              | Requested change conflicts with the current resource state       | Refresh the resource and retry only after reviewing its state |
    | `422 Unprocessable Entity`                  | Request is valid JSON but contains unacceptable values           | Review field values and required relationships                |
    | `429 Too Many Requests`                     | HackerOne API rate limit reached                                 | Apply delayed retries with exponential backoff                |
    | `5xx` response                              | Temporary HackerOne service-side error                           | Retry with backoff and check HackerOne service status         |
    | Connection timeout                          | Network, DNS, proxy, or firewall issue                           | Verify TCP 443 access to `api.hackerone.com`                  |
    | Validation succeeds but data is unavailable | Token has insufficient program access                            | Assign the token to the appropriate HackerOne group           |
    | Existing token no longer works              | Token was revoked, replaced, or permissions changed              | Create or update the token and replace it in AirMDR           |
  </Accordion>

  <Accordion title="🔄 Monitoring & Logs">
    ### Monitor in AirMDR

    Review the following areas, as applicable:

    * Integration connection status.
    * Connectivity-validation results.
    * Playbook execution history.
    * Failed skill executions.
    * Scheduled synchronization history.
    * Case or investigation timelines.
    * Audit logs.

    Monitor for:

    * Repeated authentication failures.
    * Permission-denied responses.
    * API rate-limit responses.
    * Unexpected increases in failed requests.
    * Missing reports or synchronization gaps.
    * Token changes or revocations.

    ### Monitor in HackerOne

    * Organization administrators can review the API token from **Organization Settings → API Tokens**
    * Use the token’s action menu to review or modify its assigned groups. HackerOne also provides program audit logs to administrators under Program Settings **→** General **→** Audit Log
          <Tip>
            See the [HackerOne audit-log documentation](https://docs.hackerone.com/en/articles/8524901-audit-logs?utm_source=chatgpt.com).
          </Tip>

    ### Sample successful log entry

    ```text theme={null}
    2026-07-23T10:30:12Z INFO
    integration=hackerone
    connection=hackerone-production
    operation=get_reports
    status=success
    http_status=200
    ```

    ### Sample authentication failure

    ```text theme={null}
    2026-07-23T10:31:08Z ERROR
    integration=hackerone
    connection=hackerone-production
    operation=validate_connection
    status=failed
    http_status=401
    message="HackerOne authentication failed"
    ```

    ### Sample authorization failure

    ```text theme={null}
    2026-07-23T10:32:41Z WARN
    integration=hackerone
    connection=hackerone-production
    operation=get_reports
    status=failed
    http_status=403
    message="API user does not have permission to access the requested resource"
    ```

    ### Recommended log levels

    | Log level | Usage                                                                      |
    | :-------- | :------------------------------------------------------------------------- |
    | INFO      | Successful connections, synchronization summaries, and completed requests  |
    | WARN      | Rate limits, incomplete results, or recoverable permission issues          |
    | ERROR     | Authentication failures, connection failures, and unrecoverable API errors |
    | DEBUG     | Temporary troubleshooting under controlled conditions                      |

    <Warning>
      Never log API tokens, Basic Authentication headers, session cookies, or complete sensitive report contents.
    </Warning>
  </Accordion>

  <Accordion title="🛑 Security & Access Best Practices">
    ### ✅ Do

    * Create a dedicated organization API token for AirMDR.
    * Use a descriptive token identifier such as `airmdr-production`.
    * Assign the token to least-privilege groups.
    * Store the token in an approved secrets-management system.
    * Use HTTPS over TCP port 443.
    * Rotate credentials according to organizational policy.
    * Validate the new token before revoking the previous token.
    * Review API-token permissions periodically.
    * Redact credentials and sensitive vulnerability data from screenshots.
    * Monitor authentication failures and unexpected API activity.

    ### ❌ Avoid

    * Using a personal sign-in password as the API token.
    * Assuming the normal HackerOne username is the organization API Username.
    * Assigning administrator permissions without a documented requirement.
    * Storing tokens in source control, Confluence, Jira, email, or Slack.
    * Including credentials in screenshots or troubleshooting logs.
    * Sharing one token across multiple unrelated integrations.
    * Sending credentials over unencrypted channels.
    * Hard-coding the token in scripts or configuration files.
    * Leaving unused API tokens active.
    * Publishing complete HackerOne report content in diagnostic logs.
  </Accordion>

  <Accordion title="👉 Support & Maintenance">
    * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.
    * 🔁 Rotate credentials regularly. Recommended cadence: Every 90 days or as per internal security policy
    * 🔄 Reconnect in AirMDR when secrets are changed.
    * For HackerOne platform or API issues:
      * Consult the [HackerOne Help Center](https://docs.hackerone.com/).
      * Review the [HackerOne API documentation](https://api.hackerone.com/?utm_source=chatgpt.com).
      * Contact HackerOne Support through your organization’s approved support channel. | Activity | Recommended Frequency | | :-- | :-- | | Review token permissions | Quarterly | | Rotate API token | As per company security policy | | Check token expiration | Monthly |

    ### Updating assigned groups

    To update permissions for an existing organization API token:

    1. Navigate to **Organization Settings > API Tokens**.
    2. Locate the AirMDR API token.
    3. Open the three-dot action menu.
    4. Select **Edit API token**.
    5. Select **Manage groups for this API token**.
    6. Add or remove the required groups.
    7. Save the changes.
    8. Validate the connection in AirMDR.

    ### Revoking a token

    1. Create and validate a replacement token, if required.
    2. Open **Organization Settings > API Tokens**.
    3. Locate the old AirMDR token.
    4. Open its action menu.
    5. Revoke or remove the token.
    6. Confirm that AirMDR is using the replacement credential.
  </Accordion>

  <Accordion title="🛑 Data Flow & Security">
    Depending on the AirMDR playbooks and permissions, the integration may process:

    * HackerOne report identifiers.
    * Report titles and descriptions.
    * Report state and severity.
    * Weakness and vulnerability information.
    * Program information.
    * Reporter and assignee metadata.
    * Report comments and activity.
    * Timestamps and remediation status.
    * Asset or structured-scope information.

    The HackerOne API supports workflows such as retrieving vulnerability reports, accessing program information, importing findings, and interacting with reports. See the [HackerOne API use cases](https://api.hackerone.com/use-cases/?utm_source=chatgpt.com).

    ### Network requirements

    | Requirement    | Value                          |
    | :------------- | :----------------------------- |
    | Direction      | Outbound from AirMDR           |
    | Protocol       | HTTPS                          |
    | Port           | TCP 443                        |
    | API hostname   | `api.hackerone.com`            |
    | API base URL   | `https://api.hackerone.com/v1` |
    | Payload format | JSON                           |
    | Authentication | HTTP Basic Authentication      |

    ### Encryption

    * API communication must occur over HTTPS.
    * Do not permit fallback to unencrypted HTTP.
    * Store the API token only in an approved credential or secret store.
    * Do not include the Authorization header in application logs.
    * Follow your organization’s data-retention requirements for vulnerability data stored in AirMDR.

    <Note>
      Confirm AirMDR credential-storage and at-rest encryption controls against your organization’s deployed AirMDR version and security architecture.
    </Note>
  </Accordion>
</AccordionGroup>