Logo

Docs

URLs

Malicious URL Data API Usage Guide

The proposed API service serves as a pivotal tool in combatting online threats by allowing users and applications to report and retrieve URLs associated with malicious activities, including phishing and malware distribution. This service empowers users to contribute to a collective defense against cyber threats by submitting suspicious URLs with corresponding details. By centralizing and categorizing this information, the service provides valuable insights into emerging threats and patterns, enabling users to proactively protect themselves and their systems. Through the API’s retrieval capabilities, users can access up-to-date information about malicious URLs, enhancing their ability to identify and avoid potential risks. Ultimately, this API service plays a critical role in fostering a safer online environment by fostering collaboration, awareness, and preventive action against malicious intent.

GET - Check single URL

  • Retrieve metadata for over a million known malicious url.
  • 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/urls/:url HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
url URL to Scan (String) URL you wishing to gain information (must be valid format and URL Encoded)
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:

        {
            "url": "http://www.almaservice.it",
            "score": 54,
            "ts": 1695896501,
            "total_reports": 1,
            "total_members": 1,
            "tags": [
                "MARAVENTO",
                "OneFirewall"
            ],
            "elk_ts": "2023-09-28T10:21:41.000Z",
            "elk_entry_ts": "2023-09-28T10:21:41.000Z",
            "entry_ts": 1695896501
        }

GET - List of malicious URLs

Retrieve a list of malicious urls

HTTP Request

GET /api/v1/urls/score/:min_score?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 urls separated by ‘,’
page String A cursor that indicates the next page ID to access the next batch of data

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)
URL1
URL2
...
LIST (in case format=LIST)
URL1,URL2,...

GET - Get latest URLs

Retrieve the latest malicious url recorded

HTTP Request

GET /api/v1/urls?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": "URL",
        "version": 4,
        "ts": 1693519200,
        "next_ts": 1695919395,
        "page_size": 100,
        "user": {
            "guid": "OFA-GUID-3256-FDGS-OODP",
            "name": "Name",
            "surname": "Surname",
            "username": "[email protected]",
            "role": 0,
            "unsuccessful_login": 0,
            "member_of": {
                "gid": "OFA-GID-jkbjhvhjg",
                "name": "Org1",
                "trust": 0.85,
                "delay": "0",
                "credit_tokens": 2000000000,
                "debit_tokens": 1888963
            }
        }
    },
    "body": [
        {
            "url": "http://www.almaservice.it",
            "score": 54,
            "ts": 1695896501,
            "total_reports": 1,
            "total_members": 1,
            "tags": [
                "MARAVENTO",
                "OneFirewall"
            ],
            "elk_ts": "2023-09-28T10:21:41.000Z",
            "elk_entry_ts": "2023-09-28T10:21:41.000Z",
            "entry_ts": 1695896501
        },
        {
            "url": "http://www.gothamserver.net",
            "score": 54,
            "ts": 1695898867,
            "total_reports": 1,
            "total_members": 1,
            "tags": [
                "MARAVENTO",
                "OneFirewall"
            ],
            "elk_ts": "2023-09-28T11:01:07.000Z",
            "elk_entry_ts": "2023-09-28T11:01:07.000Z",
            "entry_ts": 1695898867
        }
    ]
}

POST - Reporting API

  • Enable users to report url 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/urls HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
{
    "confidence": 1,
    "tags": ["benign"],
    "url": "http://extratorrent.cc/torrent/4190340/Maya.the.Bee.Movie.2014.BRRip.XviD.AC3-EVO.html"
}
Variable Possible Values Notes
url Full URL (String) Valid url string
tags Tags/Labels (Array of Strings) Any string (in array format) to reference the malicious activities of the url
confidence 0.0 to 1.0 (Float) Confidence level on the malicious capabilites of the url
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/urls/<url> 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