NAV Navbar

Use Cases

Importing known vulnerabilities

The API allows you to import known vulnerabilities to your HackerOne program so that you can have central vulnerability management and detect duplicate vulnerabilities. You can use the create report endpoint to systematically import vulnerabilities that are found outside the HackerOne platform, such as from internal tests or via automated vulnerability scanners.

Below is an example on how to import a known vulnerability:

curl "https://api.hackerone.com/v1/reports" \
  -X POST \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ=" \
  -H "Content-Type: application/json" \
  -d @- <<EOD
    {
      "data": {
        "type": "report",
        "attributes": {
          "team_handle": "security",
          "title": "XSS in login form",
          "vulnerability_information": "...",
          "impact": "...",
          "severity_rating": "medium",
          "weakness_id": "1337",
          "structured_scope_id": "287",
          "source": "detectify"
        }
      }
    }
EOD

Using the source attribute, you can define the original source of the vulnerability. This will be helpful in tracking vulnerabilities from specific sources and in running analytics by source. The source attribute will also be returned in the response of the report object.

Using the reports query endpoint

The Get All Reports endpoint allows you to get multiple reports at once. The filters enable you to insert criteria the report has to match to show up in the list. The default filter to get all reports in one program is filter[program]. Your request would look like:

curl "https://api.hackerone.com/v1/reports?filter\[program\]\[\]=john_doe_example_company" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

Combining multiple filters

Using this endpoint, you can combine multiple filters if you want to make the query more specific. Here's an example that queries all reports in the triaged state for the john_doe_example_company program.

curl "https://api.hackerone.com/v1/reports?filter\[program\]\[\]=john_doe_example_company&filter\[state\]\[\]=triaged" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

Awarding bounties

The API has 2 different methods for awarding bounties: one for vulnerabilities reported via HackerOne and one for vulnerabilities reported outside of the HackerOne platform. For vulnerabilities reported via HackerOne, you can use the bounty award endpoint:

curl "https://api.hackerone.com/v1/reports/172932/bounties" \
  -X POST \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ=" \
  -H "Content-Type: application/json" \
  -d @- <<EOD
    {
      "data": {
        "message": "Thanks for the great report. Here's your bounty!",
        "amount": "500",
        "bonus_amount": "250"
      }
    }
EOD

External bounties

To award a bounty to someone who found a vulnerability outside the HackerOne platform, use the program bounty endpoint. In the example below, there's no report of the vulnerability in the HackerOne system.

curl "https://api.hackerone.com/v1/programs/11000/bounties" \
  -X POST \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ=" \
  -H "Content-Type: application/json" \
  -d @- <<EOD
    {
      "data": {
        "type": "bounty",
        "attributes": {
          "amount": 100,
          "reference": "JIRA1239",
          "title": "Reflected XSS on marketing.example.com",
          "recipient": "hacker@hackerone.com",
          "currency": "USD",
          "severity_rating": "high"
        }
      }
    }
EOD

Program management

This section will dive deeper into querying your program information using the API. All endpoints in this section require your program ID. To find your program ID, you can use the following query:

curl "https://api.hackerone.com/v1/me/programs" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

This endpoint returns all programs and their IDs this API token can access.

Finding team members and groups

You can use the read program endpoint to get basic information about your program and its members. The endpoint will return team members and groups associated with the program which can be used to easily see all members of a certain user group.

In the example below, we use the program 11000 which is the ID of our example program.

curl "https://api.hackerone.com/v1/programs/11000" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

Fetching the balance

Most programs have a deposit at HackerOne that can be used for bounty payments.

A program that’s using a credit card, won’t have a balance as bounties are directly charged on the credit card. See our documentation for more information about our different payment methods.

curl "https://api.hackerone.com/v1/programs/11000/billing/balance" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

The balance returned is the total balance available in the program. Both the bounty and bounty fee (if applicable) will be paid from this balance.

Fetching billing transactions

All financial transactions made in your HackerOne program are accessible via the transactions endpoint. This endpoint returns a transaction for each change to your balance. This can be a bounty payment, deposit, move of funds, etc.

curl "https://api.hackerone.com/v1/programs/11000/billing/transactions?month=9&year=2019" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

Billing transactions are only available for programs that are in private or public mode. If the program is still in the sandboxed mode, this endpoint will return a 403 response.

Checking if a hacker is participating in your program

Programs that are in private mode can only be accessed by hackers that are invited to the program. To confirm if a hacker is invited and has access, you can query the hacker by using the show user endpoint. In the example below, we’re querying the user fransrosen:

curl "https://api.hackerone.com/v1/users/fransrosen" \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

The API will respond with some basic user information and a list of private programs (participating_programs) the user has access to. Note that you won’t be able to see private programs you can’t access yourself.

Managing policy

Some companies have their policy page stored in a central git repository for better change management. With the policy endpoint, you can easily keep your policy page in HackerOne up to date based on the changes you’re making externally.

curl "https://api.hackerone.com/v1/programs/11000/policy" \
  -X PUT \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ=" \
  -H "Content-Type: application/json" \
  -d @- <<EOD
    {
      "data": {
        "type": "program-policy",
        "attributes": {
          "policy": "..."
        }
      }
    }
EOD

Changing the policy text will automatically notify hackers that are subscribed to the program about the policy change.

Adding attachments to the policy

If you have any files that are relevant for hackers, for example an APK file with a special version of your app, you can easily upload these to the policy page using the policy attachments endpoint. This endpoint enables you to upload any file to the policy and use the policy endpoint to include it in the policy.

curl "https://api.hackerone.com/v1/programs/3774/policy_attachments" \
  -X POST \
  -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ=" \
  -F "file=@/tmp/example.png"
EOD

The API will respond with an ID that can be included as {ID} in the policy of the program using the policy endpoint.