feat: add url analysis support (#33)

* feat: add url analysis support

Co-authored-by: Jonathan Abrahamy <[email protected]>

CHANGES

@@ -1,3 +1,9 @@
+1.7.0
+-------
+- Add UrlAnalysis
+- `Analysis` was renamed to `FileAnalysis`
+- Drop support for python 3.5, add support for python 3.10
+
 1.6.4 - 1.6.10
 -------
 - Analysis summary utility improvements

README.md

@@ -9,6 +9,7 @@ Currently, the following options are available in the SDK:
 
 - Analyze by file
 - Analyze by SHA256
+- Analyze Url
 - Index by file
 - Index by SHA256
 - Get Latest Analysis
@@ -33,20 +34,20 @@ api.set_global_api('<api_key>')
 
 ### Analyze By File
 ```python
-analysis = Analysis(file_path=<file_path>,
+analysis = FileAnalysis(file_path=<file_path>,
                     dynamic_unpacking=<force_dynamic_unpacking>, # optional
                     static_unpacking=<force_static_unpacking>)   # optional
 analysis.send(wait=True) 
 result = analysis.result()
 ```
 ### Analyze By SHA256
 ```python
-analysis = Analysis(file_hash=<file_sha256>)
+analysis = FileAnalysis(file_hash=<file_sha256>)
 analysis.send(wait=True)
 result = analysis.result()
 ```
 
-### Analysis result example
+### File Analysis result example
 ```python
 {
   'analysis_id': '00000000-0000-0000-0000-000000000000', 
@@ -59,6 +60,66 @@ result = analysis.result()
   'verdict': 'malicious'
 }
 ```
+### Analyze Url
+```python
+analysis = UrlAnalysis(url=<url>)
+analysis.send(wait=True)
+result = analysis.result()
+```
+### Url Analysis result example
+```python
+{
+    'analysis_id': '70d09f68-c7a3-43a3-a8de-07ec31fbf4ed',
+    'domain_info': {
+        'creation_date': '1997-08-13 04:00:00.000000',
+        'domain_name': 'foo.com',
+        'registrar': 'TUCOWS, INC.'
+    },
+    'indicators': [
+    {
+        'classification': 'informative',
+        'text': 'URL is accessible'
+    },
+    {
+        'classification': 'informative',
+        'text': 'Assigned IPv4 domain'
+    },
+    {
+        'classification': 'informative',
+        'text': 'Vaild IPv4 domain'
+    }
+    ],
+    'ip': '34.206.39.153',
+    'redirect_chain': [
+    {
+        'response_status': 301,
+        'url': 'https://foo.com/'
+    },
+    {
+        'response_status': 200,
+        'url': 'http://www.foo.com/'
+    }
+    ],
+    'scanned_url': 'http://www.foo.com/',
+    'submitted_url': 'foo.com',
+    'downloaded_file': {
+        'analysis_id': '8db9a401-a142-41be-9a31-8e5f3642db62',
+        'analysis_summary': {
+           'verdict_description': 'This file contains code from malicious software, therefore it's very likely that it's malicious.',
+           'verdict_name': 'malicious',
+           'verdict_title': 'Malicious',
+           'verdict_type': 'malicious'
+        },
+        'sha256': '4293c1d8574dc87c58360d6bac3daa182f64f7785c9d41da5e0741d2b1817fc7'
+     },
+    'summary': {
+        'description': 'No suspicious activity was detected for this URL',
+        'title': 'No Threats',
+        'verdict_name': 'no_threats',
+        'verdict_type': 'no_threats'
+    }
+}
+```
 ### Index By File
 ```python
 from intezer_sdk import consts
@@ -79,14 +140,14 @@ index.send(wait=True)
 index_id = index.index_id
 ```
 
-### Get Latest Analysis
+### Get Latest File Analysis
 ```python
 analysis = get_latest_analysis(file_hash: <file_sha256>)
 result = analysis.result()
 ```
 
 ### Get Sub Analyses
-#### Root Analysis
+#### Root File Analysis
 ```python
 root_analysis = analysis.get_root_analysis()
 ```
@@ -130,7 +191,7 @@ string_related_samples = operation.get_result()
 
 #### Wait with timeout
 ```python
-analysis = Analysis(file_hash=<file_sha256>)
+analysis = FileAnalysis(file_hash=<file_sha256>)
 analysis.send(wait=True, wait_timeout=datetime.timedelta(minutes=1))
 ```
 

examples/analyze_by_file.py

@@ -2,19 +2,19 @@
 from pprint import pprint
 
 from intezer_sdk import api
-from intezer_sdk.analysis import Analysis
+from intezer_sdk.analysis import FileAnalysis
 
 
 def send_file_with_wait(file_path):
     api.set_global_api('<api_key>')
-    analysis = Analysis(file_path=file_path)
+    analysis = FileAnalysis(file_path=file_path)
     analysis.send(wait=True)
     pprint(analysis.result())
 
 
 def send_file_without_wait(file_path):
     api.set_global_api('<api_key>')
-    analysis = Analysis(file_path=file_path)
+    analysis = FileAnalysis(file_path=file_path)
     analysis.send()
     analysis.wait_for_completion()
     pprint(analysis.result())

examples/analyze_by_hash.py

@@ -3,26 +3,26 @@
 from pprint import pprint
 
 from intezer_sdk import api
-from intezer_sdk.analysis import Analysis
+from intezer_sdk.analysis import FileAnalysis
 
 
 def analysis_by_hash_with_wait(file_hash):  # type: (str) -> None
     api.set_global_api('<api_key>')
-    analysis = Analysis(file_hash=file_hash)
+    analysis = FileAnalysis(file_hash=file_hash)
     analysis.send(wait=True)
     pprint(analysis.result())
 
 
 def analysis_by_hash_with_wait_timeout(file_hash):  # type: (str) -> None
     api.set_global_api('<api_key>')
-    analysis = Analysis(file_hash=file_hash)
+    analysis = FileAnalysis(file_hash=file_hash)
     analysis.send(wait=True, wait_timeout=datetime.timedelta(minutes=1))
     pprint(analysis.result())
 
 
 def analysis_by_hash_without_wait(file_hash):  # type: (str) -> None
     api.set_global_api('<api_key>')
-    analysis = Analysis(file_hash=file_hash)
+    analysis = FileAnalysis(file_hash=file_hash)
     analysis.send()
     analysis.wait_for_completion()
     pprint(analysis.result())

examples/analyze_folder.py

@@ -2,21 +2,21 @@
 import sys
 
 from intezer_sdk import api
-from intezer_sdk.analysis import Analysis
+from intezer_sdk.analysis import FileAnalysis
 
 API_KEY = os.environ.get('INTEZER_API_KEY')
 DIRECTORY_PATH = ''
 
 
-def send_analysis(analysis: Analysis):
+def send_analysis(analysis: FileAnalysis):
     analysis.send(wait=True)
     return analysis.result()
 
 
 def collect_suspicious_and_malicious_analyses() -> list:
     malicious_and_suspicious_analyses_results = []
     file_paths = [file for file in os.listdir(DIRECTORY_PATH)]
-    analyses = [Analysis(os.path.join(DIRECTORY_PATH, path)) for path in file_paths if
+    analyses = [FileAnalysis(os.path.join(DIRECTORY_PATH, path)) for path in file_paths if
                 os.path.isfile(os.path.join(DIRECTORY_PATH, path))]
 
     for analysis in analyses:

examples/analyze_url.py

@@ -0,0 +1,24 @@
+import sys
+from pprint import pprint
+
+from intezer_sdk import api
+from intezer_sdk.analysis import UrlAnalysis
+
+
+def send_url_with_wait(url):
+    api.set_global_api('<api_key>')
+    analysis = UrlAnalysis(url=url)
+    analysis.send(wait=True)
+    pprint(analysis.result())
+
+
+def send_url_without_wait(url):
+    api.set_global_api('<api_key>')
+    analysis = UrlAnalysis(url=url)
+    analysis.send()
+    analysis.wait_for_completion()
+    pprint(analysis.result())
+
+
+if __name__ == '__main__':
+    send_file_with_wait(*sys.argv[1:])

examples/sentinel_one_integration.py

@@ -19,7 +19,7 @@
 from intezer_sdk import api
 from intezer_sdk import errors
 from intezer_sdk import util
-from intezer_sdk.analysis import Analysis
+from intezer_sdk.analysis import FileAnalysis
 
 _s1_session: Optional[requests.Session] = None
 _logger = logging.getLogger('intezer')
@@ -65,7 +65,7 @@ def analyze_by_file(threat_id: str):
     download_url, zipp_password = fetch_file(threat_id)
     file = download_file(download_url)
     _logger.debug('starting to analyze file')
-    analysis = Analysis(file_stream=file, file_name=f'{threat_id}.zip', zip_password=zipp_password)
+    analysis = FileAnalysis(file_stream=file, file_name=f'{threat_id}.zip', zip_password=zipp_password)
     return analysis
 
 
@@ -143,7 +143,7 @@ def filter_threat(threat_info: dict) -> bool:
     return threat_info['agentDetectionInfo']['agentOsName'].lower().startswith(('linux', 'windows'))
 
 
-def send_note(threat_id: str, analysis: Analysis):
+def send_note(threat_id: str, analysis: FileAnalysis):
     note = util.get_analysis_summary(analysis)
 
     response = _s1_session.post('/web/api/v2.1/threats/notes',
@@ -174,7 +174,7 @@ def analyze_threat(threat_id: str, threat: dict = None):
         if file_hash:
             _logger.debug(f'trying to analyze by hash {file_hash}')
             try:
-                analysis = Analysis(file_hash=file_hash)
+                analysis = FileAnalysis(file_hash=file_hash)
                 analysis.send()
             except errors.HashDoesNotExistError:
                 _logger.debug(f'hash {file_hash} not found on server, fetching the file from endpoint')

intezer_sdk/__init__.py

@@ -1 +1 @@
-__version__ = '1.6.10'
+__version__ = '1.7.0'

intezer_sdk/_util.py

@@ -0,0 +1,11 @@
+import warnings
+
+
+def deprecated(message: str):
+    def wrapper(func):
+        warnings.warn(message,
+                      DeprecationWarning,
+                      stacklevel=2)
+        return func
+
+    return wrapper