Tool that calculates bot alert rate. Bot alert rate measures the rareness of a specific alert relative to the number of blockchain activity. For example, a bot alert rate can be # of bot alerts / # of contract creations in the last 24 hours
. Most Forta threat detection bots and community bots use this package to help identity anomalous alerts.
Create a Zettablock account to get an API key and set the following env variable:
ZETTABLOCK_API_KEY
First install the package and run the python example
$ pip install bot_alert_rate
$ python example.py
You can query the Zetta API to get the rate of a specific alert.
To do so, call calculate_alert_rate
with the specifics of the alert:
from bot_alert_rate import calculate_alert_rate, ScanCountType
# BSC
CHAIN_ID = 56
# sentiment analysis tx message bot - https://explorer.forta.network/bot/0xbdb84cba815103a9a72e66643fb4ff84f03f7c9a4faa1c6bb03d53c7115ddc4d
BOT_ID = "0xbdb84cba815103a9a72e66643fb4ff84f03f7c9a4faa1c6bb03d53c7115ddc4d"
ALERT_ID = "NEGATIVE-ANGER-TEXT-MESSAGE"
if __name__ == "__main__":
alert_rate = calculate_alert_rate(
CHAIN_ID, BOT_ID, ALERT_ID, ScanCountType.TX_WITH_INPUT_DATA_COUNT
)
print(alert_rate)
An alternative is to save a local history of the alerts in memory and use it to calculate the rates. The main motivation is to improve performance by avoiding web requests.
To use it, just wrap handle_block
/ handle_transaction
/ handle_alert
as follows:
@alert_history(size=10000)
def handle_block(log: BlockEvent) -> list:
pass
@alert_history(size=10000)
def handle_transaction(log: TransactionEvent) -> list:
pass
@alert_history(size=10000)
def handle_alert(log: AlertEvent) -> list:
pass
The decorator will automatically add the anomaly_score
in the metadata of the Finding
objects.
It will use the field alert_id
from the Finding
objects to identify them.
make sure the history size is big enough to contain occurences of the bot alerts!
For example, if your bot triggers ALERT-1
every 2k transactions and ALERT-2
every 10k on average:
@alert_history(size=100000)
would gather enough alerts to have a relevant estimation of the rate of both alerts.
First install the package and run the typescript example
$ npm i bot-alert-rate
$ ts-node example.ts
import { ScanCountType } from "bot-alert-rate";
import calculateAlertRate from "bot-alert-rate";
// BSC
const chainId = 56;
// sentiment analysis tx message bot - https://explorer.forta.network/bot/0xbdb84cba815103a9a72e66643fb4ff84f03f7c9a4faa1c6bb03d53c7115ddc4d
const botId = "0xbdb84cba815103a9a72e66643fb4ff84f03f7c9a4faa1c6bb03d53c7115ddc4d";
const alertId = "NEUTRAL-NEUTRAL-TEXT-MESSAGE";
calculateAlertRate(
chainId, botId, alertId, ScanCountType.TxWithInputDataCount
).then(alertRate => {
console.log(alertRate);
}).catch((error) => {
console.error(error);
});