TorScan Quick Start Guide

Prerequisites

• Docker and Docker Compose installed
• Basic understanding of command line operations
• At least 4GB of RAM available

5-Minute Setup

1. Clone and Configure

# Clone the repository
git clone <repository-url>
cd torscan

# Create your configuration
cp .env.example .env

# Edit the .env file - IMPORTANT: Change these values!
nano .env

• SECRET_KEY: Generate a random string
• MONGODB_PASSWORD: Set a strong password
• ELASTICSEARCH_PASSWORD: Set a strong password
• FLASK_DEBUG: Set to False for production

2. Start TorScan

# Start all services
docker-compose up -d

# Check that services are running
docker-compose ps

• Web Dashboard: http://localhost:5000
• MongoDB: localhost:27017
• Elasticsearch: localhost:9200
• Redis: localhost:6379

3. Initial Login

1. Navigate to http://localhost:5000
2. Login with default credentials:
   • Username: admin
   • Password: admin123
3. Change the password immediately!

Your First Scan

Step 1: Add Target Sites

# Example .onion sites to scan
- http://example1.onion
- http://example2.onion
- http://example3.onion

Step 2: Define Search Patterns

[
  "keyword1",
  "company-name",
  "email@example.com",
  "bitcoin:.*",
  "specific phrase"
]

Step 3: Run a Manual Scan

1. Go to the Dashboard
2. Click "New Scan"
3. Select your sources and targets
4. Click "Start Scan"
5. Monitor progress in real-time

Step 4: View Results

1. Navigate to "Scan Results"
2. Click on your completed scan
3. Review matches with context
4. Export results as JSON or CSV

Setting Up Scheduled Scans

Create a Daily Scan

1. Go to "Scheduled Scans"
2. Click "New Schedule"
3. Configure:
   • Name: "Daily Dark Web Monitor"
   • Schedule Type: "Cron"
   • Cron Expression: 0 2 * * * (runs at 2 AM daily)
   • Select sources and targets
4. Save and enable

Schedule Types Available

• Cron: Use cron expressions for complex schedules
• Interval: Simple recurring intervals (e.g., every 6 hours)
• One-time: Single execution at a specific date/time

Advanced Features

Full-Text Search

1. Navigate to "Advanced Search"
2. Use search operators:
   • keyword - Basic search
   • "exact phrase" - Exact match
   • keyword1 AND keyword2 - Boolean logic
   • bitcoin~ - Fuzzy matching
3. Apply filters:
   • Date range
   • Confidence score
   • Source domain

Plugin Management

1. Go to "Plugins" section
2. Available plugin types:
   • Crawlers: Custom site crawling logic
   • Matchers: Advanced pattern matching
   • Exporters: Custom export formats
   • Notifiers: Alerts and notifications
3. Upload or configure plugins as needed

Threat Intelligence Integration

# MISP Configuration
MISP_URL=https://your-misp-instance.com
MISP_KEY=your-api-key
MISP_VERIFYCERT=True

# OpenCTI Configuration
OPENCTI_URL=https://your-opencti-instance.com
OPENCTI_TOKEN=your-api-token

API Usage

Authentication

# Get API token from dashboard
curl -X POST http://localhost:5000/api/login   -H "Content-Type: application/json"   -d '{"username":"admin","password":"your-password"}'

Start a Scan

curl -X POST http://localhost:5000/api/scan   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{
    "sources": ["http://example.onion"],
    "targets": ["keyword1", "keyword2"]
  }'

Search Results

curl -X GET "http://localhost:5000/api/search?q=bitcoin&limit=10"   -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

Security

1. Change default passwords immediately
2. Use environment variables for sensitive configuration
3. Enable HTTPS for production deployments
4. Regularly update Docker images and dependencies
5. Monitor logs for suspicious activity

Performance

1. Limit concurrent scans to avoid overloading Tor circuits
2. Use pagination for large result sets
3. Schedule scans during off-peak hours
4. Monitor resource usage with docker stats

Responsible Use

• Only scan sites you have authorization to monitor
• Respect robots.txt and rate limits
• Use for legitimate security research only
• Comply with all applicable laws and regulations

Troubleshooting

Common Issues

# Check logs
docker-compose logs -f

# Restart services
docker-compose restart

# Check Tor status
docker-compose exec tor-proxy tor-resolve check.torproject.org

# Restart Tor
docker-compose restart tor-proxy

# Rebuild Elasticsearch index
docker-compose exec web python scripts/reindex.py

• Check logs: docker-compose logs [service-name]
• Dashboard logs: /logs endpoint when debug is enabled
• Configuration issues: Verify .env file settings
• Permission errors: Ensure proper file ownership

Next Steps

1. Customize patterns in config/targets.json for your use case
2. Set up notifications using the plugin system
3. Integrate with your SIEM using the API
4. Create custom plugins for specialized monitoring
5. Enable threat intelligence feeds for enhanced detection