Create Custom Findings

Created by David Esposito, Modified on Mon, 7 Oct at 11:37 AM by David Esposito

You can import findings into Amplifier using a simple REST API integrations contract. Simply use your existing tooling to send a `POST` webhook to the endpoint configured inside your Security Hub and we will use the data provided to link it into your data graph. Provide payloads in the following format. If you are using Okta, JIRA, or JAMF please see the documentation linked at the end of this document.

Creation Logic

We use the following logic when ingesting findings:

Payload Properties

$.eventType	REQUIRED string	This MUST be an exact match with the custom finding entry provided inside the Webhook Integration.
$.kind	Optional string	Used to define the type of finding. This affects report numbers on the dashboards and in Chrome Extension. Defaults to CUSTOM. Valid values are ['ENDPOINT_MANAGEMENT', 'ENDPOINT_SECURITY', 'VULNERABILITY', 'IDENTITY', 'TRAINING'].
$.connector	Optional string	Attaches a custom finding to an existing connector. Useful for filtering and providing additional context to Ampy during engagements. Get the connector ID from the URL while editing the connector settings. See below for more details.
$.status	Optional string	Create or update the finding to the `OPEN` or `CLOSED` status.
$.email	Optional string	If a user is associated with the event provide the users email address and we will like the finding with any existing user.
$.serialNumber	Optional string	If an asset is associated with the event, you can provide the serial number and we will link it to other records, and any assigned owner.
$.eventId	Optional string	Used to update findings over multiple
$.traceId	Optional string	Use this to correlate an Amplifier finding with your internal events, e.g. SEIM trace id
$.context	Optional string	Contains additional information about the event. This can be used in the finding description or actions

Attaching a Connector

Navigate to the desired finding in the Security Hub
1. Click on "Integrations & Policies" in the left nav.
2. Click on the "CONFIGURE" button for the desired connector
Copy the Connector ID from the URL
1. The connector ID is the last string in the URL that is just random characters
Use that value inside the $.connector property inside the REST payload.

Examples

Minimal

curl --location 'https://events.amplifiersecurity.io/api/v1/findings/token123xyz' \
--header 'Content-Type: application/json' \
--data-raw '{
    "eventType": "Custom Training Finding",
    "email": "user123@amplifiersecurity.com",
    "context": {}
}'

Kitchen Sink

curl --location 'https://events.amplifiersecurity.io/api/v1/findings/token123xyz' \
--header 'Content-Type: application/json' \
--data-raw '{
    "eventType": "Custom Training Finding",
    "kind": "TRAINING",
    "connector": "sAyzrV6hWprZ",
    "status": "OPEN",
    "email": "user123@amplifiersecurity.com",
    "context": {
        "title": "Test Training #1003",
        "dueDate": "2023-04-17T13:00:00.000Z"
    }   
}'