Api Documentation

On this page, we detail our API interface for Malpedia as well as recommended ways to interact with it.

Authentication

You have two ways to authenticate towards Malpedia when using the API:

One account may have up to 10 APITokens at a time to accomodate different use cases. Please make sure to note down or store your token directly after generation as it will not be retrievable later on.

In order to use the token, just add it to the Authorization field in your HTTP header, like so (e.g. when using curl):
curl -H 'Authorization: apitoken <TOKEN>' https://malpedia.caad.fkie.fraunhofer.de/api/<API_CALL>

Malpedia Client

Pim Trouerbach wrote a very nice client for the Malpedia API in Go!
You can pull it from his Git repository: malpedia_cli.

Our own python package / client for Malpedia's REST API can be found here: malpediaclient.

API Documentation

GET /api/check/apikey

Access limitation: none

Check if the submitted API-Key is valid.

GET /api/find/actor/<needle>

<needle>Your search-string.
Access limitation: none

Provide a list of all actor names and associated synonyms where a part of the name is matched.
Output is potentially subject to change and may include the responsible "name-creator" (e.g. "fireeye": "APT 28", "crowdstrike": "Fancy Bear", ...) in the future.

GET /api/find/family/<needle>

<needle>Your search-string.
Access limitation: none

Provide a list of all family names and associated synonyms where a part of the name is matched.

GET /api/get/actor/<actor_id>

<actor_id>The ID of the actor you want to download the meta-data of.
Access limitation: none

Provide the meta information for a given <actor_id>.

GET /api/get/actors

Access limitation: none

Provide meta data for all actors on Malpedia.

GET /api/get/bib

Access limitation: none

Provide the .bib file containing all references of Malpedia.

GET /api/get/bib/actor/<actor_id>

Access limitation: none

Provide the .bib file containing all references for a certain actor

GET /api/get/bib/family/<family_id>

Access limitation: none

Provide the .bib file containing all references for a certain family

GET /api/get/families

Access limitation: none

Provide meta data for all families on Malpedia.

GET /api/get/family/<family_id>

<family_id>The ID of the family you want to get the meta-data of.
Access limitation: none

Provide meta data for a single family.

GET /api/get/misp

Access limitation: none

A current view of Malpedia in the MISP galaxy cluster format.

GET /api/get/references

Access limitation: none

Obtain all references including their corresponding families and actors on Malpedia.

GET /api/get/sample/<md5>/info

<md5>Hash of the sample you want to check.
Access limitation: registration

Provide info about presence and status of the sample without its contents

GET /api/get/sample/<md5>/raw

<md5>Hash of the sample you want to obtain.
Access limitation: registration

Provide the sample alongside potentially existing unpacked or dumped files.

GET /api/get/sample/<md5>/zip

<md5>Hash of the sample you want to obtain.
Access limitation: registration

Provide the sample alongside potentially existing unpacked or dumped files.

GET /api/get/sample/<sha256>/info

<sha256>Hash of the sample you want to check.
Access limitation: registration

Provide info about presence and status of the sample without its contents

GET /api/get/sample/<sha256>/raw

<sha256>Hash of the sample you want to obtain.
Access limitation: registration

Provide the sample alongside potentially existing unpacked or dumped files.

GET /api/get/sample/<sha256>/zip

<sha256>Hash of the sample you want to obtain.
Access limitation: registration

Provide the sample alongside potentially existing unpacked or dumped files.

GET /api/get/version

Access limitation: none

Obtain the current version of Malpedia (commit number and date).

GET /api/get/yara/<family_id>

<family_id>The ID of the family you want to get the yara-rules of.
Access limitation: none (but result may vary for registered users)

Provide the YARA rules for a given <family_id>.
Output may vary depending on access level (public = white, registration = green, amber).

GET /api/get/yara/<family_id>/zip

<family_id>The ID of the family you want to get the yara-rules of.
Access limitation: none (but result may vary for registered users)

Provide the YARA rules for a given <family_id> in a zip archive.
Output may vary depending on access level (public = white, registration = green, amber).

GET /api/get/yara/<tlp>/raw

<tlp>{tlp_white, tlp_green, tlp_amber}
Access limitation: none (but result may vary for registered users)

Provide all YARA rules with given TLP.
Output may vary depending on access level (public = white, registration = green, amber).

GET /api/get/yara/<tlp>/zip

<tlp>{tlp_white, tlp_green, tlp_amber}
Access limitation: none (but result may vary for registered users)

Provide all YARA rules with given TLP in a zip archive.
Output may vary depending on access level (public = white, registration = green, amber).

GET /api/get/yara/after/<date>

<date>Date in the following format <yyyy-mm-dd>.
Access limitation: none (but result may vary for registered users)

Provide all YARA rules with a version newer than a specific date. Intended for users intending regular automated updates.
Output may vary depending on access level (public = white, registration = green, amber).

GET /api/get/yara/auto/raw

Access limitation: none

Provide all automatically generated, code-based rules created using YARA-Signator.

GET /api/get/yara/auto/zip

Access limitation: none

Provide all automatically generated, code-based rules created using YARA-Signator in a zip archive.

GET /api/list/actors

Access limitation: none

List all actor IDs. This is a helper command to enable follow commands involving actor data.

GET /api/list/apiscout

Access limitation: registration

Provide a list of all non-zero ApiVector fingerprints that are currently on Malpedia.

GET /api/list/apiscout/csv

Access limitation: registration

Provide a list of all non-zero ApiVector fingerprints that are currently on Malpedia (in CSV format compatible with ApiScout).

GET /api/list/families

Access limitation: none

List all family IDs. This is a helper command to enable follow up commands family data.

GET /api/list/samples

Access limitation: registration

Provide a list of all samples on Malpedia for all families, including their packed status and version, if available.

GET /api/list/samples/<family_id>

<family_id>The ID of the family you would like to list the samples of.
Access limitation: registration

Provide a list of all samples known for a family, including their packed status and version, if available.

GET /api/list/yara

Access limitation: none (but result may vary for registered users)

Provide a list of all YARA rules in malpedia for all families.
Output may vary depending on access level (public = white, registration = green, amber).

POST /api/scan/apiscout

<POST_Data>compressed ApiVector as generated by ApiScout
Access limitation: none (but result may vary for registered users)

Scan a given ApiVector against Malpedia's Database of ApiVector Fingerprints.

POST /api/scan/yara/<family_id>

<POST_Data>YARA rule in text format.
<family_id>The ID of the family you want the samples to be limited to.
Access limitation: registration

Have a YARA rule used to scan against all samples (packed, unpacked, dumped) of a given family currently contained in Malpedia.
The format of <yara_scan_report> is TBD.