Skip to content

Usage

Jump to bottom
tim edited this page Sep 1, 2026 · 10 revisions

Feeds API

GreedyBear is created with the aim to collect the information from the TPOTs and generate some actionable feeds, so that they can be easily accessible and act as valuable information to prevent and detect attacks.

The feeds are reachable through the following URL:

https://<greedybear_site>/api/feeds/<feed_type>/<attack_type>/<prioritize>.<format>?<flags>

The available feed_type are:

  • <honeypot_name>: attacks detected from a specific type of honeypot; for example cowrie
  • all: get all types at once

The available attack_type are:

  • scanner: IP addresses captured by the honeypots while performing attacks
  • payload_request: IP addresses and domains extracted from payloads that would have been executed after a specific attack would have been successful. This will currently only return requests recorded by the Cowrie honeypot.
  • all: get all types at once

The available prioritization mechanisms are:

  • recent: most recent IOCs seen in the last 3 days
  • persistent: these IOCs are the ones that were seen regularly by the honeypots. This feeds will start empty once no prior data was collected and will become bigger over time.
  • likely_to_recur: these IOCs are most likely to hit the honeypots again during the next day
  • most_expected_hits: these IOCs are expected to be responsible for the most hits during the next day

The available formats are:

  • txt: plain text (just one line for each IOC)
  • csv: CSV-like file (just one line for each IOC)
  • json: JSON file with additional information regarding the IOCs

The available flags are:

  • include_mass_scanners: if set, IOCs that are known mass scanners will be included in the result
  • include_tor_exit_nodes: if set, IOCs that are known tor exit nodes will be included in the result

The json result includes two predictive scores:

  • recurrence_probability (0.0-1.0): Indicates the likelihood that an IOC will reappear within the next 24 hours. Higher values suggest greater persistence of the threat.
  • expected_interactions (0+): Estimates the number of honeypot interactions anticipated from the IOC in the next 24 hours, indicating potential activity level.

The response includes a new field:

Available from version >= 3.2.0

  • attacker_country: The country associated with the attacking IP address.

These predictions are based on historical interaction patterns and are updated once a day, shortly after midnight UTC. They are the foundation of the likely_to_recur and most_expected_hits prioritization mechanisms.

Authentication

Some API endpoints require authentication. Pass your API token in the Authorization header:

Authorization: Token <your_token>

Example with curl:

curl -H "Authorization: Token <your_token>" \
  "https://<greedybear_site>/api/feeds/advanced/?feed_type=all&attack_type=all&format_=txt"

To request a token on the Honeynet instance, reach out to Matteo Lodi or another member of The Honeynet Project.

Advanced Feeds API

Available from version >= 1.4.0

For authenticated users, GreedyBear offers an additional API endpoint that provides similar functionality to the Feeds API but with enhanced customization options.

https://<greedybear_site>/api/feeds/advanced/?<query_params>

The available query parameters are:

  • feed_type: see Feeds API
  • attack_type: see Feeds API
  • asn: Filter IOCs by their Autonomous System Number. (Available from version >= 3.3.0)
  • port: Filter IOCs that have attacked a specific destination port. (Available from version >= 3.3.0)
  • min_score: Filter IOCs by a minimum recurrence probability score (0.0 to 1.0). (Available from version >= 3.3.0)
  • start_date / end_date: Filter IOCs seen within a specific date range (format: YYYY-MM-DD). (Available from version >= 3.3.0)
  • max_age: Maximum number of days since last occurrence. (default: 3)
  • min_days_seen: Minimum number of days on which an IOC must have been seen. (default: 1)
  • min_credential_count: Filter IOCs which used at least this many distinct credentials. (default: 0) (Available from version >= 3.5.0)
  • max_credential_count: Filter IOCs which used at most this many distinct credentials. (default: infinite) (Available from version >= 3.5.0)
  • include_reputation: ;-separated list of reputation values to include, e.g. known attacker or known attacker; to include IOCs without reputation. (default: include all)
  • exclude_reputation: ;-separated list of reputation values to exclude, e.g. mass scanner or mass scanner;bot, crawler. (default: exclude none)
  • feed_size: Number of IOC items to return. (default: 5000)
  • ordering: Field to order results by, with optional - prefix for descending. (default: -last_seen)
  • verbose: true to include IOC properties that contain a lot of data, e.g. the list of days it was seen. (default: false)
  • paginate: true to paginate results. This forces the json format. (default: false)
  • format_: see Feeds API (default: json). From version >= 3.3.0, additionally supports stix21 for STIX 2.1 Bundle exports.

Check the API specification to get all the details about how to use the available APIs.

This "Advanced Feeds" API is protected through authentication. Please reach out Matteo Lodi or another member of The Honeynet Project if you are interested in gaining access to this API.

Shareable Feeds API

Available from version >= 3.3.0

For authenticated users, GreedyBear allows sharing customized feeds via a signed token, which can be consumed publicly without an account.

  • /api/feeds/share (GET): Accepts the same query parameters as the Advanced Feeds API. Returns a JSON response containing a public url to consume the feed and a revoke_url.
  • /api/feeds/consume/<token> (GET): A strictly rate-limited public endpoint that allows anyone to consume the pre-configured feed using the generated token.
  • /api/feeds/revoke/<token> (GET): Instantly invalidates the share token. This endpoint can be clicked or opened directly in the browser to revoke. Only the original creator of the token (or staff) can perform this action.

ASN Aggregated Feeds API

Available from version >= 3.0.0

For authenticated users, GreedyBear offers an API endpoint that aggregates IOC data by ASN (Autonomous System Number).

https://<greedybear_site>/api/feeds/asn/?<query_params>

Query Parameters

  • feed_type (optional): See Feeds API for valid feed types. Default: all.
  • attack_type (optional): See Feeds API for valid attack types. Default: all.
  • max_age (optional): Maximum age of IOCs in days. Default: 3.
  • min_days_seen (optional): Minimum days an IOC must have been observed. Default: 1.
  • exclude_reputation (optional): ;-separated reputations to exclude (e.g., mass scanner). Default: none.
  • ordering (optional): Aggregation ordering field (e.g., total_attack_count, asn). Default: -ioc_count.
  • asn (optional): Filter results to a specific ASN.

Responses

  • Response (200): JSON array of ASN aggregation objects. Each object containing:

    • asn (int): ASN number.
    • as_name (str)`: Autonomous System Name (Available from version >= 3.3.0)
    • ioc_count (int): Number of IOCs for this ASN.
    • total_attack_count (int): Sum of attack_count for all IOCs.
    • total_interaction_count (int): Sum of interaction_count for all IOCs.
    • total_login_attempts (int): Sum of login_attempts for all IOCs.
    • honeypots (list[str]): Sorted list of unique honeypots that observed these IOCs.
    • expected_ioc_count (float): Sum of recurrence_probability for all IOCs, rounded to 4 decimals.
    • expected_interactions (float): Sum of expected_interactions for all IOCs, rounded to 4 decimals.
    • first_seen (datetime): Earliest first_seen timestamp among IOCs.
    • last_seen (datetime): Latest last_seen timestamp among IOCs.

  • Response (400): Bad Request - Missing or invalid query parameter.

Check the API specification to get all the details about how to use the available APIs.

This "ASN Aggregated Feeds" API is protected through authentication. Please reach out Matteo Lodi or another member of The Honeynet Project if you are interested in gaining access to this API.

Enrichment API

GreedyBear provides an easy-to-query API to get the information available in GB regarding the queried observable (domain or IP address).

https://<greedybear_site>/api/enrichment?query=<observable>

This "Enrichment" API is protected through authentication. Please reach out Matteo Lodi or another member of The Honeynet Project if you are interested in gaining access to this API.

If you would like to leverage this API without the need of writing even a line of code and together with a lot of other awesome tools, consider using IntelOwl.

Cowrie Session API

Available from version >= 2.1.0

For authenticated users, GreedyBear offers an API to retrieve session data from the Cowrie honeypot including command sequences, credentials, and session details. Queries can be performed using either an IP address to find all sessions from that source, or a SHA-256 hash to find sessions containing a specific command sequence.

You can query this API endpoint using the following URL:

https://<greedybear_site>/api/cowrie_session?query=<observable>

Query Parameters

  • query (required): The search term, can be either an IP address or the SHA-256 hash of a command sequence. When generating a SHA-256 hash to query a multi-line command sequence, ensure you join all command lines with a newline character (\n) before calculating the hash. This matches our internal hashing method which uses Python's "\n".join(sequence) function.
  • include_similar (optional): When true, the result is expanded to include all sessions that executed command sequences belonging to the same cluster(s) as command sequences found in the initial query result. Requires CLUSTER_COWRIE_COMMAND_SEQUENCES enabled in the env_file.
  • include_credentials (optional): When true, the response includes all credentials used across matching Cowrie sessions. Credentials are delivered in the username | password format.
  • include_session_data (optional): When true, the response includes detailed information about matching Cowrie sessions.

Responses

  • Response (200): JSON object containing:

    • query (str): The original query parameter

    • commands (list[str]): Unique command sequences (newline-delimited strings)

    • sources (list[str]): Unique source IP addresses

    • credentials (list[str], optional): Unique credentials if include_credentials=true

    • sessions (list[object], optional): Session details if include_session_data=true

      • time (datetime): Session start time
      • duration (float): Session duration in seconds
      • source (str): Source IP address
      • interactions (int): Number of interactions in session
      • credentials (list[str]): Credentials used in this session
      • commands (str): Command sequence executed (newline-delimited)

  • Response (400): Bad Request - Missing or invalid query parameter

  • Response (404): Not Found - No matching sessions found

Examples

Example 1: Query an IP Address with Credentials

Request:

GET /api/cowrie_session?query=60.188.124.194&include_credentials=true

Response:

{
  "license": "https://github.com/honeynet/GreedyBear/blob/main/FEEDS_LICENSE.md",
  "query": "60.188.124.194",
  "commands": [
    "uname -a"
  ],
  "sources": [
    "60.188.124.194"
  ],
  "credentials": [
    "ADMIN | #K2_7f@c048Z",
    "albert | admin",
    //...
    "zccloud | d5EJQLN0nid8B6HXHHxP"
  ]
}

Example 2: Query a Command Sequence Hash

Request:

GET /api/cowrie_session?query=28ba533b0f3c4df63d6b4a5ead73860697bdf735bb353e4ca928474889eb8a15

Response:

{
  "query": "28ba533b0f3c4df63d6b4a5ead73860697bdf735bb353e4ca928474889eb8a15",
  "commands": [
    "uname -a"
  ],
  "sources": [
    "60.188.124.194"
  ]
}

Example 3: Query an IP Address with Similar Sessions

Request:

GET /api/cowrie_session?query=60.188.124.194&include_similar=true

Response:

{
  "query": "60.188.124.194",
  "commands": [
    "uname -a",
    "uname -s -m"
  ],
  "sources": [
    "60.188.124.194",
    "103.106.104.87",
    "183.204.86.10",
    "221.203.35.59"
  ]
}

Payloads API

Available from version >= 3.6.0

If you are running a T-Pot payload server and set its URL in the environment file, GreedyBear stores the malware samples that T-Pot's honeypots capture. They are fetched from the T-Pot payload server by the payload extraction job, deduplicated by SHA-256 and kept in the quarantine directory. This API exposes their metadata and, for privileged users, the raw files.

The API is read-only and is protected through authentication. Pass your API token in the Authorization header as described in Authentication.

Note: The files served by the download endpoint are live malware samples. Only handle them in an isolated analysis environment.

List Payloads

GET https://<greedybear_site>/api/payloads

Returns paginated metadata for all captured payloads, most recent first. No raw file content and no file paths are returned.

Query Parameters

  • page (optional): Page number to retrieve. (default: 1)
  • page_size (optional): Number of payloads per page, up to 100. (default: 10)
  • paginate (optional): false to return the full list without pagination. (default: true)

Responses

  • Response (200): JSON object containing:

    • count (int): Total number of payloads.

    • total_pages (int): Number of available pages.

    • results (list[object]): The payloads on this page, each containing:

      • id (int): Unique identifier of the payload.
      • sha256 (str): SHA-256 hash of the payload.
      • md5 (str): MD5 hash of the payload.
      • sha1 (str): SHA-1 hash of the payload.
      • mime_type (str): MIME type of the payload file.
      • size (int): Size of the payload in bytes.
      • source_honeypots (list[str]): Names of the honeypots that captured this payload.

  • Response (401): Unauthorized - authentication credentials were not provided or are invalid.

Example

Request:

GET /api/payloads?page_size=2

Response:

{
  "count": 1337,
  "total_pages": 669,
  "results": [
    {
      "id": 1337,
      "sha256": "aa8fc4b5d7c2f4c3d3a6e2a2e0c1b7f1c9f0b1a2d3e4f5061728394a5b6c7d8e",
      "md5": "d41d8cd98f00b204e9800998ecf8427e",
      "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
      "mime_type": "application/x-executable",
      "size": 71336,
      "source_honeypots": ["Cowrie"]
    },
    {
      "id": 1336,
      "sha256": "0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "md5": "9e107d9d372bb6826bd81d3542a419d6",
      "sha1": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
      "mime_type": "text/x-shellscript",
      "size": 1024,
      "source_honeypots": ["Cowrie", "Dionaea"]
    }
  ]
}

Retrieve a Payload

GET https://<greedybear_site>/api/payloads/<sha256>

Returns the metadata of a single payload, identified by its SHA-256 hash. The response object has the same fields as the entries of the results list above.

Responses

  • Response (200): JSON object with the payload metadata.
  • Response (401): Unauthorized - authentication credentials were not provided or are invalid.
  • Response (404): Not Found - no payload with the given SHA-256 hash.

Download a Payload

GET https://<greedybear_site>/api/payloads/<sha256>/download

Streams the raw quarantined sample as an attachment (Content-Type: application/octet-stream, filename <sha256>.vir). Every download is logged with the requesting username and the payload hash.

Unlike the metadata endpoints, this one is not available to all authenticated users: the requesting user must either be staff or belong to the threat_researcher group. That group is not created automatically. An admin has to add it in the Django Admin panel under Groups (the name must be exactly threat_researcher) and assign the users who should be allowed to download samples.

Responses

  • Response (200): The raw binary file.
  • Response (401): Unauthorized - authentication credentials were not provided or are invalid.
  • Response (403): Forbidden - the user is neither staff nor a member of the threat_researcher group.
  • Response (404): Not Found - no payload with the given SHA-256 hash, or the file is no longer present in the quarantine directory.

Example

curl -H "Authorization: Token <your_token>" \
  -O -J "https://<greedybear_site>/api/payloads/<sha256>/download"

Event Ingestion

Available from version >= 3.6.0

For authenticated users, GreedyBear provides high-performance, asynchronous endpoints to ingest event data in batches and track their background processing lifecycle.

To prevent payload parsing and database overhead from blocking HTTP responses, this API offloads execution to an asynchronous background task pipeline. The endpoint validates basic payload structures, bulk-stages the raw event data directly to the database to minimize I/O block time, and immediately hands off processing to Django-Q via an asynchronous task worker, returning a tracking ID to the client instantly.

Requirements

All Event Ingestion endpoints are protected through authentication. Pass your API token in the Authorization header as described in Authentication.

Each user must have a valid and active APISource linked to their account. APISource is provisioned by system administrators and cannot be created by users. If no APISource is linked, or if the APISource is inactive, the request will be rejected with a 403 Forbidden response.

To utilize these endpoints, each event in your payload must include a valid sensor_id. If you have not registered your sensor yet, you must first create or retrieve it using the Sensor Creation API to obtain a valid ID.

APISource Setup

APISource records are managed exclusively by system administrators via the Django Admin interface.

To create an APISource:

  1. Log in to the Django Admin panel.
  2. Navigate to the APISource section.
  3. Click "Add APISource".
  4. Select the user account to associate with this APISource.
  5. Set a name for identification (e.g. "User A API Source").
  6. Ensure the APISource is marked as active.

Once saved, the user will immediately be able to access API endpoints using their assigned APISource.

Sensor Creation API

For authenticated users, GreedyBear provides an API to create or retrieve sensor records using an IP address as the primary identifier. This API is designed to be idempotent, meaning repeated requests with the same address will not create duplicate sensors.

You can access this API endpoint using the following URL:

https://<greedybear_site>/api/sensor/

Request Body

The following parameters are supported:

  • address (required) : IP address of the sensor
  • honeypot_type (optional) : free text, description of what kind of honeypot e.g. ssh
  • honeypot_software (optional) : free text, e.g. Cowrie
  • honeypot_description (optional) : free text, human readable description of the honeypot
  • sensor_label (optional) : free text, identifying name of the sensor
  • group_label (optional) : free text, name of a group of sensors that this sensor belongs to
  • country_code (optional) : 2 characters, ISO code of the country where the sensor is located, e.g. FR
  • asn (optional) : integer, AS number of the AS where the sensor is located, e.g. 12345

Responses

  • Response (201): Created - returned when a new sensor is successfully created.
  • Response (200): OK - returned when the sensor already exists.
  • Response (400): Bad Request - invalid input data, such as a malformed IP address, an invalid country code, or an invalid ASN format.
  • Response (403): Forbidden - the user is not authenticated, or no APISource is linked to the user account.

Example response when a new sensor is created:

{
  "id": 123,
  "message": "Sensor created successfully"
}

Example response when the sensor already exists:

{
  "id": 123,
  "message": "Sensor already existed"
}

Event Creation API

Endpoint URL

POST https://<greedybear_site>/api/events/add/

Request Configuration

  • Content-Type: application/json
  • Batch Constraints: Minimum 1 event, Maximum 10,000 events per payload.

Request Body Fields

The JSON payload must contain a root key "events" mapping to an array of event objects.

Required fields, per event:

Parameter Type Validation / Constraints Description
src_ip String Valid IP Address format The source IP address that generated the event.
event_type String Max length: 100 The category of the event (e.g., bruteforce, connection).
timestamp String ISO 8601 DateTime When the event occurred. Cannot be a future timestamp.
sensor_id Integer Min value: 0 The ID of the sensor. Must be provisioned beforehand.

Optional fields, per event:

Parameter Type Default Constraints / Description
session_id String "" Max length: 100. Unique honeypot session token.
token_id String "" Max length: 100. Identifier for unique authentication tokens.
protocol String "" Max length: 50. Network layer protocol (e.g., tcp, udp).
service_name String "" Max length: 100. Application service target (e.g., ssh, cowrie).
username String "" Max length: 255. Username used during authentication attempts.
password String "" Max length: 255. Password used during authentication attempts.
cve_id String "" Max length: 50. Target vulnerability exploit tracker.
command String "" Free-text. The raw command or shell payload executed.
src_port Integer null Range: 1 to 65535. Source port of the connection.
dest_port Integer null Range: 1 to 65535. Destination port of the connection.
related_url String "" Max length: 900. Valid URL downloaded/hit during attack.
payload_hash String "" Max length: 64. Hash string (SHA-256) of dropped malware.
data Object {} Arbitrary nested JSON object for schema-less storage.

Responses

  • Response (202): Accepted - returned when the payload passes structural validation, raw entries are staged, and the extraction queue successfully registers the job.
  • Response (400): Bad Request - returned if structural payload validation fails, required event fields are missing, timestamps are in the future, or no valid events could be saved.
  • Response (403): Forbidden - returned if the user is unauthenticated, lacks an administrative APISource link, or if their APISource record has been locked due to excessive payload malformations.
  • Response (500): Internal Server Error - returned if unforeseen infrastructure anomalies interrupt staging database I/O operations or background task enqueuing.

Event Status API

This endpoint allows clients to view the processing state of an ingested event batch using its unique task_id.

Endpoint URL

GET https://<greedybear_site>/api/events/status/<task_id>/

Parameters

  • task_id (String): The unique string identifier (UUID format) received in the 202 Accepted response from the Event Creation API.

Responses

  • Response (200): OK - returned when the tracking record exists for the authenticated user's account. Possible values for the status string property include pending, processing, completed, and failed.
  • Response (403): Forbidden - returned if the user is unauthenticated or the underlying APISource identity record is deactivated.
  • Response (404): Not Found - returned if the provided task_id does not match any asynchronous ingest lifecycle record tied to your specific APISource.

Health API

Available from version >= 3.2.0

GreedyBear exposes a public, unauthenticated endpoint that can be used for liveness checks, external monitoring, and a quick at-a-glance view of the instance's data.

Example

Request:

GET /api/health

Response:

{
  "system": {
    "uptime_seconds": 29732,
    "database": "up",
    "qcluster": "up",
    "elasticsearch": "up"
  },
  "overview": {
    "iocs": {"total": 10486, "new_last_24h": 59},
    "sessions": {"total": 626615, "last_24h": 1388},
    "honeypots": {"total": 9, "active": 3},
    "threat_lists": {"firehol": 26849, "mass_scanners": 16857, "tor_exit_nodes": 1869},
    "jobs": {"scheduled": 15, "failed_last_24h": 0, "successful_last_24h": 219}
  }
}

User management

Registration

WARNING This functionality has been removed from the v.1.5.0 onwards because it was not used. In case you need it, please ask it and we re-add it to the project.

Since Greedybear v1.1.0 we added a Registration Page that can be used to manage Registration requests when providing GreedyBear as a Service.

After an user registration, an email is sent to the user to verify their email address. If necessary, there are buttons on the login page to resend the verification email and to reset the password.

Once the user has verified their email, they would be manually vetted before being allowed to use the GreedyBear platform. The registration requests would be handled in the Django Admin page by admins. If you have GreedyBear deployed on an AWS instance you can use the SES service.

In a development environment the emails that would be sent are written to the standard output.

Amazon SES

If you like, you could use Amazon SES for sending automated emails.

First, you need to configure the environment variable AWS_SES to True to enable it. Then you have to add some credentials for AWS: if you have GreedyBear deployed on the AWS infrastructure, you can use IAM credentials: to allow that just set AWS_IAM_ACCESS to True. If that is not the case, you have to set both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Additionally, if you are not using the default AWS region of us-east-1, you need to specify your AWS_REGION. You can customize the AWS Region location of you services by changing the environment variable AWS_REGION. Default is eu-central-1.

This is the GreedyBear Wiki. Wiki Home

Clone this wiki locally