From 61f900dce2484a83ca09065b7691e0e95003cf50 Mon Sep 17 00:00:00 2001 From: bentleygd Date: Thu, 24 Jul 2025 08:54:01 -0700 Subject: [PATCH 1/2] - Minor documentation update, --- DOCs.md | 108 ++++++++++++++++++++++------------------------ libs/osintchck.py | 39 +++-------------- 2 files changed, 57 insertions(+), 90 deletions(-) diff --git a/DOCs.md b/DOCs.md index 6c5024d..2d4c195 100644 --- a/DOCs.md +++ b/DOCs.md @@ -15,7 +15,6 @@ Initializes the IP_OSINT object with the provided IP address and sets up instanc - `vt_results` (`dict`): Results from VirusTotal for the IP. - `vt_response` (`int`): The response code received from VirusTotal. - `fsb_mw` (`int`): Falcon Sandbox malware count for the IP. -- `tbl_status` (`str`): Talos block list status for the IP. - `uh_results` (`dict`): URLHaus results for the IP. - `adb_results` (`list`): AbuseIPDB results for the IP. - `otx_results` (`dict`): OTX results for the IP. @@ -53,18 +52,12 @@ Checks Falcon Sandbox (Hybrid Analysis) for malware information regarding the pr --- -### `TBLChck(self)` -Checks whether the IP address is on the Talos block list. - -#### Outputs: -- `tbl_status` (`str`): Whether the IP is listed as blocked or not. -- `response.status_code` (`int`): The HTTP response code returned by the Talos website. - ---- - ### `UHChck(self)` Checks URLHaus for information about the provided IP address. +### Required Input: +- `abusech_api` (`str`): A valid URLHaus API key. + #### Outputs: - `uh_results` (`dict`): A dictionary containing information about the IP address on URLHaus, including malware count and blacklisting status. - `query_status` (`str`): The query status returned by the URLHaus API. @@ -197,24 +190,27 @@ Checks VirusTotal for information on the specified domain. Checks Hybrid-Analysis (Falcon Sandbox) for information about the given domain. #### Required Input: -- fsb_api (str): The Falcon Sandbox API key. +- `fsb_api` (`str`): The Falcon Sandbox API key. #### Outputs: -- fsb_ts_avg (int): The average threat score for the given domain. +- `fsb_ts_avg` (`int`): The average threat score for the given domain. #### Returns: -- response.status_code (int): The HTTP status code returned by Hybrid-Analysis. +- `response.status_code` (`int`): The HTTP status code returned by Hybrid-Analysis. --- -### `UHChck(self)` +### `UHChck(self, abusech_api)` Checks URLHaus for information about the given domain. +### Required Input: +- `abusech_api` (`str`) + #### Outputs: -- uh_results (dict): A dictionary containing results from URLHaus regarding the domain. +- `uh_results` (`dict`): A dictionary containing results from URLHaus regarding the domain. #### Returns: -- response.get('query_status') (str): The query status returned by the URLHaus API. +- `response.get('query_status')` (`str`): The query status returned by the URLHaus API. --- @@ -222,16 +218,16 @@ Checks URLHaus for information about the given domain. Retrieves malware data for the given domain from AlienVault OTX. #### Required Input: -- otx_key (str): The API key for AlienVault OTX. +- `otx_key` (`str`): The API key for AlienVault OTX. #### Outputs: -- otx_results (dict): A dictionary containing OTX-related malware data for the domain. +- `otx_results` (`dict`): A dictionary containing OTX-related malware data for the domain. #### Returns: -- response.status_code (int): The HTTP status code returned by the AlienVault OTX API. +- `response.status_code` (`int`): The HTTP status code returned by the AlienVault OTX API. #### Exceptions: -- HTTPError: Raised when the endpoint returns a non-200 HTTP response. +- `HTTPError`: Raised when the endpoint returns a non-200 HTTP response. --- @@ -270,16 +266,16 @@ The `URLOSINT` class is designed to retrieve Open Source Intelligence (OSINT) re Initializes the `URLOSINT` object with the given URL. #### Parameters: -- `b_url` (str): The URL to check. +- `b_url` (`str`): The URL to check. #### Instance Variables: -- `b_url` (str): The URL to check. -- `vt_response` (int): The response code returned by the VirusTotal API. -- `vc_results` (dict): The results returned by the VirusTotal API. -- `fsb_mw` (int): The count of associated malware according to Hybrid Analysis. -- `uh_results` (dict): The results returned by URLHaus. -- `otx_results` (int): The results returned by OTX (AlienVault). -- `log` (logging.Logger): Logger instance for logging information and errors. +- `b_url` (`str`): The URL to check. +- `vt_response` (`int`): The response code returned by the VirusTotal API. +- `vc_results` (`dict`): The results returned by the VirusTotal API. +- `fsb_mw` (`int`): The count of associated malware according to Hybrid Analysis. +- `uh_results` (`dict`): The results returned by URLHaus. +- `otx_results` (`int`): The results returned by OTX (AlienVault). +- `log` (`logging.Logger`): Logger instance for logging information and errors. --- @@ -289,13 +285,13 @@ Initializes the `URLOSINT` object with the given URL. Checks VirusTotal for information about a given URL. #### Parameters: -- `vt_api` (str): The VirusTotal API key. +- `vt_api` (`str`): The VirusTotal API key. #### Outputs: -- `vc_results` (dict): A dictionary containing VirusTotal scan date, positives, and permalink. +- `vc_results` (`dict`): A dictionary containing VirusTotal scan date, positives, and permalink. #### Returns: -- `response.status_code` (int): The HTTP response code returned by the VirusTotal API. +- `response.status_code` (`int`): The HTTP response code returned by the VirusTotal API. --- @@ -303,13 +299,13 @@ Checks VirusTotal for information about a given URL. Checks Hybrid Analysis (FalconSandbox) for information about a given URL. #### Parameters: -- `fsb_api` (str): The FalconSandbox API key. +- `fsb_api` (`str`): The FalconSandbox API key. #### Outputs: -- `fsb_mw` (int): The count of malware samples associated with the given URL. +- `fsb_mw` (`int`): The count of malware samples associated with the given URL. #### Returns: -- `response.status_code` (int): The HTTP response code returned by the Hybrid Analysis API. +- `response.status_code` (`int`): The HTTP response code returned by the Hybrid Analysis API. --- @@ -317,10 +313,10 @@ Checks Hybrid Analysis (FalconSandbox) for information about a given URL. Checks URLHaus for information about a given URL. #### Outputs: -- `uh_results` (dict): A dictionary containing threat status, blacklists, and reference URLs. +- `uh_results` (`dict`): A dictionary containing threat status, blacklists, and reference URLs. #### Returns: -- `response.get('query_status')` (str): The query status returned by the URLHaus API. +- `response.get('query_status')` (`str`): The query status returned by the URLHaus API. --- @@ -328,13 +324,13 @@ Checks URLHaus for information about a given URL. Retrieves general reputation data for a given URL from AlienVault OTX. #### Parameters: -- `otx_key` (str): The API key for AlienVault OTX. +- `otx_key` (`str`): The API key for AlienVault OTX. #### Outputs: -- `otx_results` (int): The number of OTX pulses associated with the given URL. +- `otx_results` (`int`): The number of OTX pulses associated with the given URL. #### Returns: -- `response.status_code` (int): The HTTP response code returned by the AlienVault OTX API. +- `response.status_code` (`int`): The HTTP response code returned by the AlienVault OTX API. #### Exceptions: - `HTTPError`: Raised if the HTTP request to OTX returns a non-200 status code. @@ -382,16 +378,16 @@ This class provides methods to check file reputation and other related data from Initializes the `FileOSINT` object with the provided SHA256 hash. #### Parameters: -- `filehash` (str): The SHA256 hash of the file. +- `filehash` (`str`): The SHA256 hash of the file. #### Instance Variables: -- `hash` (str): The SHA256 hash of the file. -- `vt_response` (int): The response code returned by the VirusTotal API. -- `vt_results` (dict): The results returned by VirusTotal for the supplied file hash. -- `fsb_r_code` (int): The FalconSandbox response code. -- `fsb_results` (dict): The results returned by FalconSandbox for the supplied file hash. -- `otx_results` (dict): The general data from AlienVault OTX for the supplied file hash. -- `log` (logging.Logger): Logger instance for logging information and errors. +- `hash` (`str`): The SHA256 hash of the file. +- `vt_response` (`int`): The response code returned by the VirusTotal API. +- `vt_results` (`dict`): The results returned by VirusTotal for the supplied file hash. +- `fsb_r_code` (`int`): The FalconSandbox response code. +- `fsb_results` (`dict`): The results returned by FalconSandbox for the supplied file hash. +- `otx_results` (`dic`t): The general data from AlienVault OTX for the supplied file hash. +- `log` (`logging.Logger`): Logger instance for logging information and errors. --- @@ -401,16 +397,16 @@ Initializes the `FileOSINT` object with the provided SHA256 hash. Checks VirusTotal for information related to the provided file hash. #### Parameters: -- `vt_api` (str): The API key for VirusTotal. +- `vt_api` (`str`): The API key for VirusTotal. #### Outputs: -- `vt_results` (dict): The results returned by the VirusTotal API for the given file hash. Includes: +- `vt_results` (`dict`): The results returned by the VirusTotal API for the given file hash. Includes: - `'av_detect'`: Number of antivirus engines that detected the file. - `'av_percentage'`: The percentage of antivirus engines that detected the file. - `'ref_url'`: The permalink to the VirusTotal report. #### Returns: -- `response.status_code` (int): The HTTP status code returned by the VirusTotal API. +- `response.status_code` (`int`): The HTTP status code returned by the VirusTotal API. --- @@ -418,15 +414,15 @@ Checks VirusTotal for information related to the provided file hash. Checks FalconSandbox (Hybrid Analysis) for information related to the provided file hash. #### Parameters: -- `fsb_api` (str): The API key for FalconSandbox. +- `fsb_api` (`str`): The API key for FalconSandbox. #### Outputs: -- `fsb_results` (dict): The results returned by the FalconSandbox API regarding the file hash. Includes: +- `fsb_results` (`dict`): The results returned by the FalconSandbox API regarding the file hash. Includes: - `'verdict'`: The verdict of the file analysis (e.g., malicious, suspicious). - `'m_family'`: The malware family associated with the file, if applicable. #### Returns: -- `response.status_code` (int): The HTTP status code returned by FalconSandbox API. +- `response.status_code` (`int`): The HTTP status code returned by FalconSandbox API. --- @@ -440,15 +436,15 @@ Checks FalconSandbox (Hybrid Analysis) for information related to the provided f Retrieves general data from AlienVault OTX for the supplied file hash. #### Parameters: -- `otx_key` (str): The API key for AlienVault OTX. +- `otx_key` (`str`): The API key for AlienVault OTX. #### Outputs: -- `otx_results` (dict): A dictionary containing: +- `otx_results` (`dict`): A dictionary containing: - `'p_count'`: The pulse count, representing the number of OTX pulses associated with the file hash. - `'m_families'`: A set of unique malware family names associated with the file. #### Returns: -- `response.status_code` (int): The HTTP status code returned by the AlienVault OTX API. +- `response.status_code` (`int`): The HTTP status code returned by the AlienVault OTX API. #### Exceptions: - **HTTPError**: Raised if the response from OTX is not successful (non-200 status code). diff --git a/libs/osintchck.py b/libs/osintchck.py index be4e062..aebbdbb 100644 --- a/libs/osintchck.py +++ b/libs/osintchck.py @@ -35,7 +35,6 @@ def __init__(self, ip): vt_results - results from VirusTotal for the IP.. vt_response - The response code received from VirusTotal. fsb_mw - Falcon SandBox malwre count for the IP. - tbl_status - Talos block list results for the IP. uh_results - URLHaus results for the IP. adb_results - AbuseIPDB results for the IP. otx_results - OTX results for the IP. @@ -46,7 +45,6 @@ def __init__(self, ip): VTChck - Checks VirusTotal for info for a given IP address. FSBChck - Checks Falcon Sandbox (hybrid-analysis) for info for a given IP. - TBLChck - Checks to see if an IP is on the Talos block list. UHChck - Checks URLHaus for info for a given IP. AIDBChck - Checks the AbuseIP database for a given IP. OTXCheck - Retrieves data from AlienVault OTX for a given IP. @@ -56,7 +54,6 @@ def __init__(self, ip): self.vt_results = dict() self.vt_response = int() self.fsb_mw = int() - self.tbl_status = str() self.uh_results = dict() self.adb_results = list() self.otx_results = dict() @@ -81,7 +78,7 @@ def VTChck(self, vt_api): response = get(url, params=params, timeout=5) if response.status_code == 200: self.log.info( - f'Succesfully retrieved data from VirusTotal for {self.ip}' + 'Succesfully retrieved data from VirusTotal for %s', self.ip ) data = response.json() self.vt_response = data.get('response_code') @@ -127,12 +124,12 @@ def FSBChck(self, fsb_api): response = post(url, headers=headers, data=data, timeout=5) if response.status_code == 200: self.log.info( - f'Successfully retrieved data from hybrid-analysis for {self.ip}' + 'Successfully retrieved data from hybrid-analysis for %s', self.ip ) self.fsb_mw = response.json().get('count') else: self.log.error( - f'Error when retrieving data from FSB for {self.ip}. The HTTP response code is {response.status_code}' + 'Error when retrieving data from FSB for %s. The HTTP response code is %s' % (self.ip, response.status_code) ) status_code = 200 except Timeout: @@ -143,29 +140,6 @@ def FSBChck(self, fsb_api): status_code = 495 return status_code - def TBLChck(self): - """Checks to see if an IP is on the Talos block list. - - Outputs: - tbl_status - Whether or not a given IP address is on the Talos - block list. - - Returns: - response.status_code - The HTTP response code returned by the - Talos website.""" - url = 'https://talosintelligence.com/documents/ip-blacklist' - response = get(url, timeout=5) - data = response.text.split('\n') - if self.ip in data: - self.tbl_status = 'block listed IP' - else: - self.tbl_status = 'Non-block listed IP' - if response.status_code == 200: - self.log.info('Successfully retrieved Talos IP black list.') - else: - self.log.error('Unable to retrieve Talos black list from Cisco.') - return response.status_code - def UHChck(self, abusech_api): """Checks URLHaus for info for a given IP. @@ -474,11 +448,8 @@ def UHChck(self, abusech_api): } else: self.log.error( - 'Unable to retrieve information from URLHaus for ' + - '%s. The query response is: %s' % ( - self.domain, response.get('query_status') + 'Unable to retrieve information from URLHaus for %s. The query response is: %s' % (self.domain, response.get('query_status')) ) - ) return response.get('query_status') def OTXCheck(self, otx_key): @@ -1086,7 +1057,7 @@ def get_adb_bl(self, api_key): if validateIP(ip): self.adb_bl.append(ip + '/32') return response.status_code - + def get_tor_exits(self): """Checks if an IP address is a TOR Exit node. From b7a2035182cce1ab73554c1a6f0cab0aa5592541 Mon Sep 17 00:00:00 2001 From: bentleygd Date: Thu, 24 Jul 2025 08:57:17 -0700 Subject: [PATCH 2/2] Updated Python version in Workflow. --- .github/workflows/pythonapp.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pythonapp.yml b/.github/workflows/pythonapp.yml index 6cb3b22..df48ea0 100644 --- a/.github/workflows/pythonapp.yml +++ b/.github/workflows/pythonapp.yml @@ -12,10 +12,10 @@ jobs: steps: - uses: actions/checkout@v1 - - name: Set up Python 3.11.10 + - name: Set up Python 3.11.13 uses: actions/setup-python@v1 with: - python-version: 3.11.10 + python-version: 3.11.13 - name: Install dependencies run: | python -m pip install --upgrade pip