Last Updated: 2021-03-11
NOTE: The call-api utility has been updated to support the binary download

Modules

These modules are here to allow trusted partners to query information about malware, networks, and trusted programs.

• research/malware-info – obtain static details about the requested sample
• research/malware-download – download a malware sample
• research/asn – obtain details about an ASN
• research/trusted-program – obtain details about a trusted program

Methods

research/malware-info

Returns a JSON response containing static details about the requested sample as well as antivirus vendor and signature details.

Fields:

apikey : string : your api key
sample : string : MD5, SHA1, SHA256, and SHA512 hash

Response:

JSON object

Sample query:

freed0@pit:~$ ./call-api.py research/malware-info '{"sample":"dfe1832e02888422f48d6896dc8e8f73"}' pretty

Up to 1,000 samples can be queried in a single call:

freed0@pit:~$ ./call-api.py research/malware-info '{"sample":["dfe1832e02888422f48d6896dc8e8f73","d41d8cd98f00b204e9800998ecf8427e"]}' pretty

Example:

freed0@pit:~$ ./call-api.py research/malware-info '{"sample":"dfe1832e02888422f48d6896dc8e8f73"}' pretty
[
    {
        "sha1": "c56ba498d41caa7be3c1eb5588cec27c413eb208",
        "last_seen": "2016-08-25 02:44:39",
        "tlsh": "c1b52a5273fa0254f2f35f75a8b7a3944939fea11d22e08e1164314d88b6f808e75bb7",
        "sha256": "d8d395f8744335fba53b0a4308e7b380a0aca86bfc8939ded9f4c8c5cb1e838a",
        "md5": "dfe1832e02888422f48d6896dc8e8f73",
        "filesize": "2438340",
        "magic": "PE32 executable (GUI) Intel 80386, for MS Windows",
        "first_seen": "2016-08-25 02:44:39",
        "sha512": "7ca1fdfe537913b8854227efc1f11b00d405f2d21e416e7023c4ebed2bfa887d2bc4d4d553ce41667c99def47ea05e6ce4a773c4ee7173927f1d263e724c16c2",
        "timestamp": "2016-08-25 02:44:39",
        "anti_virus": [
            {
                "md5": "dfe1832e02888422f48d6896dc8e8f73",
                "signature": "W32/Lamer.CQ",
                "vendor": "Fortinet",
                "timestamp": "2017-04-11 03:14:49Z"
            },
            {
                "vendor": "Avast",
                "signature": "Win32:Lamer-A",
                "timestamp": "2018-07-05 00:01:07Z",
                "md5": "dfe1832e02888422f48d6896dc8e8f73"
            },
            {
                "md5": "dfe1832e02888422f48d6896dc8e8f73",
                "timestamp": "2018-10-17 20:33:19Z",
                "signature": "Win32/Zatoxp.C",
                "vendor": "Eset"
            },
            {
                "timestamp": "2016-08-25 07:45:52Z",
                "signature": "Virus ( 004d554e1 )",
                "vendor": "K7",
                "md5": "dfe1832e02888422f48d6896dc8e8f73"
            },
            {
                "md5": "dfe1832e02888422f48d6896dc8e8f73",
                "signature": "PUA.Win.Packer.Purebasic-2",
                "vendor": "Clam",
                "timestamp": "2017-01-14 06:23:13Z"
            },
            }
        ],
        "adobe_malware_classifier": "malicious",
        "type": "exe",
        "import_hash": "33f98db5bdb6a7013d52f0120248df35",
        "entropic": "5.952427",
        "pehash": "243c35935ecc9829f30b30c45839cbf6"
    }
]

research/malware-download

Downloads the requested binary

Fields:

apikey : string : your api key
sample : string : hash

Response:

binary file contents

Example:

freed0@pit:~$ ./call-api.py research/malware-download '{"sample":"dfe1832e02888422f48d6896dc8e8f73"}' binary > /tmp/dfe1832e02888422f48d6896dc8e8f73

freed0@pit:~$ ls -la /tmp/dfe1832e02888422f48d6896dc8e8f73
-rw-rw-r-- 1 freed0 freed0 2438340 Mar 12 00:24 /tmp/dfe1832e02888422f48d6896dc8e8f73

research/asn

Query different aspects of ASN information.

Fields:

apikey : string : your api key
one of the following:
  -  query  : integer : ASN 
  -  peer   : ip      : IP address
  -  origin : integer : ASN
  -  prefix : integer : ASN

Response:

JSON object

ASN Query

Report back any information about the ASN

Example:

freed0@pit:~$ ./call-api.py research/asn '{"query":109}' pretty
{
    "nic": "arin",
    "asn": "109",
    "date": "19870506",
    "asname_long": "CISCOSYSTEMS",
    "geo": "US",
    "asname_short": "CISCOSYSTEMS"
}

Peer Query

Report back all the BGP peers for a specific CIDR

Example:

freed0@pit:~$ ./call-api.py research/asn '{ "peer": "8.8.8.8" }' pretty
[
    {
        "geo": "US",
        "asn": "15169",
        "prefix": "8.8.8.0/24",
        "asname_long": "GOOGLE",
        "asname_short": "GOOGLE",
        "peer": "1101 6696 47605 51088"
    }
]

Up to 1,000 items can be queried in one call:

freed0@pit:~$ ./call-api.py research/asn '{ "peer": [ "8.8.8.8", "8.8.4.4" ] }' pretty

Origin Query

Report back the originating ASN and ASN name for the specific CIDR.

Example:

freed0@pit:~$ ./call-api.py research/asn '{ "origin": "8.8.8.8" }' pretty
[
    {
        "geo": "US",
        "prefix": "8.8.8.0/24",
        "asn": "15169",
        "asname_long": "GOOGLE",
        "asname_short": "GOOGLE"
    }
]

Up to 1,000 items can be queried in one call:

freed0@pit:~$ ./call-api.py research/asn '{ "origin": [ "8.8.8.8", "8.8.4.4" ] }' pretty

Prefix Query

Given an ASN report back all the routed CIDR’s.

Example:

freed0@pit:~$ ./call-api.py research/asn '{ "prefix": 22414 }' pretty
[
    "208.82.236.0/22"
]

research/trusted-program

Returns a JSON response containing the details for the requested program.

Fields:

apikey : string : your api key
sample : string : hash

Help:

freed0@pit:~$ ./call-api.py research/trusted-program '{"help":true}' pretty
[
    "application_type",
    "binary",
    "bit",
    "crc32",
    "description",
    "dirname",
    "filename",
    "filesize",
    "filetimestamp",
    "fileversion",
    "language",
    "language_code",
    "md5",
    "media_source",
    "mfg_name",
    "os_mfg",
    "os_name",
    "os_version",
    "product_name",
    "product_version",
    "reference",
    "scan_time",
    "sha1",
    "sha256",
    "sha512",
    "sig_timestamp",
    "sig_trustfile",
    "signer",
    "source",
    "source_version",
    "ssdeep",
    "strongname_signed",
    "trusted_signature"
]

Response:

JSON object

Example:

freed0@pit:~$ ./call-api.py research/trusted-program '{ "sample": "7fe2248de77813ce850053ed0ce8a474" }' pretty
{
    "filetimestamp": "07/14/2009 01:14:16",
    "reference": "os_patches_wsus",
    "sha256": "289691E10A1564DD515CD128A9BCFD3AEF32E6BF4E5A1E3B1673026E1346283B",
    "bit": "32",
    "signer": "Microsoft Windows",
    "crc32": "23897C4C",
    "sha1": "E6927051249E27AD5D1F5F2F52B1CAF8A1605AE2",
    "binary": "1",
    "language": "Portuguese",
    "source_version": "1.8",
    "fileversion": "6.1.7600.16385",
    "source": "AppInfo",
    "os_version": "6.1",
    "product_version": "6.1.7600.16385",
    "trusted_signature": "1",
    "product_name": "Microsoft Windows Operating System",
    "os_name": "Microsoft Windows Server 2008 R2 Standard Service Pack 1 (build 7601), 64-bit",
    "language_code": "1046",
    "md5": "7FE2248DE77813CE850053ED0CE8A474",
    "scan_time": "2020-06-18 22:56:14",
    "filename": "ddodiag.exe",
    "dirname": "c:\\Windows\\winsxs\\x86_microsoft-windows-ddodiag_31bf3856ad364e35_6.1.7600.16385_none_362ce835fe42421b",
    "strongname_signed": "0",
    "filesize": "36864",
    "description": "DDODiag is a tool that collects Device Display Object (DDO) information from the system and logs it",
    "os_mfg": "Microsoft Corporation",
    "media_source": "http://www.microsoft.com/",
    "application_type": "exe",
    "sha512": "F61BEA0DC281B56B563ED32331938EFC9BF6D7A3C9CAB3273103D2FD95A73C2492E31F2C64119651E5ABFE8F3A881317C3D3B81BAA2229B3CF01E4991EBFE8FC",
    "ssdeep": "768:09iqlZu4aMwcWrkZKXshfN469R9B3DpWNsZSs:09iqlZu4aMwcWrkZKXshfNT9RZBSs",
    "sig_timestamp": "07/14/2009 03:17:39",
    "mfg_name": "Microsoft Corporation",
    "sig_trustfile": "C:\\Windows\\system32\\CatRoot\\{F750E6C3-38EE-11D1-85E5-00C04FC295EE}\\ntexe.cat"
}

CHANGELOG

• 2021-03-11 – New API to allow access to download malware as well as access data related to networks and trusted programs data.