ThreatHunt/QUICKSTART.md

Quick Start Guide

This guide will help you get VelociCompanion up and running in minutes.

Prerequisites

• Docker and Docker Compose installed
• 8GB RAM minimum
• Ports 3000, 5432, and 8000 available

Step 1: Start the Application

# Clone the repository
git clone https://github.com/mblanke/ThreatHunt.git
cd ThreatHunt

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

Expected output:

NAME                COMMAND                  SERVICE             STATUS              PORTS
threathunt-backend-1   "sh -c 'alembic upgr…"   backend             running             0.0.0.0:8000->8000/tcp
threathunt-db-1        "docker-entrypoint.s…"   db                  running             0.0.0.0:5432->5432/tcp
threathunt-frontend-1  "docker-entrypoint.s…"   frontend            running             0.0.0.0:3000->3000/tcp

Step 2: Verify Backend is Running

# Check backend health
curl http://localhost:8000/health

# Expected response:
# {"status":"healthy"}

# View API documentation
open http://localhost:8000/docs

Step 3: Access the Frontend

Open your browser and navigate to:

http://localhost:3000

You should see the VelociCompanion login page.

Step 4: Create Your First User

Option A: Via API (using curl)

# Register a new user
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "role": "admin"
  }'

# Login to get a token
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

Option B: Via Frontend

1. The first time you access the app, you'll need to register via API first (as shown above)
2. Then login through the frontend at http://localhost:3000/login

Step 5: Explore the API

Use the interactive API documentation at:

http://localhost:8000/docs

Click "Authorize" and enter your token in the format:

Bearer YOUR_TOKEN_HERE

Step 6: Test the API

Run the test script to verify all endpoints:

./test_api.sh

Expected output:

===================================
VelociCompanion API Test Script
===================================

1. Testing health endpoint...
✓ Health check passed

2. Registering a new user...
✓ User registration successful

3. Logging in...
✓ Login successful

4. Getting current user profile...
✓ Profile retrieval successful

5. Listing tenants...
✓ Tenants list retrieved

6. Listing hosts...
Hosts: []

7. Testing authentication protection...
✓ Authentication protection working

===================================
API Testing Complete!
===================================

Common Operations

Create a Host

# Get your token from login
TOKEN="your_token_here"

# Create a host
curl -X POST http://localhost:8000/api/hosts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "workstation-01",
    "ip_address": "192.168.1.100",
    "os": "Windows 10"
  }'

List Hosts

curl -X GET http://localhost:8000/api/hosts \
  -H "Authorization: Bearer $TOKEN"

Ingest Data

curl -X POST http://localhost:8000/api/ingestion/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "server-01",
    "data": {
      "artifact": "Windows.System.TaskScheduler",
      "results": [...]
    }
  }'

Troubleshooting

Database Connection Issues

# Check if database is running
docker-compose logs db

# Restart database
docker-compose restart db

Backend Not Starting

# Check backend logs
docker-compose logs backend

# Common issues:
# - Database not ready: Wait a few seconds and check logs
# - Port 8000 in use: Stop other services using that port

Frontend Not Loading

# Check frontend logs
docker-compose logs frontend

# Rebuild frontend if needed
docker-compose build frontend
docker-compose up -d frontend

Reset Everything

# Stop and remove all containers and volumes
docker-compose down -v

# Start fresh
docker-compose up -d

Next Steps

1. Create Additional Users: Use the /api/auth/register endpoint
2. Set Up Tenants: Create tenants via /api/tenants (admin only)
3. Integrate with Velociraptor: Configure Velociraptor to send data to /api/ingestion/ingest
4. Explore Cases: Create and manage threat hunting cases
5. Configure VirusTotal: Set up VirusTotal API integration for hash lookups

Security Considerations

⚠️ Before deploying to production:

1. Change the SECRET_KEY in docker-compose.yml or .env file

   • Must be at least 32 characters
   • Use a cryptographically random string

2. Use strong passwords for the database

3. Enable HTTPS/TLS for API and frontend

4. Configure proper firewall rules

5. Review and update CORS settings in backend/app/main.py

Development Mode

To run in development mode with hot reload:

# Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend (in another terminal)
cd frontend
npm install
npm start

Support

• Documentation: See README.md
• API Docs: http://localhost:8000/docs
• Issues: GitHub Issues