Overview

SocPuppet is a tool developed with the task of aiding SOC analysts with automating part of their workflow. One of the goals of SocPuppet is to perform as many of the routine checks as possible, allowing the analyst more time to spend on deeper analysis within the same time-frame. Details for many of SocPuppet's features can be found below.

This tool is a fork of the Sooty tool developed by TheresAFewConors.

Current Features
Requirements & Installation
SocPuppetAI
Development
Changelog
Roadmap

SocPuppet can currently:

Sanitize URL's to be safe for sending emails.
Perform reverse DNS and DNS lookups.
Perform reputation checks:
- Hashes:
  - VirusTotal - API Key Required
  - Malware Bazzar
- Domain and IP:
  - Reverse DNS
  - DNS Lookup
  - ThreatFox
  - URLScan.io - API Key Required
  - InternetDB
  - WhoIs
  - GreyNoise - API Key Required
  - Shodan - API Key Required
  - IP-API
  - inQuest - Labs
Decode:
- ProofPoint URLs.
- UTF-8 Encoded URLs.
- Office SafeLink URLs.
- Base64 Strings.
- Cisco7 Passwords.
Email:
- Analyze Email Information (Perform Reputation Checks)
Unshorten URL's that have been shortened by external services. (Limited to 10 requests per hour).
Unfurl URLs via the CLI version of Unfurl.

└── Main Menu
   ├── Sanitize URL's for use in emails
   |  └── URL Sanitizing Tool
   ├── Reputation Check
   |  └── Perform a check against IPs, Domains, or Hashes
   ├── Decoders
   |   ├── ProofPoint Decoder
   |   ├── URL Decoder
   |   ├── Office Safelinks Decoder
   |   ├── URL Unshortener
   |   ├── Base 64 Decoder
   |   ├── Cisco Password 7 Decoder
   |   └── Unfurl URL
   ├── Email
   |   └── Analyze Email
   ├── API (Requires API keys)
   |   ├── URLScan.io lookup
   |   ├── VirusTotal lookup
   |   ├── GreyNoise lookup
   |   └── Shodan lookup
   ├── Lookup Tools
   |   ├── Bitcoin Address
   |   ├── Bitcoin Transaction Tracer
   |   ├── Reverse DNS Lookup
   |   ├── DNS Lookup
   |   └── WhoIs Lookup
   ├── Extra's
   |   ├── InternetDB (Free Shodan)
   |   ├── IP-API (IP Geo Location, rate limited without a key)
   |   ├── Malware Bazaar (Abuse.ch)
   |   ├── SocPuppetAI - Experimental, uses [GPT4All](https://github.com/nomic-ai/gpt4all)
   |   ├── inQuest (limited queries without API)
   |   └── ThreatFox
   └── Exit

Requirements and Installation

Python 3.x
Install all dependencies from the requirements.txt file. pip install -r requirements.txt
Launch the tool by navigating to the main directory, and executing with python SocPuppet.py, or simply SocPuppet.py
Several API Keys are required to have full functionality with SocPuppet. However, it will still function without these keys, just without the added functionality they provide. Links are found below:
API keys are set via environment variables listed below:
- GreyNoise - GREYNOISE_API_KEY
- Shodan.io - SHODAN_API_KEY
- URL Scan - URLSCAN_IO_API_KEY
- VirusTotal - VT_API_TOKEN

Launch with Docker

docker build -t sooty . && docker run --rm -it sooty

SocPuppetAI - Experimental

This is an experimental implementation of GPT4All by Nomic AI.

With the current implementation, the tool automatically attempts to download the ggml-wizardLB-7B.q4_2 model. This particular model is based on Llama 7b and trained by Microsoft and Peking University. The ggml-wizardLB-7B.q4_2 is 4GB in size and will take up 4GB of RAM during execution. During testing, I've observed that this model appears to been better a summarizing findings that other models supplied by the organziation. That said, you can check out available models on their official GPT4All website and use them here. You will have to modify the self._gpt = gpt4all.GPT4all("ggml-wizardLM-7B.q4_2") line of code to match the model you wish to use.

The AI runs completely on your CPU which may take some time to give you a response in comparison to ChatGPT.

Due to this being a completely experimental model, you may or may not receive an expected output. In many cases, you may not even receive a response. That said

Commands

All commands must end with eof at this time, this does include the data you are pushing for the SocPuppet to analyse.

`clear_context`

This command will clear the context memory that is fed back into the AI model

`exit_gpt`

This command will exit the SocPuppetAI.

`show_context`

This command will give you the raw context array of what is being fed into the AI

Development

Want to contribute? Great!

Code Contributions

If you wish to work on a feature, leave a comment on the issue page and I will assign you to it.
Under the projects tab is a list of features that are waiting to be started / completed.
All code modifications, enhancements or additions must be done through a pull request.
Once reviewed and merged, contributors will be added to the ReadMe.

Found a Bug? Show Me!

Bugs and Issues

If an issue / bug is found, please open a ticket in the issue tracker and use the bug report template. Fill in this template and include any additional relevant information.
If you wish to work on a known bug, leave a comment on the issue page and open a Pull Request to track progress. I will assign you to it.
If there is an issue with installation or usage, use the supplied template and I will respond ASAP.

Changelog

Check the CHANGELOG.md file.

Roadmap

This is an outline of what features may be coming in future versions. You can see the current SocPuppet project items on the Projects site.

Version 1.2 - The Phishing Update

Scan email attachments for malicious content, macros, files, scan hashes, etc.
Ability to analyze an email, retrieve emails, urls and extract info from headers.
Extract IPs from body of an email.
Perform reputation checks on the sender of email and provide enriched information.

Version 1.3 - The Templating Update

Add dynamic email templates that generate based on SocPuppet's analysis.
Verify MX Records
Perform DKIM Verification

Version 1.4 - The PCAP Analysis Update

Add ability to analyze .pcap files and provide concise, enriched information.

Version 1.x - The Case Update

Add a 'New Case' Feature, allowing output of the tool to be output to a txt file.

j4ckd4n/SocPuppet