API Documentation

BruteSight provides real-time threat intelligence feeds generated from a global network of honeypots.

Use this API to programmatically access attack data, generate dynamic blocklists for firewalls, or ingest logs from your own servers into the collective intelligence pool.

Authentication

All API requests to secured endpoints must include your unique API key. Keys can be passed in one of two ways:

1. HTTP Header (Recommended): X-API-Key: YOUR_API_KEY
2. Query Parameter (For legacy devices): ?api_key=YOUR_API_KEY

1. Ingestion API (Agent Reporting)

Use this endpoint to report brute-force attacks (e.g., SSH, RDP, FTP) from your local servers to the global BruteSight network. This endpoint is highly optimized for rapid, high-volume ingestion.

Headers: Content-Type: application/json

Request Payload Example

You can send logs individually or batch them in an array to save bandwidth.

{
  "meta": {
    "version": "1.8.5",
    "source_ip": "198.51.100.12"
  },
  "logs": [
    {
      "username": "root",
      "hostname": "203.0.113.45",
      "login_time": "2026-05-02 14:32:01",
      "raw_entry": "Failed password for root from 203.0.113.45 port 49152 ssh2",
      "subnet_24": "203.0.113.0/24"
    }
  ]
}

Response Example

{
  "status": "success",
  "inserted": 1
}

*Note: If your agent is outdated, the response headers will include X-Agent-Update-Required: true along with the latest script hash in X-Latest-Agent-Version.*

2. Threat Feed Consumption APIs

Our consumption APIs are designed for automated firewalls, routers, and SIEMs.

Generic Text Feed

For pfSense, iptables, and generic firewalls. Returns a flat, line-by-line list.

Example Request: GET /api/v1/list/plain?mincount=10&type=cidr&days=7

192.168.1.0/24
10.0.0.0/24
172.16.55.0/24

Mikrotik RouterOS

Dynamically generates a .rsc script that can be imported directly into Mikrotik routers.

• list_name (string): The name of the address list in RouterOS (Default: Blacklist_SSH).
• timeout (string): Expiration time for the block rule (e.g., 2d, 12h).

Example Request: GET /api/v1/list/mikrotik?list_name=BruteSight&timeout=7d&mincount=50

/ip firewall address-list
add list=BruteSight address=203.0.113.45 timeout=7d comment="ASN:64496 CC:US Hits:450"
add list=BruteSight address=198.51.100.22 timeout=7d comment="ASN:64500 CC:GB Hits:112"

Cisco IOS ACL

Generates standard Access Control Lists with calculated wildcard masks for Cisco environments.

• acl_name (string): Name of the Cisco Access List (Default: BLOCK_SSH).

Example Request: GET /api/v1/list/cisco?acl_name=BLOCK_SSH&type=cidr

ip access-list standard BLOCK_SSH
 deny   192.168.1.0 0.0.0.255
 deny   10.0.0.0 0.0.0.255
 permit any

Juniper Networks

Generates policy options and prefix-lists natively formatted for Juniper routing environments.

• list_name (string): Name of the prefix-list (Default: BAD-SSH).

Example Request: GET /api/v1/list/juniper?list_name=BAD-SSH&type=cidr

policy-options {
    prefix-list BAD-SSH {
        192.168.1.0/24;
        10.0.0.0/24;
    }
}

Enterprise JSON

Returns heavily structured metadata for advanced threat hunting and ingestion pipelines (SIEMs, Palo Alto, Splunk).

{
  "meta": {
    "count": 1,
    "filters": {
      "asn": null,
      "country": null,
      "days": 30,
      "min_count": 5,
      "type": "ip"
    }
  },
  "data": [
    {
      "target": "203.0.113.45",
      "asn": "64496",
      "country_code": "US",
      "hit_count": 450
    }
  ]
}

3. Real-Time Statistics API

This endpoint powers our public dashboards and your custom internal visualizations, providing instant data retrieval across millions of records.

• days (int): Number of days to look back (Valid options: 1, 7, 30, or leave blank for All-Time).
• filter_type (string): Search parameter. Valid options: username, asn, or country.
• filter_value (string): The value corresponding to the filter_type (e.g., root, 64496, or CN).

Example Request: GET /api/v1/stats?days=7&filter_type=country&filter_value=CN

{
  "totals": {
    "hits": 1450230,
    "ips": 85401,
    "last_seen": "2026-05-02 14:32:05"
  },
  "top_countries": [
    {"country_code": "CN", "c": 1450230}
  ],
  "top_asns": [
    {"asn": "64511", "asn_description": "EXAMPLE-BACKBONE", "c": 210000}
  ],
  "top_users": [
    {"username": "root", "c": 980123}
  ],
  "recent_logs": [
    {"login_time": "2026-05-02 14:32:05", "hostname": "203.0.113.45", "username": "root", "country_code": "CN", "asn": "64511"}
  ]
}

Hardware Integrations

Use these scripts to automatically download and apply BruteSight threat feeds directly to your networking hardware.

Mikrotik Auto-Updater Script

Paste this directly into your Mikrotik terminal. It creates a script that fetches the .rsc file and a scheduler that runs it every hour. Because the API provides a timeout=7d parameter, Mikrotik automatically handles expiring old IPs, making this a completely hands-off setup.

/system script
add name=UpdateBruteSight policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive source="\
    /tool fetch url=\"https://api.brutesight.com/api/v1/list/mikrotik?list_name=BruteSight&timeout=7d\" mode=https dst-path=\"brutesight.rsc\"; \r\
    \n/import file-name=\"brutesight.rsc\"; \r\
    \n/file remove brutesight.rsc;"

/system scheduler
add interval=1h name=ScheduleBruteSight on-event=UpdateBruteSight policy=ftp,reboot,read,write,policy,test,password,sniff,sensitive start-time=startup

Cisco IOS EEM Applet

Cisco IOS uses the Embedded Event Manager (EEM) to automate tasks. This applet triggers every 3600 seconds (1 hour), safely copying the latest standard ACL over HTTP(S) directly into the running configuration.

conf t
event manager applet UPDATE_BRUTESIGHT
 event timer watchdog time 3600
 action 1.0 cli command "enable"
 action 2.0 cli command "copy https://api.brutesight.com/api/v1/list/cisco?acl_name=BLOCK_SSH running-config" pattern "\[running-config\]\?"
 action 3.0 cli command "\r"
 action 4.0 syslog msg "BruteSight ACL Successfully Updated"
end
wr mem

Juniper OS Push Script (Linux Jump Server)

Because Junos OS requires a strict "configure → commit" model, the most reliable way to update Juniper firewalls is by using a scheduled Bash script on a Linux jump-server to pull the feed and push it to the router via SSH.

#!/bin/bash
# Save this to /usr/local/bin/update_juniper.sh and schedule it via crontab

ROUTER_IP="192.168.1.1"
USER="admin"
API_URL="https://api.brutesight.com/api/v1/list/juniper?list_name=BAD-SSH&type=cidr"

# 1. Download the latest prefix-list
curl -s "$API_URL" > /tmp/brutesight.conf

# 2. SCP the configuration file to the Juniper router
scp /tmp/brutesight.conf $USER@$ROUTER_IP:/var/tmp/brutesight.conf

# 3. Execute the configuration load and commit via SSH
ssh $USER@$ROUTER_IP << 'EOF'
configure
load replace /var/tmp/brutesight.conf
commit
exit
EOF

Installing the Remote Agent

The BruteSight remote agent is a lightweight, dependency-minimal Python script (push_remote_logs.py) designed to parse local authentication logs and securely push them to the BruteSight ingestion API in batches.

1. Prerequisites

• Python 3.6 or higher
• The requests library (Install via pip install requests or apt install python3-requests)

2. Download & Install

Fetch the latest stable release of the agent script directly from the API and make it executable.

curl -o /usr/local/bin/push_remote_logs.py https://api.brutesight.com/api/v1/update-script
chmod +x /usr/local/bin/push_remote_logs.py

3. Configuration

The agent looks for its configuration file at /etc/brutesight/config.conf by default. Create this directory and file, replacing the placeholder with your actual API key.

mkdir -p /etc/brutesight
nano /etc/brutesight/config.conf

[brutesight]
api_key = YOUR_API_KEY_HERE

# Optional overrides (Defaults shown below)
# log_file = /var/log/auth.log
# state_file = /var/tmp/push_remote_logs.state
# batch_size = 50

4. Set up the Cron Job

Schedule the script to run every 5 minutes to continuously parse new logs and push them to the cloud.

crontab -e

*/5 * * * * root /usr/bin/python3 /usr/local/bin/push_remote_logs.py >> /var/log/brutesight_agent.log 2>&1

Updating the Agent

The BruteSight agent is completely self-aware of its version. Every time it pushes logs to the ingestion API, the server responds with a hash of the latest available script codebase via the X-Latest-Agent-Version HTTP header.

If your agent is outdated, you will see the following warning printed in your console or cron logs (/var/log/brutesight_agent.log):

WARNING: Script outdated! Update from docs.

How to Apply an Update

To update the agent, simply re-download the script over your existing file. Your configuration and state files will remain completely untouched.

curl -o /usr/local/bin/push_remote_logs.py https://api.brutesight.com/api/v1/update-script
chmod +x /usr/local/bin/push_remote_logs.py

The next time your cron job runs, the new version will seamlessly pick up log processing right from where the previous version left off.

Best Practices & Limits