Configuration Overview

# send BBOT traffic through an HTTP proxy
bbot -t evilcorp.com -c http_proxy=http://127.0.0.1:8080

http_proxy: http://127.0.0.1:8080

modules:
  shodan_dns:
    api_key: deadbeef

bbot -c modules.shodan_dns.api_key=deadbeef

### BASIC OPTIONS ###

# NOTE: If used in a preset, these options must be nested underneath "config:" like so:
# config:
#   home: ~/.bbot
#   keep_scans: 20
#   scope:
#     strict: true
#   dns:
#     minimal: true

# BBOT working directory
home: ~/.bbot
# How many scan results to keep before cleaning up the older ones
keep_scans: 20
# Interval for displaying status messages
status_frequency: 15
# When system memory exceeds this percentage, ingress is throttled with a per-event sleep
# that scales linearly from 0s at the threshold up to 5s at threshold+5 (capped at 95%).
# Last-ditch effort to give the pipeline a chance to drain before OOM.
max_mem_percent: 90
# Include the raw data of files (i.e. PDFs, web screenshots) as base64 in the event
file_blobs: false
# Include the raw data of directories (i.e. git repos) as tar.gz base64 in the event
folder_blobs: false

### SCOPE ###

scope:
  # strict scope means only exact DNS names are considered in-scope
  # their subdomains are not included unless explicitly added to the target
  strict: false
  # Filter by scope distance which events are displayed in the output
  # 0 == show only in-scope events (affiliates are always shown)
  # 1 == show all events up to distance-1 (1 hop from target)
  report_distance: 0
  # How far out from the main scope to search
  # Do not change this setting unless you know what you're doing
  search_distance: 0

### DNS ###

dns:
  # Completely disable DNS resolution (careful if you have IP targets/blacklists, consider using minimal=true instead)
  disable: false
  # Speed up scan by not creating any new DNS events, and only resolving A and AAAA records
  minimal: false
  # How many threads to use per resolver (best way to increase speed is to put more resolvers in /etc/resolv.conf)
  threads: 10
  # How many DNS records to cache
  cache_size: 100000
  # How many concurrent DNS resolvers to use when brute-forcing
  # (under the hood this is passed through directly to massdns -s)
  brute_threads: 1000
  # nameservers to use for DNS brute-forcing
  # default is updated weekly and contains ~10K high-quality public servers
  brute_nameservers: https://raw.githubusercontent.com/blacklanternsecurity/public-dns-servers/master/nameservers.txt
  # How far away from the main target to explore via DNS resolution (independent of scope.search_distance)
  # This is safe to change
  search_distance: 1
  # Limit how many DNS records can be followed in a row (stop malicious/runaway DNS records)
  runaway_limit: 5
  # DNS query timeout
  timeout: 5
  # How many times to retry DNS queries
  retries: 1
  # Completely disable BBOT's DNS wildcard detection
  wildcard_disable: False
  # Disable BBOT's DNS wildcard detection for select domains
  wildcard_ignore: []
  # How many sanity checks to make when verifying wildcard DNS
  # Increase this value if BBOT's wildcard detection isn't working
  wildcard_tests: 10
  # Skip DNS requests for a certain domain and rdtype after encountering this many timeouts or SERVFAILs
  # This helps prevent faulty DNS servers from hanging up the scan
  abort_threshold: 10
  # Treat hostnames discovered via PTR records as affiliates instead of in-scope
  # This prevents rDNS results (e.g. 1-2-3-4.ptr.example.com) from triggering
  # subdomain enumeration against unrelated domains when scanning IP ranges
  filter_ptrs: true
  # Enable/disable debug messages for DNS queries
  debug: false
  # For performance reasons, always skip these DNS queries
  # Microsoft's DNS infrastructure is misconfigured so that certain queries to mail.protection.outlook.com always time out
  omit_queries:
    - SRV:mail.protection.outlook.com
    - CNAME:mail.protection.outlook.com
    - TXT:mail.protection.outlook.com

### WEB ###

web:
  # HTTP proxy
  http_proxy:
  # Hosts/CIDRs to exclude from HTTP proxy (NO_PROXY equivalent)
  # Examples: ["localhost", "*.internal.corp", "10.0.0.0/8", "elastic.mycompany.com"]
  http_proxy_exclude: []
  # Web user-agent
  user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36 Edg/119.0.2151.97
  # Suffix to append to user-agent (e.g. for tracking or identification)
  user_agent_suffix:
  # Set the maximum number of HTTP links that can be followed in a row (0 == no spidering allowed)
  spider_distance: 0
  # Set the maximum directory depth for the web spider
  spider_depth: 1
  # Set the maximum number of links that can be followed per page
  spider_links_per_page: 25
  # HTTP timeout (for Python requests; API calls, etc.)
  http_timeout: 10
  # HTTP timeout (for blasthttp)
  blasthttp_timeout: 5
  # Custom HTTP headers (e.g. cookies, etc.)
  # in the format { "Header-Key": "header_value" }
  # These are attached to all in-scope HTTP requests
  # Note that some modules (e.g. github) may end up sending these to out-of-scope resources
  http_headers: {}
  # How many times to retry API requests
  # Note that this is a separate mechanism on top of HTTP retries
  # which will retry API requests that don't return a successful status code
  api_retries: 2
  # HTTP retries - try again if the raw connection fails
  http_retries: 1
  # HTTP retries (for blasthttp)
  blasthttp_retries: 1
  # Default sleep interval when rate limited by 429 (and retry-after isn't provided)
  429_sleep_interval: 30
  # Maximum sleep interval when rate limited by 429 (and an excessive retry-after is provided)
  429_max_sleep_interval: 60
  # Enable/disable debug messages for web requests/responses
  debug: false
  # Maximum number of HTTP redirects to follow
  http_max_redirects: 5
  # Whether to verify SSL certificates
  ssl_verify: false
  # Maximum HTTP requests per second (0 = unlimited)
  # Applies globally across all blasthttp consumers (http probing, web brute, etc.)
  http_rate_limit: 0
  # HTTP_RESPONSE body disk-spill — keeps body bytes off the Python heap.
  # Bodies are written to ${scan_home}/temp/bodies/{uuid}.body.zst and served
  # from a bounded LRU cache; only cache misses touch disk.
  body_spill:
    # Master switch
    enabled: true
    # In-memory LRU cache budget for hot bodies, in MB
    cache_mb: 512
    # zstd level-1 compression on the way to disk
    compress: true

### ENGINE ###

engine:
  debug: false

# Tool dependencies
deps:
  # How to handle installation of module dependencies
  # Choices are:
  #  - abort_on_failure (default) - if a module dependency fails to install, abort the scan
  #  - retry_failed - try again to install failed dependencies
  #  - ignore_failed - run the scan regardless of what happens with dependency installation
  #  - disable - completely disable BBOT's dependency system (you are responsible for installing tools, pip packages, etc.)
  behavior: abort_on_failure

### ADVANCED OPTIONS ###

# Load BBOT modules from these custom paths
module_dirs: []

# maximum runtime in seconds for each module's handle_event() is 60 minutes
# when the timeout is reached, the offending handle_event() will be cancelled and the module will move on to the next event
module_handle_event_timeout: 3600
# handle_batch() default timeout is 2 hours
module_handle_batch_timeout: 7200

# Infer certain events from others, e.g. IPs from IP ranges, DNS_NAMEs from URLs, etc.
speculate: True
# Passively search event data for URLs, hostnames, emails, etc.
excavate: True
# Summarize activity at the end of a scan
aggregate: True
# DNS resolution, wildcard detection, etc.
dnsresolve: True
# Cloud provider tagging
cloudcheck: True

# Strip querystring from URLs by default
url_querystring_remove: True
# When query string is retained, by default collapse parameter values down to a single value per parameter
url_querystring_collapse: True

# Completely ignore URLs with these extensions
url_extension_blacklist:
  # images
  - png
  - jpg
  - bmp
  - ico
  - jpeg
  - gif
  - svg
  - webp
  # web/fonts
  - css
  - woff
  - woff2
  - ttf
  - eot
  - sass
  - scss
  # audio
  - mp3
  - m4a
  - wav
  - flac
  # video
  - mp4
  - mkv
  - avi
  - wmv
  - mov
  - flv
  - webm

# URLs with these extensions are not distributed to modules unless the module opts in via `accept_url_special = True`
# They are also excluded from output. If you want to see them in output, remove them from this list.
url_extension_special:
  - js

# These url extensions are almost always static, so we exclude them from modules that fuzz things
url_extension_static:
  - pdf
  - doc
  - docx
  - xls
  - xlsx
  - ppt
  - pptx
  - txt
  - csv
  - xml
  - yaml
  - ini
  - log
  - conf
  - cfg
  - env
  - md
  - rtf
  - tiff
  - bmp
  - jpg
  - jpeg
  - png
  - gif
  - svg
  - ico
  - mp3
  - wav
  - flac
  - mp4
  - mov
  - avi
  - mkv
  - webm
  - zip
  - tar
  - gz
  - bz2
  - 7z
  - rar

parameter_blacklist:
  - __VIEWSTATE
  - __EVENTARGUMENT
  - __EVENTVALIDATION
  - __EVENTTARGET
  - __EVENTARGUMENT
  - __VIEWSTATEGENERATOR
  - __SCROLLPOSITIONY
  - __SCROLLPOSITIONX
  - ASP.NET_SessionId
  - .AspNetCore.Session
  - PHPSESSID
  - sessionid
  - csrftoken
  - __cf_bm
  - cf_clearance
  - _abck
  - bm_sz
  - ak_bmsc
  - f5_cspm
  - _ga
  - _gid
  - _gat
  - _gcl_au
  - _fbp
  - _fbc
  - __utma
  - __utmb
  - __utmc
  - __utmz
  - _hjid

parameter_blacklist_prefixes:
  - TS01
  - BIGipServer
  - f5avr
  - incap_
  - visid_incap_
  - AWSALB
  - utm_
  - ApplicationGatewayAffinity
  - JSESSIONID
  - ARRAffinity
  - _hjSession
  - _gat_
  - intercom-

# Don't output these types of events (they are still distributed to modules)
omit_event_types:
  - HTTP_RESPONSE
  - RAW_TEXT
  - URL_UNVERIFIED
  - DNS_NAME_UNRESOLVED
  - FILESYSTEM
  - WEB_PARAMETER
  - RAW_DNS_RECORD
  # - IP_ADDRESS

# Custom interactsh server settings
interactsh_server: null
interactsh_token: null
interactsh_disable: false

# API key for bbot.io services (currently used by ASN lookups via the asndb library)
# Can also be set via the BBOT_IO_API_KEY environment variable, which takes precedence.
bbot_io_api_key: null