add: Completed documentation for expansion modules

doc/expansion/otx.json

@@ -1,4 +1,9 @@
 {
     "description": "Module to get information from AlienVault OTX.",
-    "logo": "logos/otx.png"
+    "logo": "logos/otx.png",
+    "requirements": ["An access to the OTX API (apikey)"],
+    "input": "A MISP attribute included in the following list:\n- hostname\n- domain\n- ip-src\n- ip-dst\n- md5\n- sha1\n- sha256\n- sha512",
+    "output": "MISP attributes mapped from the result of the query on OTX, included in the following list:\n- domain\n- ip-src\n- ip-dst\n- text\n- md5\n- sha1\n- sha256\n- sha512\n- email",
+    "references": ["https://www.alienvault.com/open-threat-exchange"],
+    "features": "This module takes a MISP attribute as input to query the OTX Alienvault API. The API returns then the result of the query with some types we map into compatible types we add as MISP attributes."
 }

doc/expansion/passivetotal.json

@@ -1,4 +1,9 @@
 {
-    "description": "The PassiveTotal MISP expansion module brings the datasets derived from Internet scanning directly into your MISP instance. This module supports passive DNS, historic SSL, WHOIS, and host attributes. In order to use the module, you must have a valid PassiveTotal account username and API key. Registration is free and can be done by visiting https://www.passivetotal.org/register",
-    "logo": "logos/passivetotal.png"
+    "description": "",
+    "logo": "logos/passivetotal.png",
+    "requirements": ["Passivetotal python library", "An access to the PassiveTotal API (apikey)"],
+    "input": "A MISP attribute included in the following list:\n- hostname\n- domain\n- ip-src\n- ip-dst\n- x509-fingerprint-sha1\n- email-src\n- email-dst\n- target-email\n- whois-registrant-email\n- whois-registrant-phone\n- text\n- whois-registrant-name\n- whois-registrar\n- whois-creation-date",
+    "output": "MISP attributes mapped from the result of the query on PassiveTotal, included in the following list:\n- hostname\n- domain\n- ip-src\n- ip-dst\n- x509-fingerprint-sha1\n- email-src\n- email-dst\n- target-email\n- whois-registrant-email\n- whois-registrant-phone\n- text\n- whois-registrant-name\n- whois-registrar\n- whois-creation-date\n- md5\n- sha1\n- sha256\n- link",
+    "references": ["https://www.passivetotal.org/register"],
+    "features": "The PassiveTotal MISP expansion module brings the datasets derived from Internet scanning directly into your MISP instance. This module supports passive DNS, historic SSL, WHOIS, and host attributes. In order to use the module, you must have a valid PassiveTotal account username and API key. Registration is free and can be done by visiting https://www.passivetotal.org/register"
 }

doc/expansion/rbl.json

@@ -1,4 +1,8 @@
 {
     "description": "Module to check an IPv4 address against known RBLs.",
-    "requirements": ["dnspython3"]
+    "requirements": ["dnspython3: DNS python3 library"],
+    "input": "IP address attribute.",
+    "output": "Text with additional data from Real-time Blackhost Lists about the IP address.",
+    "references": ["[RBLs list](https://github.com/MISP/misp-modules/blob/8817de476572a10a9c9d03258ec81ca70f3d926d/misp_modules/modules/expansion/rbl.py#L20)"],
+    "features": "This module takes an IP address attribute as input and queries multiple know Real-time Blackhost Lists to check if they have already seen this IP address.\n\nWe display then all the information we get from those different sources."
 }

doc/expansion/reversedns.json

@@ -1,3 +1,7 @@
 {
-    "description": "Simple Reverse DNS expansion service to resolve reverse DNS from MISP attributes."
+    "description": "Simple Reverse DNS expansion service to resolve reverse DNS from MISP attributes.",
+    "requirements": ["DNS python library"],
+    "input": "An IP address attribute.",
+    "output": "Hostname attribute the input is resolved into.",
+    "features": "The module takes an IP address as input and tries to find the hostname this IP address is resolved into.\n\nThe address of the DNS resolver to use is also configurable, but if no configuration is set, we use the Google public DNS address (8.8.8.8).\n\nPlease note that composite MISP attributes containing IP addresses are supported as well."
 }

doc/expansion/securitytrails.json

@@ -0,0 +1,9 @@
+{
+    "description": "An expansion modules for SecurityTrails.",
+    "logo": "logos/securitytrails.png",
+    "requirements": ["dnstrails python library", "An access to the SecurityTrails API (apikey)"],
+    "input": "A domain, hostname or IP address attribute.",
+    "output": "MISP attributes resulting from the query on SecurityTrails API, included in the following list:\n- hostname\n- domain\n- ip-src\n- ip-dst\n- dns-soa-email\n- whois-registrant-email\n- whois-registrant-phone\n- whois-registrant-name\n- whois-registrar\n- whois-creation-date\n- domain",
+    "references": ["https://securitytrails.com/"],
+    "features": "The module takes a domain, hostname or IP address attribute as input and queries the SecurityTrails API with it.\n\nMultiple parsing operations are then processed on the result of the query to extract a much information as possible.\n\nFrom this data extracted are then mapped MISP attributes."
+}

doc/expansion/shodan.json

@@ -1,4 +1,9 @@
 {
     "description": "Module to query on Shodan.",
-    "logo": "logos/shodan.png"
+    "logo": "logos/shodan.png",
+    "requirements": ["shodan python library", "An access to the Shodan API (apikey)"],
+    "input": "An IP address MISP attribute.",
+    "output": "Text with additional data about the input, resulting from the query on Shodan.",
+    "references": ["https://www.shodan.io/"],
+    "features": "The module takes an IP address as input and queries the Shodan API to get some additional data about it."
 }

doc/expansion/sigma_queries.json

@@ -0,0 +1,9 @@
+{
+    "description": "An expansion hover module to display the result of sigma queries.",
+    "logo": "logos/sigma.png",
+    "requirements": ["Sigma python library"],
+    "input": "A Sigma attribute.",
+    "output": "Text displaying results of queries on the Sigma attribute.",
+    "references": ["https://github.com/Neo23x0/sigma/wiki"],
+    "features": "This module takes a Sigma rule attribute as input and tries all the different queries available to convert it into different formats recognized by SIEMs."
+}

doc/expansion/sigma_syntax_validator.json

@@ -0,0 +1,9 @@
+{
+    "description": "An expansion hover module to perform a syntax check on sigma rules.",
+    "logo": "logos/sigma.png",
+    "requirements": ["Sigma python library", "Yaml python library"],
+    "input": "A Sigma attribute.",
+    "output": "Text describing the validity of the Sigma rule.",
+    "references": ["https://github.com/Neo23x0/sigma/wiki"],
+    "features": "This module takes a Sigma rule attribute as input and performs a syntax check on it.\n\nIt displays then that the rule is valid if it is the case, and the error related to the rule otherwise."
+}

doc/expansion/sourcecache.json

@@ -1,3 +1,8 @@
 {
-    "description": "Module to cache web pages of analysis reports, OSINT sources. The module returns a link of the cached page."
+    "description": "Module to cache web pages of analysis reports, OSINT sources. The module returns a link of the cached page.",
+    "requirements": ["urlarchiver: python library to fetch and archive URL on the file-system"],
+    "input": "A link or url attribute.",
+    "output": "A malware-sample attribute describing the cached page.",
+    "references": ["https://github.com/adulau/url_archiver"],
+    "features": "This module takes a link or url attribute as input and caches the related web page. It returns then a link of the cached page."
 }

doc/expansion/stix2_pattern_syntax_validator.json

@@ -0,0 +1,9 @@
+{
+    "description": "An expansion hover module to perform a syntax check on stix2 patterns.",
+    "logo": "logos/stix.png",
+    "requirements": ["stix2patterns python library"],
+    "input": "A STIX2 pattern attribute.",
+    "output": "Text describing the validity of the STIX2 pattern.",
+    "references": ["[STIX2.0 patterning specifications](http://docs.oasis-open.org/cti/stix/v2.0/cs01/part5-stix-patterning/stix-v2.0-cs01-part5-stix-patterning.html)"],
+    "features": "This module takes a STIX2 pattern attribute as input and performs a syntax check on it.\n\nIt displays then that the rule is valid if it is the case, and the error related to the rule otherwise."
+}

doc/expansion/threatcrowd.json

@@ -1,4 +1,8 @@
 {
     "description": "Module to get information from ThreatCrowd.",
-    "logo": "logos/threatcrowd.png"
+    "logo": "logos/threatcrowd.png",
+    "input": "A MISP attribute included in the following list:\n- hostname\n- domain\n- ip-src\n- ip-dst\n- md5\n- sha1\n- sha256\n- sha512\n- whois-registrant-email",
+    "output": "MISP attributes mapped from the result of the query on ThreatCrowd, included in the following list:\n- domain\n- ip-src\n- ip-dst\n- text\n- md5\n- sha1\n- sha256\n- sha512\n- hostname\n- whois-registrant-email",
+    "references": ["https://www.threatcrowd.org/"],
+    "features": "This module takes a MISP attribute as input and queries ThreatCrowd with it.\n\nThe result of this query is then parsed and some data is mapped into MISP attributes in order to enrich the input attribute."
 }

doc/expansion/threatminer.json

@@ -1,4 +1,8 @@
 {
     "description": "Module to get information from ThreatMiner.",
-    "logo": "logos/threatminer.png"
+    "logo": "logos/threatminer.png",
+    "input": "A MISP attribute included in the following list:\n- hostname\n- domain\n- ip-src\n- ip-dst\n- md5\n- sha1\n- sha256\n- sha512",
+    "output": "MISP attributes mapped from the result of the query on ThreatMiner, included in the following list:\n- domain\n- ip-src\n- ip-dst\n- text\n- md5\n- sha1\n- sha256\n- sha512\n- ssdeep\n- authentihash\n- filename\n- whois-registrant-email\n- url\n- link",
+    "references": ["https://www.threatminer.org/"],
+    "features": "This module takes a MISP attribute as input and queries ThreatMiner with it.\n\nThe result of this query is then parsed and some data is mapped into MISP attributes in order to enrich the input attribute."
 }

doc/expansion/urlscan.json

@@ -0,0 +1,9 @@
+{
+    "description": "An expansion module to query urlscan.io.",
+    "logo": "logos/urlscan.jpg",
+    "requirements": ["An access to the urlscan.io API"],
+    "input": "A domain, hostname or url attribute.",
+    "output": "MISP attributes mapped from the result of the query on urlscan.io.",
+    "references": ["https://urlscan.io/"],
+    "features": "This module takes a MISP attribute as input and queries urlscan.io with it.\n\nThe result of this query is then parsed and some data is mapped into MISP attributes in order to enrich the input attribute."
+}

doc/expansion/virustotal.json

@@ -1,4 +1,9 @@
 {
     "description": "Module to get information from virustotal.",
-    "logo": "logos/virustotal.png"
+    "logo": "logos/virustotal.png",
+    "requirements": ["An access to the VirusTotal API (apikey)"],
+    "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."
 }

doc/expansion/vmray_submit.json

@@ -1,4 +1,9 @@
 {
     "description": "Module to submit a sample to VMRay.",
-    "logo": "logos/vmray.png"
+    "logo": "logos/vmray.png",
+    "requirements": ["An access to the VMRay API (apikey & url)"],
+    "input": "An attachment or malware-sample attribute.",
+    "output": "MISP attributes mapped from the result of the query on VMRay API, included in the following list:\n- text\n- sha1\n- sha256\n- md5\n- link",
+    "references": ["https://www.vmray.com/"],
+    "features": "This module takes an attachment or malware-sample attribute as input to query the VMRay API.\n\nThe sample contained within the attribute in then enriched with data from VMRay mapped into MISP attributes."
 }

doc/expansion/vulndb.json

@@ -1,4 +1,9 @@
 {
     "description": "Module to query VulnDB (RiskBasedSecurity.com).",
-    "logo": "logos/vulndb.png"
+    "logo": "logos/vulndb.png",
+    "requirements": ["An access to the VulnDB API (apikey, apisecret)"],
+    "input": "A vulnerability attribute.",
+    "output": "Additional data enriching the CVE input, fetched from VulnDB.",
+    "references": ["https://vulndb.cyberriskanalytics.com/"],
+    "features": "This module takes a vulnerability attribute as input and queries VulnDB in order to get some additional data about it.\n\nThe API gives the result of the query which can be displayed in the screen, and/or mapped into MISP attributes to add in the event."
 }

doc/expansion/vulners.json

@@ -0,0 +1,9 @@
+{
+    "description": "An expansion hover module to expand information about CVE id using Vulners API.",
+    "logo": "logos/vulners.png",
+    "requirements": ["Vulners python library", "An access to the Vulners API"],
+    "input": "A vulnerability attribute.",
+    "output": "Text giving additional information about the CVE in input.",
+    "references": ["https://vulners.com/"],
+    "features": "This module takes a vulnerability attribute as input and queries the Vulners API in order to get some additional data about it.\n\nThe API then returns details about the vulnerability."
+}

doc/expansion/whois.json

@@ -1,4 +1,8 @@
 {
     "description": "Module to query a local instance of uwhois (https://github.com/rafiot/uwhoisd).",
-    "requirements": ["uwhois"]
+    "requirements": ["uwhois: A whois python library"],
+    "input": "A domain or IP address attribute.",
+    "output": "Text describing the result of a whois request for the input value.",
+    "references": ["https://github.com/rafiot/uwhoisd"],
+    "features": "This module takes a domain or IP address attribute as input and queries a 'Univseral Whois proxy server' to get the correct details of the Whois query on the input value (check the references for more details about this whois server)."
 }

doc/expansion/wiki.json

@@ -1,4 +1,9 @@
 {
     "description": "An expansion hover module to extract information from Wikidata to have additional information about particular term for analysis.",
-    "logo": "logos/wikidata.png"
+    "logo": "logos/wikidata.png",
+    "requirements": ["SPARQLWrapper python library"],
+    "input": "Text attribute.",
+    "output": "Text attribute.",
+    "references": ["https://www.wikidata.org"],
+    "features": "This module takes a text attribute as input and queries the Wikidata API. If the text attribute is clear enough to define a specific term, the API returns a wikidata link in response."
 }

doc/expansion/xforceexchange.json

@@ -1,4 +1,9 @@
 {
     "description": "An expansion module for IBM X-Force Exchange.",
-    "logo": "logos/xforce.png"
+    "logo": "logos/xforce.png",
+    "requirements": ["An access to the X-Force API (apikey)"],
+    "input": "A MISP attribute included in the following list:\n- ip-src\n- ip-dst\n- vulnerability\n- md5\n- sha1\n- sha256",
+    "output": "MISP attributes mapped from the result of the query on X-Force Exchange.",
+    "references": ["https://exchange.xforce.ibmcloud.com/"],
+    "features": "This module takes a MISP attribute as input to query the X-Force API. The API returns then additional information known in their threats data, that is mapped into MISP attributes."
 }