Skip to content

SETUP.md

Latest commit

 

History

History
289 lines (212 loc) · 7.16 KB

SETUP.md

File metadata and controls

289 lines (212 loc) · 7.16 KB

WHOMST Setup Guide

This guide will help you set up WHOMST for investigating Twitter aliases and mapping relationships through breach data analysis.

Prerequisites

1. Install Go

Download and install Go 1.21 or later:

Verify installation:

go version
# Should output: go version go1.21.x...

2. DeHashed API Account

  1. Sign up: Visit https://www.dehashed.com/ and create an account
  2. Verify email: Complete email verification
  3. Purchase credits: Buy API credits (investigations consume credits based on results)
  4. Get API key: Navigate to your account settings to find your API key

Installation

1. Download WHOMST

# Clone the repository
git clone https://github.com/splinters-io/whomst.git
cd whomst/src

2. Install Dependencies

go mod download

3. Build the Application

go build -o whomst

Verify build:

./whomst
# Should show usage information

Configuration

1. Create Configuration File

# Copy the example configuration
cp config.yaml.example config.yaml

2. Edit Configuration

Open config.yaml in your preferred editor:

# DeHashed API Configuration
dehashed:
  email: "your-dehashed-email@example.com"    # Your DeHashed account email
  api_key: "your-dehashed-api-key-here"       # Your DeHashed API key

# Investigation Settings
investigation:
  max_depth: 2                    # Start with 2 for reasonable scope
  rate_limit_delay_ms: 1000       # 1 second between API calls

# Report Configuration (optional customization)
report:
  classification_level: "UNCLASSIFIED"
  organization: "ANTI-FRAUD INVESTIGATION UNIT"
  operation_name: "WHOMST"

3. Optional: Hashcat Integration

If you want automated password cracking capabilities:

# Add to your config.yaml
hashcat:
  enabled: true
  binary_path: "hashcat"          # or "/usr/bin/hashcat"
  wordlists:
    - "/usr/share/wordlists/rockyou.txt"
  rules:
    - "/usr/share/hashcat/rules/best64.rule"
  attack_modes:
    - "wordlist"
    - "rules"
  workload_profile: 3

Install hashcat (if desired):

First Investigation

1. Test Configuration

Run a basic investigation to test your setup:

./whomst -target testaccount

This should:

  • Load your configuration
  • Connect to DeHashed API
  • Search for "testaccount" in breach databases
  • Generate output in output/testaccount/

2. Check Output

Navigate to the output directory:

ls -la output/testaccount/

You should see:

  • report.md - Intelligence briefing
  • graph.json - Relationship data
  • visualization.html - Interactive graph
  • logic.log - Investigation log
  • hashcat/ - Password files (if hashcat enabled)

3. View Results

Open the visualization:

# macOS
open output/testaccount/visualization.html

# Linux
xdg-open output/testaccount/visualization.html

# Windows
start output/testaccount/visualization.html

Advanced Configuration

Investigation Depth Control

investigation:
  max_depth: 2              # Overall recursion depth
  max_email_depth: 3        # Specific limit for email searches
  max_ip_depth: 1           # Specific limit for IP searches
  enable_ip_recursion: true # Enable/disable IP recursion
  rate_limit_delay_ms: 1500 # Increase delay if hitting rate limits

Depth Guidelines:

  • Depth 1: Only initial Twitter results (fast, minimal credits)
  • Depth 2: Includes emails/IPs from initial results (recommended)
  • Depth 3: Deeper recursion (more comprehensive, more credits)
  • Depth 4+: Very deep recursion (expensive, potentially slow)

Rate Limiting

Adjust based on your DeHashed plan:

  • Basic plan: 1000-2000ms recommended
  • Premium plan: 500-1000ms may be acceptable
  • Monitor: Check DeHashed dashboard for rate limit violations

Troubleshooting

Configuration Issues

"Failed to load config"

# Check YAML syntax
cat config.yaml | head -20

# Verify file exists
ls -la config.yaml

# Check permissions
chmod 644 config.yaml

"DeHashed email and API key are required"

  • Ensure both fields are filled in config.yaml
  • Remove any extra quotes or spaces
  • Verify API key is correct from DeHashed dashboard

API Issues

"API error (status 401)"

  • Double-check email and API key in DeHashed dashboard
  • Ensure account is verified and active
  • Try logging into DeHashed web interface to verify credentials

"API error (status 403)"

"Rate limit exceeded"

  • Increase rate_limit_delay_ms in config
  • Wait before retrying
  • Consider reducing investigation depth

Investigation Issues

"Username not found in Twitter breach database"

  • This is expected behavior - tool only investigates accounts from the 2022 Twitter breach
  • The 2022 Twitter breach is the required entry point for all investigations
  • Try a different target that may exist in the 2022 Twitter breach database
  • Tool will not proceed without this initial Twitter breach match

No results/empty output

  • Check that target exists in any breach database
  • Verify API credits weren't exhausted
  • Review logic.log for investigation flow details

Performance Issues

Investigation taking too long

  • Reduce max_depth setting
  • Increase rate_limit_delay_ms
  • Check system resources and network connectivity

High credit consumption

  • Start with max_depth: 1 for testing
  • Monitor credit usage in DeHashed dashboard
  • Consider using separate depth limits for emails vs IPs

Security Considerations

Configuration Security

# Protect your config file
chmod 600 config.yaml

# Don't commit config with real credentials
git update-index --skip-worktree config.yaml

Investigation Ethics

  • Authorization: Only investigate accounts you're authorized to research
  • Legal compliance: Follow all applicable laws and regulations
  • Data handling: Securely handle any breach data discovered
  • Documentation: Maintain proper investigation documentation

Getting Help

  1. Check logs: Review logic.log in output directories
  2. Verify config: Double-check config.yaml syntax and values
  3. API status: Check DeHashed service status and account standing
  4. Documentation: Review README.md for detailed usage information

Next Steps

Once setup is complete:

  1. Practice: Run investigations on fictional test accounts
  2. Tune settings: Adjust depth and rate limits based on your needs
  3. Explore output: Familiarize yourself with report formats and visualizations
  4. Plan investigations: Develop systematic approaches for your use cases

Remember: Always ensure proper authorization before investigating any accounts, and comply with all applicable laws and regulations.