OSRFramework

OSRFramework is a comprehensive open-source intelligence (OSINT) framework designed for performing reconnaissance operations. It enables security professionals to gather information about usernames, email addresses, domains, and digital identities across multiple online sources in a structured and automated manner.

Installation

Linux Installation

# Clone the repository
git clone https://github.com/i3visio/osrframework.git
cd osrframework

# Install dependencies
pip3 install -r requirements.txt

# Install the package
pip3 install .

# Verify installation
osrframework --version

macOS Installation

# Install using Homebrew (if available)
brew install osrframework

# Or via pip3
pip3 install osrframework

# Verify
osrframework --version

Windows Installation

# Install via pip
pip install osrframework

# Verify installation
osrframework --version
python -m osrframework --version

Docker Installation

# Build Docker image
docker build -t osrframework .

# Run in container
docker run -it osrframework bash

Core Components

Main Tools

Tool	Purpose
usufy.py	Username enumeration across platforms
mailfy.py	Email account discovery and verification
domainfy.py	Domain and subdomain reconnaissance
phonefy.py	Phone number OSINT and reverse lookup
searchfy.py	Search query automation across engines

Supporting Tools

Tool	Purpose
hash-osint	Hash identifier and lookup
ip-osint	IP address reconnaissance
uri-osint	URI pattern analysis

Usufy - Username Enumeration

Basic Username Search

# Search for username across all platforms
usufy.py -u john.doe

# Search multiple usernames
usufy.py -u john.doe -u jane.smith -u admin

# Search with specific output file
usufy.py -u john.doe -o username_results.txt

Platform-Specific Searches

# Search only on Twitter
usufy.py -u john.doe -p twitter

# Search on multiple platforms
usufy.py -u john.doe -p twitter,github,linkedin

# List available platforms
usufy.py --list-platforms

Custom Platform Configuration

# Use custom platform list
usufy.py -u john.doe -p twitter,facebook,instagram,reddit

# Specify custom configuration file
usufy.py -u john.doe -c custom_platforms.cfg

Verbose and Debug Output

# Verbose output
usufy.py -u john.doe -v

# Debug mode with detailed logging
usufy.py -u john.doe -d

# Quiet mode (minimal output)
usufy.py -u john.doe -q

Batch Username Enumeration

# Read usernames from file
usufy.py -f usernames.txt

# Process with custom timeout
usufy.py -f usernames.txt -t 10

# Combine multiple input files
usufy.py -f file1.txt -f file2.txt -o batch_results.txt

Mailfy - Email Discovery

Basic Email Enumeration

# Search for email addresses
mailfy.py -m john.doe@example.com

# Search multiple emails
mailfy.py -m john@example.com -m jane@example.com

# Search by username pattern
mailfy.py -u john.doe -e @gmail.com

Domain-Based Email Discovery

# Find emails for specific domain
mailfy.py -d example.com

# Find emails with multiple domains
mailfy.py -d example.com -d company.org

# Generate email patterns
mailfy.py -u john.doe -d example.com --generate-patterns

Email Validation

# Verify email existence
mailfy.py -m john.doe@example.com --verify

# Check email deliverability
mailfy.py -m john.doe@example.com --check-deliverable

# Bulk email verification
mailfy.py -f emails.txt --verify-all

Email Breach Checking

# Check if email in breach database
mailfy.py -m john.doe@example.com --check-breaches

# Detailed breach information
mailfy.py -m john.doe@example.com --check-breaches -v

# Check multiple emails for breaches
mailfy.py -f emails.txt --check-breaches

Domainfy - Domain Reconnaissance

Domain Information Gathering

# Get domain information
domainfy.py -d example.com

# Get multiple domains
domainfy.py -d example.com -d company.org

# Check domain availability
domainfy.py -d example.com --check-availability

Subdomain Discovery

# Find subdomains
domainfy.py -d example.com --find-subdomains

# Deep subdomain enumeration
domainfy.py -d example.com --recursive --depth 2

# Export subdomain list
domainfy.py -d example.com --find-subdomains -o subdomains.txt

DNS Record Enumeration

# Get DNS records
domainfy.py -d example.com --dns-records

# Check specific record types
domainfy.py -d example.com --record-types MX,NS,A,CNAME

# Full DNS enumeration
domainfy.py -d example.com --dns-enumeration

Domain Reputation Check

# Check domain reputation
domainfy.py -d example.com --reputation

# Malware/phishing check
domainfy.py -d example.com --check-malware

# Detailed reputation report
domainfy.py -d example.com --reputation -v

Phonefy - Phone Number OSINT

Phone Number Lookup

# Search phone number
phonefy.py -p "+1-555-123-4567"

# Multiple phone numbers
phonefy.py -p "+1-555-123-4567" -p "+44-20-7946-0958"

# Format variations
phonefy.py -p "5551234567" -p "+1 555 123 4567"

Phone Number Validation

# Validate phone number format
phonefy.py -p "+1-555-123-4567" --validate

# Check carrier information
phonefy.py -p "+1-555-123-4567" --carrier-info

# Get location information
phonefy.py -p "+1-555-123-4567" --location-info

Bulk Phone Number Processing

# Process phone numbers from file
phonefy.py -f phone_numbers.txt

# Combined with validation
phonefy.py -f phone_numbers.txt --validate -o results.txt

Searchfy - Search Query Automation

Multi-Engine Searches

# Search across engines
searchfy.py -q "john doe security researcher"

# Specific search engine
searchfy.py -q "admin credentials" --engine google

# Multiple search engines
searchfy.py -q "vulnerability disclosure" --engines google,bing,duckduckgo

Dork-Based Searching

# Google dork search
searchfy.py -q 'filetype:pdf site:example.com'

# GitHub dork
searchfy.py -q 'path:config password' --engine github

# Custom dork patterns
searchfy.py --dork-file dorks.txt

Result Filtering

# Filter results by keyword
searchfy.py -q "example.com" --filter "admin"

# Limit result count
searchfy.py -q "security conference" --max-results 50

# Export results
searchfy.py -q "vulnerability" --export results.json

Advanced Reconnaissance

Combined Multi-Tool Workflow

# Username + Email discovery
usufy.py -u john.doe | mailfy.py --from-usufy

# Domain + Email enumeration
domainfy.py -d example.com | mailfy.py --from-domainfy

# Phone + Reverse lookup
phonefy.py -p "+1-555-123-4567" | searchfy.py --from-phonefy

Output Formats

# JSON output
usufy.py -u john.doe -o results.json --format json

# CSV output
mailfy.py -m john@example.com -o results.csv --format csv

# HTML report
domainfy.py -d example.com -o report.html --format html

# XML output
phonefy.py -f numbers.txt -o results.xml --format xml

Data Correlation

# Correlate findings across tools
osrframework correlate \
  --usufy results_users.json \
  --mailfy results_emails.json \
  --domainfy results_domains.json \
  --output correlated_results.json

# Detailed correlation report
osrframework correlate \
  --input results/ \
  --verbose \
  --html-report

Authentication and API Keys

Configure API Keys

# Set up API keys for enhanced functionality
osrframework configure

# Add specific API key
osrframework config --set SHODAN_API_KEY "your_key_here"

# Add Twitter API credentials
osrframework config --set TWITTER_API_KEY "key"
osrframework config --set TWITTER_API_SECRET "secret"

Free vs. Premium Searches

# Use only free sources
usufy.py -u john.doe --free-only

# Enable premium features with API keys
mailfy.py -m john@example.com --use-premium

# Check available API keys
osrframework config --list-keys

Performance Optimization

Threading and Rate Limiting

# Adjust thread count
usufy.py -u john.doe --threads 10

# Set request delay
mailfy.py -m john@example.com --delay 2

# Rate limiting
domainfy.py -d example.com --rps 5

Timeout Configuration

# Set connection timeout
usufy.py -u john.doe --timeout 30

# Set socket timeout
mailfy.py -m john@example.com --socket-timeout 15

# Retry logic
phonefy.py -p "+1-555-123-4567" --retries 3

Large-Scale Operations

# Process large datasets efficiently
usufy.py -f large_usernames.txt \
  --threads 20 \
  --delay 0.5 \
  --timeout 45 \
  -o results.json

# Distributed processing
osrframework distributed \
  --input-file huge_list.txt \
  --workers 4 \
  --tool usufy

Filtering and Refinement

Result Filtering

# Filter for active accounts only
usufy.py -u john.doe --filter active

# Show only verified results
mailfy.py -m john@example.com --verified-only

# Confidence-based filtering
domainfy.py -d example.com --min-confidence 80

Custom Filters

# Filter by response code
usufy.py -u john.doe --response-codes 200,301

# Filter by keyword in results
mailfy.py -m john@example.com --contains "verified"

# Exclude results
phonefy.py -p "+1-555-123-4567" --exclude-spam

Reporting and Export

Generate Reports

# HTML report
usufy.py -u john.doe -o john_doe_report.html --report-format html

# JSON report
mailfy.py -m john@example.com --json-report email_report.json

# CSV export
domainfy.py -d example.com --csv-export domain_data.csv

# Excel report (if supported)
phonefy.py -f phones.txt --excel-report phone_report.xlsx

Multi-Format Output

# Export to multiple formats simultaneously
usufy.py -u john.doe \
  --json results.json \
  --csv results.csv \
  --html results.html

# Detailed markdown report
osrframework report \
  --input findings/ \
  --format markdown \
  --output findings.md

Troubleshooting

Connection Issues

# Test connectivity
osrframework test-connection

# Verbose network debugging
usufy.py -u john.doe -v --debug-network

# Proxy configuration
usufy.py -u john.doe --proxy http://proxy.example.com:8080

API Issues

# Test API key validity
osrframework test-api-keys

# Check rate limits
osrframework check-rate-limits

# Reset API configuration
osrframework config --reset

Performance Issues

# Monitor resource usage
osrframework monitor

# Reduce load
usufy.py -u john.doe --threads 2 --delay 5

# Memory optimization
mailfy.py -m john@example.com --memory-efficient

Best Practices

Pre-Assessment Planning

• Define clear intelligence objectives
• Identify target entities (usernames, domains, emails)
• Document all findings and sources
• Maintain ethical standards throughout
• Verify information accuracy through multiple sources

Efficient Reconnaissance

# Structured multi-stage approach
# 1. Initial username search
usufy.py -u target_user -o stage1_users.json

# 2. Email discovery from results
mailfy.py -d discovered_domain.com -o stage2_emails.json

# 3. Domain reconnaissance
domainfy.py -d discovered_domain.com -o stage3_domains.json

# 4. Correlate findings
osrframework correlate --input stage*.json --output final_report.json

Data Management

# Organize results by timestamp
mkdir -p osint_results/$(date +%Y%m%d)

# Store comprehensive logs
osrframework verbose --all \
  --logfile osint_results/$(date +%Y%m%d)/osrfw.log

# Archive results
tar -czf osint_$(date +%Y%m%d).tar.gz osint_results/

Legal and Ethical Considerations

OSRFramework should only be used:

• For authorized security assessments
• During legitimate reconnaissance phases
• With proper scope documentation
• In compliance with applicable laws
• Respecting platform terms of service

Always maintain:

• Written authorization before testing
• Detailed logs of all activities
• Clear documentation of methodology
• Professional ethical standards
• Confidentiality of sensitive findings

Resources

• Official GitHub: https://github.com/i3visio/osrframework
• Documentation: https://osrframework.readthedocs.io/
• OSINT methodology guides
• Platform-specific research resources
• Legal/ethical OSINT guidelines