# Events

An Event is a piece of data discovered by BBOT. Examples include `IP_ADDRESS`, `DNS_NAME`, `EMAIL_ADDRESS`, `URL`, etc. When you run a BBOT scan, events are constantly being exchanged between modules. They are also output to the console:

```text
[DNS_NAME]      www.evilcorp.com    sslcert         (distance-0, in-scope, resolved, subdomain, a-record)
 ^^^^^^^^       ^^^^^^^^^^^^^^^^    ^^^^^^^          ^^^^^^^^^^
event type      event data          source module    tags
```

## Findings

All vulnerability discoveries, security-relevant observations, and other notable results in BBOT are emitted as **`FINDING`** events.

Each finding has a **severity** and a **confidence**:

* **Severity** indicates impact: `INFO`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`
* **Confidence** indicates how certain the finding is: `CONFIRMED`, `HIGH`, `MEDIUM`, `LOW`, or `UNKNOWN`

Together, these let you quickly prioritize results -- e.g. a `CRITICAL` severity with `CONFIRMED` confidence is immediately actionable, while a `MEDIUM` severity with `LOW` confidence may need manual verification.

## Event Attributes

Each BBOT event has the following attributes. Not all of these attributes are visible in the terminal output. However, they are always saved in `output.json` in the scan output folder. If you want to see them on the terminal, you can use `--json`.

- `.type`: the event type (e.g. `DNS_NAME`, `IP_ADDRESS`, `OPEN_TCP_PORT`, etc.)
- `.id`: an identifier representing the event type + a SHA1 hash of its data (note: multiple events can have the same `.id`)
- `.uuid`: a universally unique identifier for the event (e.g. `DNS_NAME:6c96d512-090a-47f0-82e4-6860e46aac13`)
- `.scope_description`: describes the scope of the event (e.g. `in-scope`, `affiliate`, `distance-2`)
- `.data`: the actual discovered data (for some events like `DNS_NAME` or `IP_ADDRESS`, this is a string. For other more complex events like `HTTP_RESPONSE`, it's a dictionary). In JSON output it's serialized as `data` or `data_json` depending on its type (see below).
- `.host`: the hostname or IP address (e.g. `evilcorp.com` or `1.2.3.4`)
- `.port`: the port number (e.g. `80`, `443`)
- `.netloc`: the network location, including both the hostname and port (e.g. `www.evilcorp.com:443`)
- `.resolved_hosts`: a list of all resolved hosts for the event (`A`, `AAAA`, and `CNAME` records)
- `.dns_children`: a dictionary of all DNS records for the event (typically only present on `DNS_NAME`)
- `.web_spider_distance`: a count of how many URL links have been followed in a row to get to this event
- `.scope_distance`: a count of how many hops it is from the main scope (0 == in-scope)
- `.scan`: the ID of the scan that produced the event
- `.timestamp`: the date/time when the event was discovered
- `.parent`: the ID of the parent event that led to the discovery of this event
- `.parent_uuid`: the universally unique identifier for the parent event
- `.tags`: a list of tags describing the event (e.g. `mx-record`, `http-title`, etc.)
- `.module`: the module that discovered the event
- `.module_sequence`: the recent sequence of modules that were executed to discover the event (including omitted events)
- `.host_metadata`: cloud provider, ASN, and other metadata about the host (when available)
- `.discovery_context`: a description of the context in which the event was discovered
- `.discovery_path`: a list of every discovery context leading to this event
- `.parent_chain`: a list of every event UUID leading to the discovery of this event (corresponds exactly to `.discovery_path`)

These attributes allow us to construct a visual graph of events (e.g. in [Neo4j](output.md#neo4j)) and query/filter/grep them more easily. Here is what a typical event looks like in JSON format:

```json
{
  "type": "DNS_NAME",
  "id": "DNS_NAME:33bc005c2bdfea4d73e07db733bd11861cf6520e",
  "uuid": "DNS_NAME:6c96d512-090a-47f0-82e4-6860e46aac13",
  "scope_description": "in-scope",
  "netloc": "link.evilcorp.com",
  "data": "link.evilcorp.com",
  "host": "link.evilcorp.com",
  "resolved_hosts": [
    "184.31.52.65",
    "2600:1402:b800:d82::700",
    "2600:1402:b800:d87::700",
    "link.evilcorp.com.edgekey.net"
  ],
  "dns_children": {
    "A": [
      "184.31.52.65"
    ],
    "AAAA": [
      "2600:1402:b800:d82::700",
      "2600:1402:b800:d87::700"
    ],
    "CNAME": [
      "link.evilcorp.com.edgekey.net"
    ]
  },
  "web_spider_distance": 0,
  "scope_distance": 0,
  "scan": "SCAN:b6ef48bc036bc8d001595ae5061846a7e6beadb6",
  "timestamp": 1729266013.71688,
  "parent": "DNS_NAME:94c92b7eaed431b37ae2a757fec4e678cc3bd213",
  "parent_uuid": "DNS_NAME:c737dffa-d4f0-4b6e-a72d-cc8c05bd892e",
  "tags": [
    "a-record",
    "aaaa-record",
    "cdn-akamai",
    "cname-record",
    "in-scope",
    "subdomain"
  ],
  "module": "speculate",
  "module_sequence": "speculate->speculate",
  "discovery_context": "speculated parent DNS_NAME: link.evilcorp.com",
  "discovery_path": [
    "Scan insidious_frederick seeded with DNS_NAME: evilcorp.com",
    "TXT record for evilcorp.com contains IP_ADDRESS: 149.72.247.52",
    "PTR record for 149.72.247.52 contains DNS_NAME: o1.ptr2410.link.evilcorp.com",
    "speculated parent DNS_NAME: ptr2410.link.evilcorp.com",
    "speculated parent DNS_NAME: link.evilcorp.com"
  ],
  "parent_chain": [
    "DNS_NAME:34c657a3-0bfa-457e-9e6e-0f22f04b8da5",
    "IP_ADDRESS:efc0fb3b-1b42-44da-916e-83db2360e10e",
    "DNS_NAME:c737dffa-d4f0-4b6e-a72d-cc8c05bd892e",
    "DNS_NAME_UNRESOLVED:722a3473-30c6-40f1-90aa-908d47105d5a",
    "DNS_NAME:6c96d512-090a-47f0-82e4-6860e46aac13"
  ]
}
```

### `data` vs `data_json`

When events are serialized to JSON (`output.json`, the `json` output module, or `--json`), the data field is named after its type, so a given key always holds a consistent type. This makes parsing far easier for scripts and aggregation tools like Elasticsearch:

- **`data`** -- a string, for events whose data is a string (`DNS_NAME`, `IP_ADDRESS`, `URL`, ...). The example above is a `DNS_NAME`, so its value lives under `data`.
- **`data_json`** -- a dictionary, for events whose data is structured (`HTTP_RESPONSE`, `FINDING`, `STORAGE_BUCKET`, ...).

Exactly one of the two is present per event. When reading events back, check `data_json` first and fall back to `data`.

For a more detailed description of BBOT events, see [Developer Documentation - Event](../dev/event.md).

Below is a full list of event types along with which modules produce/consume them.

## List of Event Types

<!-- BBOT EVENTS -->
| Event Type          | # Consuming Modules   | # Producing Modules   | Consuming Modules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Producing Modules                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
|---------------------|-----------------------|-----------------------| |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| *                   | 24                    | 0                     | affiliates, cloudcheck, csv, discord, dnsresolve, elastic, json, kafka, mongo, mysql, nats, neo4j, postgres, python, rabbitmq, slack, splunk, sqlite, stdout, teams, txt, webhook, websocket, zeromq                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ASN                 | 0                     | 1                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | asn                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| AZURE_TENANT        | 1                     | 1                     | speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | azure_tenant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| CODE_REPOSITORY     | 8                     | 8                     | docker_pull, git_clone, gitdumper, github_workflows, google_playstore, postman_download, trajan, trufflehog                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | code_repository, dockerhub, git, github_codesearch, github_org, gitlab_com, gitlab_onprem, postman                                                                                                                                                                                                                                                                                                                                                                                                     |
| DNS_NAME            | 57                    | 39                    | anubisdb, asset_inventory, azure_tenant, baddns, baddns_zone, bevigil, bucket_amazon, bucket_digitalocean, bucket_firebase, bucket_google, bucket_hetzner, bucket_microsoft, bufferoverrun, builtwith, c99, censys_dns, certspotter, chaos, credshed, crt, crt_db, dehashed, dnsbimi, dnsbrute, dnsbrute_mutations, dnscaa, dnscommonsrv, dnsdumpster, dnstlsrpt, emailformat, fullhunt, github_codesearch, github_usersearch, hackertarget, hunterio, leakix, myssl, nmap_xml, oauth, otx, pgp, portscan, rapiddns, securitytrails, securitytxt, shodan_dns, shodan_idb, skymem, speculate, subdomaincenter, subdomainradar, subdomains, trickest, urlscan, viewdns, virustotal, wayback | anubisdb, azure_tenant, bevigil, bufferoverrun, builtwith, c99, censys_dns, censys_ip, certspotter, chaos, crt, crt_db, dnsbrute, dnsbrute_mutations, dnscaa, dnscommonsrv, dnsdumpster, dnsresolve, fullhunt, hackertarget, hunterio, leakix, myssl, ntlm, oauth, otx, rapiddns, securitytrails, shodan_dns, shodan_idb, speculate, sslcert, subdomaincenter, subdomainradar, trickest, urlscan, viewdns, virustotal, wayback                                                                         |
| DNS_NAME_UNRESOLVED | 3                     | 0                     | baddns, speculate, subdomains                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| DNS_NAME_UNVERIFIED | 0                     | 1                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | virtualhost                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| EMAIL_ADDRESS       | 1                     | 11                    | emails                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | credshed, dehashed, dnscaa, dnstlsrpt, emailformat, github_usersearch, hunterio, pgp, securitytxt, skymem, sslcert                                                                                                                                                                                                                                                                                                                                                                                     |
| FILESYSTEM          | 4                     | 9                     | jadx, kreuzberg, trufflehog, unarchive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | apkpure, docker_pull, filedownload, git_clone, gitdumper, github_workflows, jadx, postman_download, unarchive                                                                                                                                                                                                                                                                                                                                                                                          |
| FINDING             | 2                     | 38                    | asset_inventory, web_report                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | ajaxpro, aspnet_bin_exposure, azure_tenant, baddns, baddns_direct, baddns_zone, badsecrets, bucket_amazon, bucket_digitalocean, bucket_firebase, bucket_google, bucket_hetzner, bucket_microsoft, bypass403, dotnetnuke, generic_ssrf, git, gitlab_onprem, graphql_introspection, host_header, hunt, legba, lightfuzz, medusa, newsletters, ntlm, nuclei, reflected_parameters, retirejs, shodan_enterprise, shodan_idb, speculate, telerik, trajan, trufflehog, url_manipulation, waf_bypass, wayback |
| GEOLOCATION         | 0                     | 2                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | ip2location, ipstack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| HASHED_PASSWORD     | 0                     | 2                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | credshed, dehashed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| HTTP_RESPONSE       | 18                    | 4                     | ajaxpro, asset_inventory, badsecrets, dotnetnuke, excavate, filedownload, gitlab_onprem, host_header, newsletters, nmap_xml, ntlm, paramminer_cookies, paramminer_getparams, paramminer_headers, speculate, sslcert, telerik, trufflehog                                                                                                                                                                                                                                                                                                                                                                                                                                                  | http, lightfuzz, virtualhost, wayback                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| IP_ADDRESS          | 11                    | 5                     | asn, asset_inventory, censys_ip, ip2location, ipneighbor, ipstack, nmap_xml, portscan, shodan_enterprise, shodan_idb, speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | asset_inventory, censys_ip, dnsresolve, ipneighbor, speculate                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| IP_RANGE            | 2                     | 1                     | portscan, speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | dnsresolve                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| MOBILE_APP          | 1                     | 1                     | apkpure                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | google_playstore                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| OPEN_TCP_PORT       | 5                     | 6                     | asset_inventory, fingerprintx, http, nmap_xml, portfilter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | asset_inventory, censys_ip, portscan, shodan_enterprise, shodan_idb, speculate                                                                                                                                                                                                                                                                                                                                                                                                                         |
| OPEN_UDP_PORT       | 0                     | 2                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | censys_ip, shodan_enterprise                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ORG_STUB            | 4                     | 1                     | dockerhub, github_org, google_playstore, postman                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| PASSWORD            | 0                     | 2                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | credshed, dehashed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| PROTOCOL            | 3                     | 2                     | legba, medusa, nmap_xml                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | censys_ip, fingerprintx                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| RAW_DNS_RECORD      | 0                     | 3                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | dnsbimi, dnsresolve, dnstlsrpt                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| RAW_TEXT            | 2                     | 1                     | excavate, trufflehog                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | kreuzberg                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| SOCIAL              | 7                     | 4                     | dockerhub, github_org, gitlab_com, gitlab_onprem, gowitness, postman, speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | dockerhub, github_usersearch, gitlab_onprem, social                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| STORAGE_BUCKET      | 9                     | 6                     | baddns_direct, bucket_amazon, bucket_digitalocean, bucket_file_enum, bucket_firebase, bucket_google, bucket_hetzner, bucket_microsoft, speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | bucket_amazon, bucket_digitalocean, bucket_firebase, bucket_google, bucket_hetzner, bucket_microsoft                                                                                                                                                                                                                                                                                                                                                                                                   |
| TECHNOLOGY          | 4                     | 9                     | asset_inventory, gitlab_onprem, trajan, web_report                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | ajaxpro, badsecrets, censys_ip, dotnetnuke, gitlab_onprem, gowitness, nuclei, shodan_enterprise, shodan_idb                                                                                                                                                                                                                                                                                                                                                                                            |
| URL                 | 25                    | 2                     | ajaxpro, aspnet_bin_exposure, asset_inventory, baddns_direct, bypass403, generic_ssrf, git, gowitness, graphql_introspection, http, iis_shortnames, lightfuzz, ntlm, nuclei, portfilter, robots, speculate, telerik, url_manipulation, virtualhost, waf_bypass, wafw00f, wayback, web_report, webbrute                                                                                                                                                                                                                                                                                                                                                                                    | gowitness, http                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| URL_HINT            | 1                     | 1                     | webbrute_shortnames                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | iis_shortnames                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| URL_UNVERIFIED      | 9                     | 19                    | code_repository, filedownload, http, oauth, portfilter, retirejs, social, speculate, trajan                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | azure_tenant, bevigil, bucket_file_enum, censys_ip, dnsbimi, dnscaa, dnstlsrpt, dockerhub, excavate, fingerprintx, github_codesearch, gowitness, hunterio, robots, securitytxt, urlscan, wayback, webbrute, webbrute_shortnames                                                                                                                                                                                                                                                                        |
| USERNAME            | 1                     | 2                     | speculate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | credshed, dehashed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| VIRTUAL_HOST        | 0                     | 1                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | virtualhost                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| WAF                 | 1                     | 1                     | asset_inventory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | wafw00f                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| WEBSCREENSHOT       | 0                     | 1                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | gowitness                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| WEB_PARAMETER       | 7                     | 5                     | hunt, lightfuzz, paramminer_cookies, paramminer_getparams, paramminer_headers, reflected_parameters, web_parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | excavate, paramminer_cookies, paramminer_getparams, paramminer_headers, wayback                                                                                                                                                                                                                                                                                                                                                                                                                        |
<!-- END BBOT EVENTS -->

[Next Up: Output -->](./output.md){ .md-button .md-button--primary }
