From 13d683f7c683c96f2119422714ad65c0ddf878e9 Mon Sep 17 00:00:00 2001 From: chrisr3d Date: Tue, 23 Jul 2019 09:31:06 +0200 Subject: [PATCH] add: [documentation] Updated README and documentation with the virustotal modules changes --- README.md | 3 ++- doc/README.md | 38 +++++++++++++++++++++++----- doc/expansion/virustotal.json | 10 ++++---- doc/expansion/virustotal_public.json | 9 +++++++ 4 files changed, 47 insertions(+), 13 deletions(-) create mode 100644 doc/expansion/virustotal_public.json diff --git a/README.md b/README.md index c9fd915..bd998a8 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,8 @@ For more information: [Extending MISP with Python modules](https://www.circl.lu/ * [threatminer](misp_modules/modules/expansion/threatminer.py) - an expansion module to expand from [ThreatMiner](https://www.threatminer.org/). * [urlhaus](misp_modules/modules/expansion/urlhaus.py) - Query urlhaus to get additional data about a domain, hash, hostname, ip or url. * [urlscan](misp_modules/modules/expansion/urlscan.py) - an expansion module to query [urlscan.io](https://urlscan.io). -* [virustotal](misp_modules/modules/expansion/virustotal.py) - an expansion module to pull known resolutions and malware samples related with an IP/Domain from virusTotal (this modules require a VirusTotal private API key) +* [virustotal](misp_modules/modules/expansion/virustotal.py) - an expansion module to query the [VirusTotal](https://www.virustotal.com/gui/home) API with a high request rate limit required. (More details about the API: [here](https://developers.virustotal.com/reference)) +* [virustotal_public](misp_modules/modules/expansion/virustotal_public.py) - an expansion module to query the [VirusTotal](https://www.virustotal.com/gui/home) API with a public key and a low request rate limit. (More details about the API: [here](https://developers.virustotal.com/reference)) * [VMray](misp_modules/modules/expansion/vmray_submit.py) - a module to submit a sample to VMray. * [VulnDB](misp_modules/modules/expansion/vulndb.py) - a module to query [VulnDB](https://www.riskbasedsecurity.com/). * [Vulners](misp_modules/modules/expansion/vulners.py) - an expansion module to expand information about CVEs using Vulners API. diff --git a/doc/README.md b/doc/README.md index fd5b73b..d5d2ed0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1042,21 +1042,45 @@ An expansion module to query urlscan.io. -Module to get information from virustotal. +Module to get advanced information from virustotal. - **features**: ->This module takes a MISP attribute as input and queries the VirusTotal API with it, in order to get additional data on the input attribute. +>New format of modules able to return attributes and objects. > ->Multiple recursive requests on the API can then be processed on some attributes found in the first request. A limit can be set to restrict the number of values to query again, and at the same time the number of request submitted to the API. +>A module to take a MISP attribute as input and query the VirusTotal API to get additional data about it. > ->This limit is important because the default user VirusTotal apikey only allows to process a certain nunmber of queries per minute. As a consequence it is recommended to have a larger number of requests or a private apikey. +>Compared to the [standard VirusTotal expansion module](https://github.com/MISP/misp-modules/blob/master/misp_modules/modules/expansion/virustotal.py), this module is made for advanced parsing of VirusTotal report, with a recursive analysis of the elements found after the first request. > ->Data is then mapped into MISP attributes. +>Thus, it requires a higher request rate limit to avoid the API to return a 204 error (Request rate limit exceeded), and the data parsed from the different requests are returned as MISP attributes and objects, with the corresponding relations between each one of them. - **input**: >A domain, hash (md5, sha1, sha256 or sha512), hostname or IP address attribute. - **output**: ->MISP attributes mapped from the rersult of the query on VirusTotal API. +>MISP attributes and objects resulting from the parsing of the VirusTotal report concerning the input attribute. - **references**: ->https://www.virustotal.com/ +>https://www.virustotal.com/, https://developers.virustotal.com/reference +- **requirements**: +>An access to the VirusTotal API (apikey), with a high request rate limit. + +----- + +#### [virustotal_public](https://github.com/MISP/misp-modules/tree/master/misp_modules/modules/expansion/virustotal_public.py) + + + +Module to get information from VirusTotal. +- **features**: +>New format of modules able to return attributes and objects. +> +>A module to take a MISP attribute as input and query the VirusTotal API to get additional data about it. +> +>Compared to the [more advanced VirusTotal expansion module](https://github.com/MISP/misp-modules/blob/master/misp_modules/modules/expansion/virustotal.py), this module is made for VirusTotal users who have a low request rate limit. +> +>Thus, it only queries the API once and returns the results that is parsed into MISP attributes and objects. +- **input**: +>A domain, hostname, ip, url or hash (md5, sha1, sha256 or sha512) attribute. +- **output**: +>MISP attributes and objects resulting from the parsing of the VirusTotal report concerning the input attribute. +- **references**: +>https://www.virustotal.com, https://developers.virustotal.com/reference - **requirements**: >An access to the VirusTotal API (apikey) diff --git a/doc/expansion/virustotal.json b/doc/expansion/virustotal.json index 9008003..060069e 100644 --- a/doc/expansion/virustotal.json +++ b/doc/expansion/virustotal.json @@ -1,9 +1,9 @@ { - "description": "Module to get information from virustotal.", + "description": "Module to get advanced information from virustotal.", "logo": "logos/virustotal.png", - "requirements": ["An access to the VirusTotal API (apikey)"], + "requirements": ["An access to the VirusTotal API (apikey), with a high request rate limit."], "input": "A domain, hash (md5, sha1, sha256 or sha512), hostname or IP address attribute.", - "output": "MISP attributes mapped from the rersult of the query on VirusTotal API.", - "references": ["https://www.virustotal.com/"], - "features": "This module takes a MISP attribute as input and queries the VirusTotal API with it, in order to get additional data on the input attribute.\n\nMultiple recursive requests on the API can then be processed on some attributes found in the first request. A limit can be set to restrict the number of values to query again, and at the same time the number of request submitted to the API.\n\nThis limit is important because the default user VirusTotal apikey only allows to process a certain nunmber of queries per minute. As a consequence it is recommended to have a larger number of requests or a private apikey.\n\nData is then mapped into MISP attributes." + "output": "MISP attributes and objects resulting from the parsing of the VirusTotal report concerning the input attribute.", + "references": ["https://www.virustotal.com/", "https://developers.virustotal.com/reference"], + "features": "New format of modules able to return attributes and objects.\n\nA module to take a MISP attribute as input and query the VirusTotal API to get additional data about it.\n\nCompared to the [standard VirusTotal expansion module](https://github.com/MISP/misp-modules/blob/master/misp_modules/modules/expansion/virustotal.py), this module is made for advanced parsing of VirusTotal report, with a recursive analysis of the elements found after the first request.\n\nThus, it requires a higher request rate limit to avoid the API to return a 204 error (Request rate limit exceeded), and the data parsed from the different requests are returned as MISP attributes and objects, with the corresponding relations between each one of them." } diff --git a/doc/expansion/virustotal_public.json b/doc/expansion/virustotal_public.json new file mode 100644 index 0000000..242c734 --- /dev/null +++ b/doc/expansion/virustotal_public.json @@ -0,0 +1,9 @@ +{ + "description": "Module to get information from VirusTotal.", + "logo": "logos/virustotal.png", + "requirements": ["An access to the VirusTotal API (apikey)"], + "input": "A domain, hostname, ip, url or hash (md5, sha1, sha256 or sha512) attribute.", + "output": "MISP attributes and objects resulting from the parsing of the VirusTotal report concerning the input attribute.", + "references": ["https://www.virustotal.com", "https://developers.virustotal.com/reference"], + "features": "New format of modules able to return attributes and objects.\n\nA module to take a MISP attribute as input and query the VirusTotal API to get additional data about it.\n\nCompared to the [more advanced VirusTotal expansion module](https://github.com/MISP/misp-modules/blob/master/misp_modules/modules/expansion/virustotal.py), this module is made for VirusTotal users who have a low request rate limit.\n\nThus, it only queries the API once and returns the results that is parsed into MISP attributes and objects." +}