Merge pull request #7 from fireeye/feature/dod-1.2.0

Reverted submit_file() function to 0.1.0 syntax and added get_artifac…

Author: jtviolet

CHANGE.md

@@ -1,3 +1,6 @@
+### Version 1.1.0
+- Reverted the file_submit function back to 0.1.0 since the body parameter is used for additional options and specifying file size cutoffs is not the preferred way to handle large files.
+- Added the get_artifact() function.
 ### Version 1.0.0
 - Changed parameters for submit_file function.  Eliminated the "body" parameter since it isn't needed, added "file_name" parameter to name the file, and added parameter "contents" to put the binary contents of the file.
 - Added an option to the submit_file function to specify how many bytes from the beginning of a file to send to the detection service.  Default is the first 32 MB, but is configurable to any positive integer.   

README.md

@@ -40,12 +40,27 @@ To obtain a free trial API key, subscribe on the [AWS Marketplace](https://aws.a
 
 ### Upload A File
 ```python
-response = detection.submit_file(file_name="myfile.txt", contents=open("path/to/myfile.txt", "rb"))
-```
- By default, submit_file() will only send the first 32 MB (32,000,000 bytes) of a file, which is the API limit, but this can be configured by setting the "file_size_limit" option to any positive integer, where the unit is bytes.  While you can send more than 32 MB, the API will only use the first 32 MB itself, so this option will save network bandwidth.
+  import fireeyepy
+
+  detection = fireeyepy.Detection(key="yourapikeyhere")
+
+  result = detection.submit_file(
+    files={
+      "file": ('filename', open('./path/to/filename', 'rb'))
+    }
+  )
 ```
-# Send the first 10 MB of the file
-result = detection.submit_file(file_name="myfile.txt", contents=open("path/to/myfile.txt", "rb"), file_size_limit=10000000)
+With configuration options:
+```python
+  result = detection.submit_file(
+    body={
+      "file_name": "different_name.txt",
+      "screenshot": true
+    },
+    files={
+      "file": ('filename', open('./path/to/filename', 'rb'))
+    }
+  )
 ```
 
 ### Retrieve File Report
@@ -66,3 +81,8 @@ result = detection.get_presigned_url(report_id)
 ```python
 response = detection.get_hash(hash)
 ```
+
+### Get a report artifact
+```python
+artifact = detection.get_artifact(report_id="8d0aa90b-8bf3-4483-ae3b-0ded00d157ab", artifact_type="screenshot")
+```

fireeyepy/__init__.py

@@ -5,7 +5,7 @@
 import requests
 import logging
 
-__version__ = "1.0.2"
+__version__ = "1.1.0"
 logger = logging.getLogger("fireeye")
 
 class Detection:
@@ -26,13 +26,24 @@ class Detection:
 
   detection = fireeyepy.Detection(key="yourapikeyhere")
 
-  result = detection.submit_file(file_name="myfile.txt", contents=open("path/to/myfile.txt", "rb"))
+  result = detection.submit_file(
+    files={
+      "file": ('filename', open('./path/to/filename', 'rb'))
+    }
+  )
   ```
 
-  By default, submit_file() will only send the first 32 MB (32,000,000 bytes) of a file, which is the API limit, but this can be configured by setting the "file_size_limit" option to any positive integer, where the unit is bytes.  While you can send more than 32 MB, the API will only use the first 32 MB itself, so this option will save network bandwidth.
-  ```
-  # Send the first 10 MB of the file
-  result = detection.submit_file(file_name="myfile.txt", contents=open("path/to/myfile.txt", "rb"), file_size_limit=10000000)
+  Optionally, you can send body parameters:
+  ```python
+  result = detection.submit_file(
+    body={
+      "file_name": "different_name.txt",
+      "screenshot": true
+    },
+    files={
+      "file": ('filename', open('./path/to/filename', 'rb'))
+    }
+  )
   ```
   ------------------------------
 
@@ -63,8 +74,20 @@ class Detection:
   detection = fireeyepy.Detection(key="yourapikeyhere")
 
   result = detection.get_hash_lookup(hash="md5sumhashhere")
+  ```  
+  ------------------------------
+
+  Example of getting an artifact from a report.
+
+  ```python
+  import fireeyepy
+
+  detection = fireeyepy.Detection(key="yourapikeyhere")
+
+  result = detection.get_artifact(report_id="8d0aa90b-8bf3-4483-ae3b-0ded00d157ab", artifact_type="screenshot")
   ```
   """
+
   def __init__(self,key=None):
     self.api_key = key or os.environ.get("FIREEYE_API_KEY", None)
     self.api_host = "feapi.marketplace.apps.fireeye.com"
@@ -74,23 +97,17 @@ def __init__(self,key=None):
     self.headers = {"User-Agent": user_agent, "feye-auth-key": key}
     self.session = requests.Session()
 
-  def submit_file(self, file_name, contents, file_size_limit=32000000):
-    """Allows you to submit a binary file object for malware analysis.
+  def submit_file(self, body=None, files=None):
+    """Allows you to submit a file object for malware analysis.
     
     Keyword Arguments:
-        file_name {string} -- The name of the file
-        contents {io.BufferedIOBase} -- The contents of the file in binary
-        file_size_limit {integer} -- The number of bytes to send to the detection service from the beginning of the file.  Files that are smaller than the limit will be sent in their entirety.  Files that are larger than this limit will only have the first 'n' bytes sent.  Default is 32 MB (32,000,000 bytes).
+        body {dict} -- The body of your http request. This is optional. (default: {None})
+        files {io.TextIOWrapper} -- The file you will be submitting for analysis. (default: {None})
     
     Returns:
         dict -- Returns a dict of the http response.
     """
-    contents.seek(0) # Make sure the file handler is at byte 0 so we can read the next 'n' bytes
-    files = {
-      "file": (file_name, contents.read(file_size_limit))
-    }
-
-    return self.post(self.api_host, "/files", None, files)
+    return self.post(self.api_host, "/files", body, files)
 
   def get_report(self, report_id, extended=False):
     """Allows you to get the report details for a file or hash submission.
@@ -119,6 +136,18 @@ def get_hash(self, hash):
     """
     return self.get(self.api_host, "/hashes/{}".format(hash))
 
+  def get_artifact(self, report_id, artifact_type):
+    """This endpoint fetches the screenshot gif file for the given report_id
+    
+    Arguments:
+        report_id {string} -- The ID of the report to get artifacts for
+        artifact_type {string} -- The type of artifact to get. ex. 'screenshot'
+    
+    Returns:
+        dict -- Returns a dict of the http response.
+    """
+    return self.get(self.api_host, "/artifacts/{}?type={}".format(report_id,artifact_type))
+
   def get(self, host, request_uri, params=None):
     uri = "https://{host}{request_uri}".format(host=host, request_uri=request_uri)
     headers = self.headers

setup.py

@@ -6,7 +6,7 @@
 
 setup(
   name="fireeyepy",
-  version="1.0.2",
+  version="1.1.0",
   description="FireEye Client Library for Python",
   long_description=long_description,
   long_description_content_type="text/markdown",