Adding labels to findings

Labels provide a way to add more contextual data to findings generated by Forta bots. This information can be used to answer questions like "which addresses have been involved in flashloan attacks?" or "which blocks contain exploits?". The Forta bot SDK provides an easy way to specify labels which this page will describe.

Adding labels

Bots return Finding objects from their handler functions, which now includes a labels field to specify a list of labels to add. Here is an example of adding labels:

Finding.from({
  name: "High Tether Transfer",
  description: "High amount of USDT transferred",
  alertId: "FORTA-1",
  severity: FindingSeverity.High,
  type: FindingType.Suspicious,
  labels: [
    {
      entityType: EntityType.Address,
      entity: "0x062dB680e5DCA653248432fC1B4F788E41c83234",
      label: "attacker",
      confidence: 0.9,
    },
    {
      entityType: EntityType.Transaction,
      entity:
        "0xfb141d179b40d895ba227c26860d7f49744fe50bdf89a6e6e21978c09c7ac05f",
      label: "flashloan-attack",
      confidence: 0.7,
      metadata: {
        exploitedProtocol: "someDAO"
      }
    },
  ],
});

The first label in the above code snippet is saying with 90% certainty that the specified address is an attacker. The second label is saying with 70% certainty that the specified transaction is a flashloan attack. You can also optionally add more data using the metadata field.

You can add one or more label objects to a Finding. Each label object should specify all the 4 required fields: entity, entityType, label and confidence. The label field can be any string you choose to allow flexibility of supporting many different types of labels. The entity is the item being described and is of entityType which supports 5 different types: Address, Transaction, Block, Url and Unknown. The confidence level should be a number between 0 and 1.

Removing labels

You can also remove labels from entities which works very similarly to adding labels. The only difference is setting the remove field to the boolean true value on the label. For example, if we wanted to now remove the "flashloan-attack" label from the transaction that we specified above, we can do this in a subsequent finding like so:

Finding.from({
  name: "High Tether Transfer",
  description: "High amount of USDT transferred",
  alertId: "FORTA-1",
  severity: FindingSeverity.High,
  type: FindingType.Suspicious,
  labels: [
    {
      entityType: EntityType.Transaction,
      entity:
        "0xfb141d179b40d895ba227c26860d7f49744fe50bdf89a6e6e21978c09c7ac05f",
      label: "flashloan-attack",
      confidence: 0.7,
      remove: true,
    },
  ],
});

Notice that all values of the label are the same, but we just added remove: true.

Querying labels

You can query for labels using the Forta GraphQL API.