Merge pull request #552 from GDATASoftwareAG/python/add-verdict-docum…

…entation

Update Pythons scan function comments with return dict details

python/README.md

@@ -20,6 +20,26 @@ If you want to request if a file behind a URL is safe, you can specify the URL a
 
 You can also ask for a file itself. You will still get the benefit of a fast verdict via Sha256 because the SDK will do that for you first. But additionally, if we don't know the file, the file will get uploaded and (automatically) analyzed by us.
 
+## What do the Verdicts look like
+
+The verdicts are simple. They are either
+- `Clean`: The scanners didn't find anything malicious.
+- `Malicious`: The scanners found something malicious.
+- `Unknown`: We don't know the file hash yet. A scan is then performed for each except `for_sha256` function.
+- `Pup`: Potentially Unwanted Program (Adware, Spyware, etc.)
+
+The scan functions will return the following dict:
+```python
+{
+    "Sha256": "<Sha256>",
+    "Guid": "<Guid>",
+    "Verdict": <"Clean"|"Malicious"|"Unknown"|"Pup">,
+    "Detection": "<Name of the detected malware>",
+    "FileType": "<FileType>",
+    "MimeType": "<MimeType>"
+}
+```
+
 ## How to use
 
 ### Installation

python/examples/VaasExample/main.py

@@ -25,6 +25,16 @@ async def main():
         verdict = await vaas.for_file(path)
         print(f"{verdict['Sha256']} is detected as {verdict['Verdict']}")
 
+        # The scan functions will return the following dict:
+        # {
+        #     "Sha256": "<Sha256>",
+        #     "Guid": "<Guid>",
+        #     "Verdict": <"Clean"|"Malicious"|"Unknown"|"Pup">,
+        #     "Detection": "<Name of the detected malware if found>",
+        #     "FileType": "<FileType>",
+        #     "MimeType": "<MimeType>"
+        # }
+
 
 if __name__ == "__main__":
     loop = asyncio.new_event_loop()

python/examples/VaasExample/main_url.py

@@ -23,6 +23,16 @@ async def main():
         verdict = await vaas.for_url(url)
         print(f"Url {url} is detected as {verdict['Verdict']}")
 
+        # The scan functions will return the following dict:
+        # {
+        #     "Sha256": "<Sha256>",
+        #     "Guid": "<Guid>",
+        #     "Verdict": <"Clean"|"Malicious"|"Unknown"|"Pup">,
+        #     "Detection": "<Name of the detected malware if found>",
+        #     "FileType": "<FileType>",
+        #     "MimeType": "<MimeType>"
+        # }
+
 
 if __name__ == "__main__":
     loop = asyncio.new_event_loop()

python/src/vaas/vaas.py

@@ -5,7 +5,7 @@
 import json
 import time
 import uuid
-from typing import Optional
+from typing import Optional, TypedDict, Literal
 import asyncio
 from asyncio import Future
 import ssl
@@ -55,6 +55,22 @@ def __init__(self):
         self.use_cache = True
         self.use_hash_lookup = True
 
+class VaasVerdict(TypedDict):
+    Sha256: str
+    "The SHA256 hash of the file"
+
+    Guid: str
+
+    Verdict: Literal["Clean", "Malicious", "Unknown", "Pup"]
+
+    Detection: Optional[str]
+    "Name of the detected malware if found"
+
+    FileType: Optional[str]
+    "The file type of the file"
+
+    MimeType: Optional[str]
+    "The mime type of the file"
 
 def hash_file(filename):
     """Return sha256 hash for file"""
@@ -94,7 +110,7 @@ def problem_details_to_error(problem_details):
     return VaasServerError(details)
 
 
-def map_response(verdict_response):
+def map_response(verdict_response) -> VaasVerdict:
     return {
         "Sha256": verdict_response.get("sha256"),
         "Guid": verdict_response.get("guid"),
@@ -175,7 +191,7 @@ async def __aenter__(self):
     async def __aexit__(self, exc_type, exc, traceback):
         await self.close()
 
-    async def for_sha256(self, sha256, verdict_request_attributes=None, guid=None):
+    async def for_sha256(self, sha256, verdict_request_attributes=None, guid=None) -> VaasVerdict:
         """Returns the verdict for a SHA256 checksum"""
         verdict_response = await self.__for_sha256(
             sha256, verdict_request_attributes, guid
@@ -272,7 +288,7 @@ async def __receive_loop(self):
         except Exception as error:
             raise VaasConnectionClosedError(error) from error
 
-    async def for_buffer(self, buffer, verdict_request_attributes=None, guid=None):
+    async def for_buffer(self, buffer, verdict_request_attributes=None, guid=None) -> VaasVerdict:
         """Returns the verdict for a buffer"""
 
         loop = asyncio.get_running_loop()
@@ -307,7 +323,7 @@ async def _for_unknown_buffer(self, response, buffer, buffer_len):
         self.tracing.trace_upload_request(time.time() - start, buffer_len)
         return verdict_response
 
-    async def for_stream(self, asyncBufferedReader, len, verdict_request_attributes=None, guid=None):
+    async def for_stream(self, asyncBufferedReader, len, verdict_request_attributes=None, guid=None) -> VaasVerdict:
         """Returns the verdict for a file"""
 
         verdict_response = await self.__for_stream(
@@ -339,7 +355,7 @@ async def for_stream(self, asyncBufferedReader, len, verdict_request_attributes=
 
         return map_response(verdict_response)
 
-    async def for_file(self, path, verdict_request_attributes=None, guid=None):
+    async def for_file(self, path, verdict_request_attributes=None, guid=None) -> VaasVerdict:
         """Returns the verdict for a file"""
 
         loop = asyncio.get_running_loop()
@@ -376,7 +392,7 @@ async def __upload(self, token, upload_uri, buffer_or_file, content_length):
             self.tracing.trace_upload_timeout(content_length)
             raise VaasTimeoutError() from ex
 
-    async def for_url(self, url, verdict_request_attributes=None, guid=None):
+    async def for_url(self, url, verdict_request_attributes=None, guid=None) -> VaasVerdict:
         """Returns the verdict for a file from an url"""
         if verdict_request_attributes is not None and not isinstance(
             verdict_request_attributes, dict