Logo

Docs

Domains

Malicious Domains Data API Usage Guide

The API service acts as a centralized hub, gathering and curating data from various sources, including security researchers, threat intelligence feeds, and community contributions in relation to any qualified domain name (FQDN) marked as serving malicious content.

GET - Check single Domain name

  • Retrieve metadata for over a million known malicious domains.
  • Gain knowledge about specific threat actors.
  • Integrate automated prevention measures into your security systems.
  • Stay up to date with real-time updates on threats.

HTTP Request

GET /api/v1/domains/:domain_name?deep_scan=NO HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
domain_name Domain to Scan (String) Domain name you wishing to gain information (must be valid format)
deep_scan YES or NO (String) A Deep Scan is perfromed accross 4 million IoCs if the Digest is not presented into the main OneFirewall Data Lake
Output

The possible HTTP Code responses are:

  • 200 OK: The request was received and processed successfully
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 402 Payment Required: Not enogh OneFirewall Coins to perform the request
  • 404 Not Found: The requested digest was not found
  • 403 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable

In case of an 200 response the body will be presented as the below example:

        {
            "domain": "ukfoyr.com",
            "score": 88,
            "ts": 1693526732,
            "total_reports": 1,
            "total_members": 1,
            "tags": [
                "CTA",
                "OneFirewall"
            ],
            "elk_ts": "2023-09-01T00:05:32.000Z",
            "elk_entry_ts": "2023-09-01T00:05:32.000Z",
            "entry_ts": 1693526732
        }

GET - List of malicious Domains

Retrieve a list of malicious domains

HTTP Request

GET /api/v1/domains/score/:min_score?protocol=HTTPS&format=CSV&page=BASE64String HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
min_score 1 to 1000 (Integer) Minimum WCF Crime Score Feeds
format CSV or LIST (String) CSV=the output is CSV, LIST=the output is a list of domains separated by ‘,’
page String A cursor that indicates the next page ID to access the next batch of data
protocol HTTP or HTTPS return the domains with HTTP or HTTPS protocol prefix

If the response header contains a variable with name next_page, use the value with the new request on the API in order to retreive the next batch of data for the same Score. If the header is not presented, means there no more data to return.

Output

The possible HTTP Code responses are:

  • 200 OK: The request was received and processed successfully
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 402 Payment Required: Not enogh OneFirewall Coins to perform the request
  • 404 Not Found: The requested digest was not found
  • 403 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable

In case of an 200 response the body will be presented as the below example:

CSV (in case format=CSV or not presented in the request)
domain1.xyz
domain2.xyz
...
LIST (in case format=LIST)
domain1.xyz,domain2.xyz,...

GET - Get latest domains

Retrieve the latest malicious domains recorded

HTTP Request

GET /api/v1/domains?ts=<timestamp>&page_size=<integer> HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
ts Timestamp (integer format) Latest updates starting from this timestamp
page_size 100-2000 (integer) Maximum elements to return
Output

The possible HTTP Code responses are:

  • 200 OK: The request was received and processed successfully
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 402 Payment Required: Not enogh OneFirewall Coins to perform the request
  • 404 Not Found: The requested digest was not found
  • 403 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable

The JSON in return is split into 2 objects:

  • header: Accountable to provide metadata of the request, the user who made the request and the organization where the users belong
  • header.ts: The start of the timestamp requested
  • header.next_ts: The timestamp for the next page (use this value to make a new request to the API)
  • header.page_size: The total amount of feeds in the body array. If the value is 0 means no new data are presented, you can consider this as of the final page (or you can loop until new data are provided). The page size could bigger or smaller than the requested page_size
  • header.user: Information about the user making the request
  • body: Provide the data requested, in this case is an array of IoC feeds
HTTP Response in case of a HTTP 200
{
    "header": {
        "type": "Domain",
        "version": 4,
        "ts": 1693519200,
        "next_ts": 1693526758,
        "page_size": 100,
        "user": {
            "guid": "OFA-GUID-DSDG-FDFG-XJDO",
            "name": "Name",
            "surname": "Surname",
            "username": "[email protected]",
            "role": 0,
            "unsuccessful_login": 0,
            "member_of": {
                "gid": "OFA-GID-sdgdfgdfd",
                "name": "Org1",
                "trust": 0.85,
                "delay": "0",
                "credit_tokens": 2000000000,
                "debit_tokens": 1888975
            }
        }
    },
    "body": [
        {
            "domain": "ukfoyr.com",
            "score": 88,
            "ts": 1693526732,
            "total_reports": 1,
            "total_members": 1,
            "tags": [
                "CTA",
                "OneFirewall"
            ],
            "elk_ts": "2023-09-01T00:05:32.000Z",
            "elk_entry_ts": "2023-09-01T00:05:32.000Z",
            "entry_ts": 1693526732
        },
        {
            "domain": "vewuio.com",
            "score": 88,
            "ts": 1693526732,
            "total_reports": 1,
            "total_members": 1,
            "tags": [
                "CTA",
                "OneFirewall"
            ],
            "elk_ts": "2023-09-01T00:05:32.000Z",
            "elk_entry_ts": "2023-09-01T00:05:32.000Z",
            "entry_ts": 1693526732
        }
    ]
}

POST - Reporting API

  • Enable users to report domains suspected of serving malware, viruses, or trojans.
  • Streamlined reporting process for easy submission and analysis.
  • Enhance collective defense by contributing to threat identification and analysis.
  • Ensure user confidentiality and privacy.
  • Support crowdsourced threat intelligence and incident response efforts.

HTTP Request

POST /api/v1/domains HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
{
    "confidence": 0.4,
    "tags": ["OneFirewall"],
    "domain": "hacks4me.com"
}
Variable Possible Values Notes
domain Domain Name (String) Valid domain name
tags Tags/Labels (Array of Strings) Any string (in array format) to reference the malicious activities of the domain
confidence 0.0 to 1.0 (Float) Confidence level on the malicious capabilites of the domain
Output

The possible HTTP Code responses are:

  • 200 OK: The request was received and processed successfully, no body content
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 403 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable

PUT - Overwrite Decision

This API is used to change / overwrite the decision based on score, in other words setting manually a IoC in whitelist or blacklist.

HTTP Request

POST /api/v1/domains/<domain> HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
{
    "decision": <integer>
}
Variable Possible Values Notes
decision 1,0,-1 0 for whitelist, 1 for blacklist, -1 (default) for based on score (not overwrite)
Output

The possible HTTP Code responses are:

  • 200 OK: The request was received and processed successfully, no body content
  • 400 Bad Request: The request was malformed (body contains further explanations)
  • 403 Unauthorized: The request not authorized (body contains further explanations)
  • 5XX Internal Server Error: The service is momentarily unavailable