The Orca
class provides functionality for searching, purging, and quarantining phishing emails. It integrates with the TrendMicro API to interact with email data, specifically focusing on Office 365 mailboxes. The class is designed to be invoked via CLI to perform tasks such as finding phishing emails, deleting them, or quarantining them for further investigation.
config
: The configuration file used across all instances of theOrca
class.
tm_api
: The API key used for authenticating requests to TrendMicro.api_counter
: A counter to track API usage and ensure rate limits are respected.
Initializes an instance of the Orca
class by loading configuration and setting up API authentication.
config
: TheOrca.config
configuration file.
tm_api
: API key fetched from the configuration file.api_counter
: Initialized to zero for tracking the number of API calls.
Searches for phishing emails based on provided keyword arguments, such as sender, subject, file extension, file hash, or URL.
sender
: (str) Malicious email address (required if not searching by URL or file hash).subject
: (str) Subject of the email (optional).file_ext
: (str) File extension (optional).file_hash
: (str) SHA1 file hash (optional).url
: (str) Phishing URL to search for (optional).
evil_list
: A list of dictionaries containing:mailbox
: Mailbox where the phishing email was found.mmi
: Mail message ID.mui
: Mail unique ID.d_time
: Delivery time of the email.
HTTPError
: Raised if a non-200 HTTP response is returned.
- The method constructs search parameters based on provided keyword arguments (e.g., sender, subject, file hash, etc.).
- It checks if the API rate limit has been reached and pauses execution if necessary.
- The method performs an HTTP GET request to the TrendMicro API to search for phishing emails.
- If the response is successful (HTTP 200), it processes the data and logs the results.
- The method returns a list of emails matching the search criteria.
Deletes phishing emails from Office 365 mailboxes.
evil_list
: A list of dictionaries containing phishing email details (mailbox, mmi, mui, d_time).
- None
HTTPError
: Raised if a non-201 HTTP response is returned when attempting to delete an email.
- The method iterates over the provided
evil_list
, and for each email, it constructs a request body with required parameters (mailbox, mmi, mui, etc.). - It ensures that the request does not exceed the maximum allowed batch size of 10 emails per request.
- The method checks if the API rate limit has been reached and pauses execution if necessary.
- After sending the request to delete emails, the method logs the result and increments the
api_counter
. - If an error occurs during the deletion process, it logs the exception and continues with the next email.
Quarantines phishing emails from Office 365 mailboxes.
evil_list
: A list of dictionaries containing phishing email details (mailbox, mmi, mui, d_time).
- None
HTTPError
: Raised if a non-201 HTTP response is returned when attempting to quarantine an email.
- Similar to the
purge_email
method, this method iterates over theevil_list
and constructs a request body to quarantine each email. - It ensures that the number of emails in each API request does not exceed the maximum allowed size.
- The method checks if the API rate limit is reached and pauses execution when necessary.
- After sending the request to quarantine emails, it logs the result and increments the
api_counter
. - If an error occurs during the quarantine process, it logs the exception and continues with the next email.
The class utilizes logging at various stages of the process:
- Debug Logs: To track the status of searches, deletions, and quarantines.
- Info Logs: To report the number of emails found, deleted, or quarantined.
- Exception Logs: To record any errors or abnormal responses from API requests.
# Instantiate the Orca class
orca = Orca()
# Search for phishing emails by sender
phishing_emails = orca.find_phish(sender='malicious@example.com')
# Purge the found phishing emails
orca.purge_email(phishing_emails)
# Quarantine the found phishing emails
orca.pull_email(phishing_emails)
- The class interacts with the TrendMicro API, specifically the
sweeping/mails
andmitigation/mails
endpoints, to perform phishing email searches, purges, and quarantines. - API rate limits are managed by the
api_counter
, which is reset after 60 seconds if the limit is reached. - The
find_phish
method supports various search criteria (sender, subject, URL, file hash, etc.), enabling flexible phishing email searches. - The
purge_email
andpull_email
methods allow for managing the emails once identified, by either deleting or quarantining them.
Two classes, get_phish_tank_urls
and get_openphish_urls
, are designed to retrieve phishing URLs from two different sources:
- PhishTank - A community-driven platform that provides verified phishing URLs.
- OpenPhish - A commercial phishing feed service.
Both classes use descriptors to fetch phishing URLs and provide a list of verified phishing URLs upon request.
This class is responsible for retrieving verified phishing URLs from PhishTank.org. It is specifically designed to be used as a descriptor in the OrcaPod class.
This method retrieves the list of verified phishing URLs from PhishTank.org by requesting a CSV file containing online valid phishing URLs.
- None: This method is invoked automatically when accessing the descriptor.
- phish_tank_list: A list of phishing URLs retrieved from PhishTank.
- HTTPError: Raised if there is an issue with the request to retrieve the CSV file from PhishTank.org.
- Logging: Logs errors and information using the
getLogger
function. - Request PhishTank Data: Sends an HTTP GET request to the PhishTank API to retrieve the phishing URL CSV.
- Error Handling: If the request fails, an
HTTPError
is raised and logged. - Data Parsing: The CSV data is processed and written to a temporary file.
- Extract URLs: The CSV data is read using
DictReader
, and the URLs are extracted and stored in a list. - File Closure: The temporary file is closed after reading.
- Return: The list of phishing URLs is returned.
This class retrieves verified phishing URLs from OpenPhish.com, a commercial phishing feed service. It is also a descriptor designed for the OrcaPod class.
This method retrieves the list of phishing URLs from OpenPhish.com by requesting a plain text feed containing phishing URLs.
- None: This method is automatically called when accessing the descriptor.
- open_phish_list: A list of phishing URLs retrieved from OpenPhish.
- HTTPError: Raised if there is an issue with the request to retrieve the phishing URL feed from OpenPhish.
- Logging: Logs errors and information using the
getLogger
function. - User-Agent Setup: Sets a custom user-agent header to simulate a request from a Windows PC.
- Request OpenPhish Data: Sends an HTTP GET request to retrieve the phishing URL feed from OpenPhish.
- Error Handling: If the request fails, an
HTTPError
is raised and logged. - Parse URLs: The text feed is split by newlines, and each entry is checked for blanks before being added to the list of phishing URLs.
- Return: The list of phishing URLs is returned.
# Assuming obj is an instance of the class containing the descriptor
phish_tank_urls = obj.phish_tank_urls
# Assuming obj is an instance of the class containing the descriptor
open_phish_urls = obj.open_phish_urls
- Both classes are designed to be used as descriptors and will retrieve phishing URLs when accessed as part of an object.
- The classes do not take any arguments for initialization but rely on accessing the API or URL directly.