Hastur
Analyze output of GoPhish with python to produce findings and capture credentials.
Install
git clone https://github.com/OrneLibrary/hastur
cd hastur
pip3 install -r requirements.txtUsage
usage: hastur.py [-h] [-scope abs_path] method [options ..] ...
hastur - pull information from GoPhish and request stats or beautify output
optional arguments:
-h, --help show this help message and exit
-scope abs_path specify the location of text file with IPs in scope
INPUT METHODS:
method [options ..]
csv pull information from raw data csv file
api pull information directly via GoPhish APICSV Methods Usage
usage: hastur.py csv [-h] [-f] [-dc [N]] [-ic [N]] [-il [N]] [-io [N]] [-n NAME] [-e EMAIL] [-p PASSWORDS] [-c CLICKS] phish_dump
csvparser - a method to analyze the output of the GoPhish through csv
positional arguments:
phish_dump specify the location of the csv dump from GoPhish, can be single file or directory
optional arguments:
-h, --help show this help message and exit
STATS ARGUMENTS:
specify various statistics from GoPhish
-f, --findings return information for findings
-dc [N], --domain_creds [N]
return top N email domains for users who entered credentials, default is 5
-ic [N], --ip_creds [N]
return top N remote IPs for user who entered credentials, default is 5
-il [N], --ip_click [N]
return top N remote IPs for user who clicked, default is 5
-io [N], --ip_open [N]
return top N remote IPs for user who opened email, default is 5
OUTPUT ARGUMENTS:
request credentials, user clicks, or other information for future use
-n NAME, --name NAME request a single file with emails:passwords credentials
-e EMAIL, --email EMAIL
specify a seperate file with only emails that provided credentials
-p PASSWORDS, --passwords PASSWORDS
specify a seperate file with only passwords
-c CLICKS, --clicks CLICKS
output users who clicked link to a file for future useAPI Methods Usage
usage: hastur.py api [-h] [-f] [-dc [N]] [-ic [N]] [-il [N]] [-io [N]] [-n NAME] [-e EMAIL] [-p PASSWORDS] [-c CLICKS] url api_key campaign_id
apiparser - a method to analyze the output of the GoPhish through the API
positional arguments:
url specify GoPhish server
api_key specify the API key for GoPhish
campaign_id specify the campaign ID from GoPhish
optional arguments:
-h, --help show this help message and exit
STATS ARGUMENTS:
specify various statistics from GoPhish
-f, --findings return information for findings
-dc [N], --domain_creds [N]
return top N email domains for users who entered credentials, default is 5
-ic [N], --ip_creds [N]
return top N remote IPs for user who entered credentials, default is 5
-il [N], --ip_click [N]
return top N remote IPs for user who clicked, default is 5
-io [N], --ip_open [N]
return top N remote IPs for user who opened email, default is 5
OUTPUT ARGUMENTS:
request credentials, user clicks, or other information for future use
-n NAME, --name NAME request a single file with emails:passwords credentials
-e EMAIL, --email EMAIL
specify a seperate file with only emails that provided credentials
-p PASSWORDS, --passwords PASSWORDS
specify a seperate file with only passwords
-c CLICKS, --clicks CLICKS
output users who clicked link to a file for future usePreparation
There are some preliminary steps required for the csv method and the api method.
GoPhish CSV Download Steps
In order to properly utilize hastur csv, follow the below steps to dump the CSV from GoPhish.
-
Navigate to GoPhish Server Dashboard and Click on "Campaigns."
-
Select the appropriate "Campaign." If completed with Phishing Assessment, select "Archived Campaigns". If incomplete, select "Active Campaigns."
-
Click on "Stats" (looks like a histogram) of the "Campaign."
-
Click on "Export CSV" within the "Campaign."
-
Click "Raw Events."
-
Save the CSV in the desired working directory.
API Method Preparation
In order to properly utilize
hastur api, follow the steps found here to retrieve the required campaign ID and API key.Usage Examples
Examples for usage of each method within Hastur.
CSV Usage Examples
-
Return all credentials from CSV dump file named PhishDump.csv to the command line.
$ python3 hastur.py csv PhishDump.csv Credentials: ----------------------------------------- {'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']} {'email': ['user2@mail.com'], 'password': ['password12'], 'rid': ['ze4b4H0']} {'email': ['user3@mail.com'], 'password': ['p@ssword1'], 'rid': ['o9idyZN']} {'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']} {'email': ['user4@mail.com'], 'password': ['1234567'], 'rid': ['NDjWBLS']} ----------------------------------------- -
Return in-scope credentials from CSV dump file name PhishDump.csv to the command line using scope IPs found in public_ips.txt.
$ python3 hastur.py csv PhishDump.csv -scope public_ips.txt IP 0 [IP Address1] 1 [IP Address2] 2 [IP Address3] Credentials in Scope: ----------------------------------------- {'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']} {'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']} ----------------------------------------- Full output in Scope: ----------------------------------------- {'payload': {'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']}, 'browser': {'address': 'x.x.x.x', 'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36'}} {'payload':{'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']}, 'browser': {'address': 'x.x.x.x', 'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36'}} ----------------------------------------- -
Output credentials to a file named output.txt with emails:passwords from GoPhish.
$ python3 hastur.py csv PhishDump.csv -n output.txt -
Output the findings using PhishDump.csv as the CSV dump file.
$ python3 hastur.py csv PhishDump.py -f Number of Emails Sent: 669 Number of Emails Delivered: 669 Number of Unique Clicks: 602 Click Rate (%): 89.99 Total Number of Clicks: 1052 Time to First Click (HH:MM:SS): 0:21:21.869481 Number of Unique User and Password Combinations Exploited/Submitted Data: 34 Number of Total Users Exploited/Submitted Data: 62 Length of Campaign (HH:MM:SS): 2 days, 20:32:37.902602 -
Return the top 6 email domains that entered credentials from the PhishDump.csv file.
$ python3 hastur.py csv PhishDump.csv -dc 6 count google.com 120 yahoo.com 28 aol.com 16 gmail.com 9 mail.com 4 verizon.net 4 -
Return the top 5 IP addresses for users who opened the email within the PhishDump.csv file.
python3 hastur.py csv PhishDump.csv -io count [IP Address1] 20 [IP Address2] 18 [IP Address3] 18 [IP Address4] 14 [IP Address5] 12 -
Output passwords and emails from PhishDump.csv to a file name passwords.txt and emails.txt respectively.
$ python3 hastur.py csv PhishDump.csv -e emails.txt -p passwords.txt -
Return credentials from multiple campaigns within a phish_directory directory to the terminal.
$ python3 hastur.py csv phish_directory Credentials: ----------------------------------------- {'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']} {'email': ['user2@mail.com'], 'password': ['password12'], 'rid': ['ze4b4H0']} {'email': ['user3@mail.com'], 'password': ['p@ssword1'], 'rid': ['o9idyZN']} {'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']} {'email': ['user4@mail.com'], 'password': ['1234567'], 'rid': ['NDjWBLS']} ----------------------------------------- -
Output the findings across multiple campaigns within the phish_directory.
$ python3 hastur.py csv phish_directory -f Number of Emails Sent: 2469 Number of Emails Delivered: 2469 Number of Unique Clicks: 1233 Click Rate (%): 49.94 Total Number of Clicks: 2233 Time to First Click (HH:MM:SS): 1 day, 22:25:23.496496 Number of Unique User and Password Combinations Exploited/Submitted Data: 130 Number of Total Users Exploited/Submitted Data: 273 Length of Campaign (HH:MM:SS): 2 days, 22:53:20.855733 -
Output the findings across multiple campaigns within phish_directory for IPs in scope from livehosts.
$ python3 hastur.py csv phish_directory -f -scope livehosts.txt Number of Unique Clicks: 19 Unique Click Rate (%): 11.24 Total Number of Clicks: 34 Number of Unique User and Password Combinations Exploited/Submitted Data: 12 Number of Total Users Exploited/Submitted Data: 28API Usage Examples
-
Return all credentials via API to the command line.
$ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID]
Credentials:
{'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']} {'email': ['user2@mail.com'], 'password': ['password12'], 'rid': ['ze4b4H0']} {'email': ['user3@mail.com'], 'password': ['p@ssword1'], 'rid': ['o9idyZN']} {'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']} {'email': ['user4@mail.com'], 'password': ['1234567'], 'rid': ['NDjWBLS']}
2. Return in-scope credentials from the GoPhish API to the command line using scope IPs found in public_ips.txt.$ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID] -scope public_ips.txt IP 0 [IP Address1] 1 [IP Address2] 2 [IP Address3] Credentials in Scope:
{'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']} {'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']}
Full output in Scope:
{'payload': {'email': ['user1@mail.com'], 'password': ['password1'], 'rid': ['wkwfnUG']}, 'browser': {'address': 'x.x.x.x', 'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36'}} {'payload':{'email': ['user4@mail.com'], 'password': ['123456789'], 'rid': ['NDjWBLS']}, 'browser': {'address': 'x.x.x.x', 'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36'}}
3. Output credentials to a file named output.txt with emails:passwords from GoPhish directly. $ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID] -n output.txt
4. Output the findings from a campaign through the API. $ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID] -f Number of Emails Sent: 669 Number of Emails Delivered: 669 Number of Unique Clicks: 602 Click Rate (%): 89.99 Total Number of Clicks: 1052 Time to First Click (HH:MM:SS): 0:21:21.869481 Number of Unique User and Password Combinations Exploited/Submitted Data: 34 Number of Total Users Exploited/Submitted Data: 62 Length of Campaign (HH:MM:SS): 2 days, 20:32:37.902602
5. Return the top 6 email domains that entered credentials from the API. $ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID] -dc 6 count google.com 120 yahoo.com 28 aol.com 16 gmail.com 9 mail.com 4 verizon.net 4
6. Return the top 5 IP addresses for users who opened the email through the API. $ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID] -io count [IP Address1] 20 [IP Address2] 18 [IP Address3] 18 [IP Address4] 14 [IP Address5] 12
7. Output passwords and emails to a file name passwords.txt and emails.txt respectively. $ python3 hastur.py api https://[URL][API_KEY] [CAMPAIGN_ID] -e emails.txt -p passwords.txt
## In-Scope IP Address Preparation (Optional)
In order to properly utilize ```hastur``` with the in-scope capabilities, create a txt file modeled like the below.
ScopeAddresses.txtIP x.x.x.x x.x.x.x x.x.x.x x.x.x.x
Do not use netmasks. Ensure each line is an individual address. Use [DeepOne](https://github.com/OrneLibrary/DeepOne) if necessary.
## Dependencies
Python 3.8.10
Created by: AJ Read