How to Create an Automation
You can find automations by going to Organization settings>Automations, or by going to https://hackerone/com/organizations/<your_organization>/automations.
Click the Create new automation button on the top right to create a new automation. Next, select an automation template. Templates are pre-built automations that give you a headstart when setting up your automation. If you prefer to start from scratch, pick the “custom automation” template. For this example, we will pick the “Automatic inbox assignment based on asset” template and click Next.
In the next view, we have a couple of fields. The first field is the name. This distinguishes between automations, so pick something memorable and descriptive.
The next field lets you configure trigger events. Automations can have multiple trigger events, and selecting more than one means any of those events can trigger the automation. Some templates have required events that cannot be removed, and most templates limit the number of events allowed. For example, the “Automatic inbox assignment based on asset” template has only one required event, so we’ll leave it as is.
Next, we have Actions. The Actions tab includes template-specific form elements to help you easily set up the automation. For the “Inbox assignment based on asset” template, it provides dropdowns for selecting the asset and the inbox the report should be assigned to.
Once you've set up the asset-to-inbox mapping, you can save the automation. If you'd like to see exactly what the automation will do, you can also check the “Template code” tab.
How to Create a Custom Automation
HackerOne offers automation templates to give you a headstart. However, in some cases, you may want to start with a blank slate and write the code yourself.
To create a custom automation, navigate to the automation overview page. You can find this page by clicking the automations button in the main navigation or by navigating to https://hackerone/com/organizations/<your_organization>/automations.
Next, select the “custom automation” template and click Next.
The following screen has several fields. The first field, name, lets you choose a name for your automation. This is used to distinguish between automation, so pick something recognizable.
The next field allows you to configure the trigger events. Automations can have multiple trigger events. When you select multiple trigger events, any of those events will individually trigger the automation.
The last field is the code field. This lets you write custom javascript code that will be executed every time the automation runs. The code is executed in a node.js environment (version 20.x). In order for the automation to work, the javascript file should export an asynchronous function called run.
Note: The contents of the response are different for each endpoint. You can find an overview of the available endpoints at https://api.hackerone.com/customer-resources/#customer-resources.
The run function is passed an object with the following properties:
The
dataproperty. This is an object that contains the following properties:reportId: Contains the ID of the report the activity belongs to.report: A JSON representation of the report, in the same format as the API call Get Report, would return.activityId: Which contains the ID of the activity that triggered this automation run.activity: A JSON representation of the activity, in the same format as the API call Get Activity, would return.
The
configproperty. This is an object that contains the config as configured during the setup process. For automations that do not have a config, the config will be an empty object.The
apiGethandler(path: string) => Promise<Response>. This is a helper method for sending GET requests to the HackerOne API. The request is authorized with the automation’s access token. apiGet returns a promise that will resolve the parsed JSON response. The contents of the response are different for each endpoint.Note that since it returns a promise, you will need to await the response in order to use it, so:
await apiGet(‘/reports’)
The
apiPosthandler(path: string, body: JSON => Promise<Response>. This is a helper method for sending POST requests to the HackerOne API. The request is authorized with the automation’s access token. apiPost returns a promise that will resolve the parsed JSON response. The contents of the response are different for each endpoint.The
apiPuthandler (path: string, body: JSON => Promise<Response>. This is a helper method to send PUT requests to the HackerOne API. The request is authorized with the automation’s access token. apiPut returns a promise that will resolve the parsed JSON response. The contents of the response are different for each endpoint.The
apiDeletehandler (path: string, body: JSON => Promise<Response>. This is a helper method to send DELETE requests to the HackerOne API. The request is authorized with the automation’s access token. apiDelete returns a promise that will resolve the parsed JSON response. The contents of the response are different for each endpoint.The
promptHaihelper(prompt: string, context = { reportIds: number[], programHandles: string[], cveIds: string[], cweIds: string[] }) => Promise<string>. This helper method can be used to send a prompt to Hai, which will return apromise, eventually resolving Hai's response. It deals with the overhead of creating and polling a Hai completion object. Thepromptparameter contains the prompt you want to send to Hai. Thecontextparameter provides the context for Hai's reasoning, which can include report IDs, program handles, CVE IDs, or CWE IDs. If no report IDs are included, Hai will default to using the report ID of the activity that triggered the automation.
See Automation Security and Access to learn more about automation access.
In the following example, we write some custom javascript code that will post a comment when a report is closed as spam. Any calls to console.log, console.warn, console.error, etc., will appear in the log runs. You can use this to keep track of useful information about automation runs. Log runs are automatically removed after 3 months.
How to Manually Run an Automation
Automations can be manually run. This can be used to test the automation. Keep in mind that this is not a dry run. Any actions performed by the automation will be applied to your organization.
Automations are triggered by events dispatched when report activities are created. To manually trigger an event, you need to provide an activity ID. This activity will be used in the automation run.
Note: The easiest way to find the activity ID is via the activity timestamps in the inbox. Right-click on the timestamp, copy the link to the activity and find the activity ID in the link. The activity is prefixed with activity-. You only have to copy the numbers.
To trigger a run for an activity ID, click on the automation’s kebab menu (three vertical dots) and click the Run automation button. If you already know an activity ID, you can paste it here. Otherwise, you can click Help me find the activity id. This gives you the option to select a report you want to use to find the activity and then a selector with the activities of that report.
Once you have the activity ID, you can click on the automation’s kebab menu (three vertical dots) and click the Run automation button. Paste the activity ID in the input and press Run automation.
Note: A manual run still requires an activity that emits an event that triggers the automation. Check out Activity and Event Mapping to find out what type of activity you need to provide.
The run log is in the run overview. Click the kebab menu again and click on View runs.
If a run fails, the logs can contain valuable information about why it failed. To check those logs, click the Show logs link.
This shows all log messages from the automation run.