Logo

Docs

Files

Malicious File Data API Usage Guide

OneFirewall Alliance provides a robust File Indicator of Compromise (IoC) framework to enhance cybersecurity practices and bolster threat detection capabilities. With their extensive threat intelligence and Data Lake of malicious files, OneFirewall offers a comprehensive set of file IoCs that enable proactive identification and prevention of known threats.

The File IoC framework from OneFirewall encompasses a range of metadata indicators associated with malicious files. These indicators typically include MD5, SHA1, and SHA256 hashes, which serve as unique identifiers for each file. By leveraging these indicators, security teams and systems can swiftly identify and classify files that match known malicious signatures.

OneFirewall’s File IoCs are continuously updated and enriched with the latest threat intelligence, ensuring that security measures remain effective against emerging threats. This real-time information allows organizations to stay ahead of attackers and quickly adapt their defenses to counter new and evolving threats

GET - File types (mimetypes)

OneFirewall retetrive each file flagged as malware and associates it with a specific file type (when possible), or more precisely, a MIME type. Currently, OneFirewall only accepts file types from a predetermined list provided by this API.

HTTP Request

GET /api/v1/file_types HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
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:

[
        {
        "name": "application/x-krita",
        "description": "KRA is the file format for Krita, a raster graphics editor. It is a ZIP archive containing a number of files, including the image data, the layer structure, and the document settings.<br /><br />It is similar in function to PSD files for photoshop.<br /><br />A .krz file is a compressed version of a .kra file and only missing the mergedimage.png contained within it to save storage. The lack of this file can affect interchange with other applications such as Scribus.",
        "types": [
            ".kra",
            ".krz"
        ],
        "alternatives": [],
        "furtherReading": [
            {
                "title": "Krita File Format",
                "url": "https://docs.krita.org/en/general_concepts/file_formats/file_kra.html"
            }
        ]
    }
    ...
]

GET - Check malicious files by any digest type

  • Retrieve metadata for over a million known malicious files.
  • Access indicators such as MD5, SHA1, and SHA256 for easy identification.
  • 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/files/:digest?deep_scan=NO HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
Variable Possible Values Notes
digest MD5,SHA1,SHA256 (String) Digest value in any format from MD5,SHA1,SHA256
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:

        {
            "md5": "947F536E12836C13CFC73638B796471D",
            "sha1": "F478B6E4653C4620AF43841CC1F0227BC79F3ADB",
            "sha256": "1AE54CBDE48D74B3312771FCDB51E672CD0D60F737FA5FE09F9C83597B8A3B5F",
            "score": 96,
            "ts": 1693519331,
            "file_bytes": null,
            "total_reports": 47,
            "total_members": 1,
            "file_type": "application/x-executable",
            "file_name": "947f536e12836c13cfc73638b796471d",
            "tags": [
                "n/a",
                "elf",
                "Gafgyt"
            ],
            "elk_ts": "2023-08-31T22:02:11.000Z",
            "elk_entry_ts": "2023-08-30T00:03:23.000Z",
            "entry_ts": 1693353803
        }

GET - List of malwares

Retrieve a list of malicious files by digest type

HTTP Request

GET /api/v1/files/score/:min_score?format=CSV&digest=SHA256&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 digest separated by ‘,’
page String A cursor that indicates the next page ID to access the next batch of data
digest SHA256,SHA1 or MD5 (String) Digest algorithm representations 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)
E285554419641DFF5D76400773422172E364B53AE22C412D92EAA98A28CAE5F0
A73E7A36715AD8A067EDD3B455ADA4AE88D5F973FB627F996FF6FD0BEC820B6E
...
LIST (in case format=LIST)
A73E7A36715AD8A067EDD3B455ADA4AE88D5F973FB627F996FF6FD0BEC820B6E,E285554419641DFF5D76400773422172E364B53AE22C412D92EAA98A28CAE5F0,...

GET - Get latest malwares

Retrieve the latest malicious files recorded

HTTP Request

GET /api/v1/files?ts=<timestamp>&page_size=<int>&min_score=<int>&file_type=<string>&file_name=<string>&tags=<string>,<string> 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 (defult 30min ago)
page_size 100-2000 (integer) Maximum size to return (default 100)
min_score 0-1000 (integer) Filter based on minimum score (default 0)
file_type (string) Filter based on file type (default none)
file_name (string) Filter based on file name (default none)
tags (array of strings) Array of strings separated by ‘,’ to return documents that contain at least one of the tags provided (default none)
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": "Malware",
        "version": 4,
        "ts": 1693519200,
        "next_ts": 1693519490,
        "page_size": 100,
        "user": {
            "guid": "OFA-GUID-YORP-4193-FDFM",
            "name": "NAME",
            "surname": "Surname",
            "username": "[email protected]",
            "role": 0,
            "unsuccessful_login": 0,
            "member_of": {
                "gid": "OFA-GID-dsfgdsfgfdj",
                "name": "Org1",
                "trust": 0.85,
                "delay": "0",
                "credit_tokens": 2000000000,
                "debit_tokens": 1888915
            }
        }
    },
    "body": [
        {
            "md5": "B3A5311FB0E11953EBD765D4231776EE",
            "sha1": "EE727E0FFE780EC24609B9FCCA8512ADE671E2D5",
            "sha256": "15678297D3D6DA1D77C9B5C7B479F5C3C922D739C42CA00641F3D3587A829970",
            "score": 96,
            "ts": 1693519331,
            "file_bytes": null,
            "total_reports": 47,
            "total_members": 1,
            "file_type": "application/x-executable",
            "file_name": "b3a5311fb0e11953ebd765d4231776ee",
            "tags": [
                "n/a",
                "elf"
            ],
            "elk_ts": "2023-08-31T22:02:11.000Z",
            "elk_entry_ts": "2023-08-30T00:03:23.000Z",
            "entry_ts": 1693353803
        },
        {
            "md5": "947F536E12836C13CFC73638B796471D",
            "sha1": "F478B6E4653C4620AF43841CC1F0227BC79F3ADB",
            "sha256": "1AE54CBDE48D74B3312771FCDB51E672CD0D60F737FA5FE09F9C83597B8A3B5F",
            "score": 96,
            "ts": 1693519331,
            "file_bytes": null,
            "total_reports": 47,
            "total_members": 1,
            "file_type": "application/x-executable",
            "file_name": "947f536e12836c13cfc73638b796471d",
            "tags": [
                "n/a",
                "elf",
                "Gafgyt"
            ],
            "elk_ts": "2023-08-31T22:02:11.000Z",
            "elk_entry_ts": "2023-08-30T00:03:23.000Z",
            "entry_ts": 1693353803
        },
        {
            "md5": "9D6980C593C635DE0E0A37224272924D",
            "sha1": "2EEA6F42D295AC7CEEB7FF079B99ADBB698C321F",
            "sha256": "DE895366E2FB48A164C45082928A4AF3D08969A5218F8B9581455635F7922876",
            "score": 96,
            "ts": 1693519331,
            "file_bytes": null,
            "total_reports": 47,
            "total_members": 1,
            "file_type": "application/x-executable",
            "file_name": "9d6980c593c635de0e0a37224272924d",
            "tags": [
                "n/a",
                "elf"
            ],
            "elk_ts": "2023-08-31T22:02:11.000Z",
            "elk_entry_ts": "2023-08-30T00:03:23.000Z",
            "entry_ts": 1693353803
        }
    ]
}

POST - Reporting API

  • Enable users to report files suspected of containing 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/files HTTP/1.1
Host: app.onefirewall.com
Authorization: Bearer PLACE_YOUR_OWN_TOKEN_HERE
Input
{
    "confidence": 1.0,
    "tags": ["Trojan", "SourcA"],
    "file_bytes": 4343232,
    "file_type": "application/x-executable",
    "file_name": "fun_videos",
    "md5": "b686a851d16fd6fcc716bdad3be7da93",
    "sha1": "9c452bd67089262ea08ec736a8794027b65a48f8",
    "sha256": "9be0305894d045617acaef9f66877acd738b31214a5c50296a7c4b5b1267854b"
}
Variable Possible Values Notes
md5 MD5 (String) Digest value in MD5 format (32 Chars) one digest is mandatory
sha1 SHA1 (String) Digest value in MD5 format (40 Chars) one digest is mandatory
sha256 SHA256 (String) Digest value in MD5 format (64 Chars) one digest is mandatory
file_type File Type (String) Not mandatory, specify the type of file, in respect of allowd list from this API /api/v1/file_types
file_name File Name (String) Not mandatory, specify the name of the file
file_bytes Number of Bytes for the file (Integer) The file size
tags Tags/Labels (Array of Strings) Any string (in array format) to reference the malware
confidence 0.0 to 1.0 (Float) Confidence level on the malware capabilites of the file
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/files/<digest> 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