Skip to content

- Minor documentation update, #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bentleygd merged 4 commits into from
Jul 24, 2025
Merged

- Minor documentation update, #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
61f900d
- Minor documentation update,
Jul 24, 2025
3ad211a
Merge branch 'master' into release/v0.4.1
bentleygd Jul 24, 2025
b7a2035
Updated Python version in Workflow.
Jul 24, 2025
947b921
Merge branch 'release/v0.4.1' of https://github.com/bentleygd/CSIC in…
Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/pythonapp.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
108 changes: 52 additions & 56 deletions DOCs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -197,41 +190,44 @@ 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.

---

### `OTXCheck(self, otx_key)`
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.

---

Expand Down Expand Up @@ -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.

---

Expand All @@ -289,52 +285,52 @@ 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.

---

### `FSBChck(self, fsb_api)`
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.

---

### `UHChck(self)`
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.

---

### `OTXCheck(self, otx_key)`
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.
Expand Down Expand Up @@ -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.

---

Expand All @@ -401,32 +397,32 @@ 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.

---

### `FSBChck(self, fsb_api)`
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.

---

Expand All @@ -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).
Expand Down
39 changes: 5 additions & 34 deletions libs/osintchck.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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()
Expand All @@ -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')
Expand Down Expand Up @@ -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:
Expand All @@ -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.

Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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.

Expand Down