Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
311 lines (217 loc) · 6.55 KB

GETTING_STARTED.md

File metadata and controls

311 lines (217 loc) · 6.55 KB

Getting Started Guide

Complete step-by-step guide to get the Vulnerability Scanner running on your machine.

Prerequisites Check

Before starting, ensure you have the required software installed:

# Check Node.js (need 18+)
node --version

# Check Python (need 3.8+)
python3 --version

# Check npm
npm --version

If you're missing any, install from:

Step 1: Clone the Repository

git clone https://github.com/dev0558/vulnerability-scanner.git
cd vulnerability-scanner

Step 2: Setup Upstash Redis (Free)

  1. Go to https://upstash.com
  2. Click "Sign up" (you can use your GitHub account)
  3. Click "Create Database"
  4. Name it: scanner-queue
  5. Type: Regional
  6. Region: Choose the closest to you
  7. Click "Create"

Once created, you'll see your Redis dashboard. Copy these three values (you'll need all of them):

  • REST URL: https://xxxxx.upstash.io
  • REST Token: AXxxxxx...
  • TCP URL: rediss://default:xxxxx@xxxxx.upstash.io:6379

Save these somewhere safe - you'll use them in the next steps.

Step 3: Setup Frontend

Navigate to the frontend directory and install dependencies:

cd frontend
npm install

Create your environment file:

cp .env.local.example .env.local
nano .env.local

Add your Upstash Redis credentials:

UPSTASH_REDIS_REST_URL=https://xxxxx.upstash.io
UPSTASH_REDIS_REST_TOKEN=AXxxxxx...

Replace xxxxx with your actual Redis credentials from Upstash. Save the file with Ctrl+X, then Y, then Enter.

Verify the file was created:

cat .env.local

You should see your credentials displayed.

Step 4: Setup Worker

Go back to the project root and setup the Python worker:

cd ../worker
pip install -r requirements.txt

This installs all Python dependencies needed for the scanner.

Step 5: Start the Worker

Open a new terminal window and navigate to the worker directory:

cd ~/vulnerability-scanner/worker
export REDIS_URL="rediss://default:PASSWORD@HOST.upstash.io:6379"
python worker.py

Replace PASSWORD@HOST with your actual TCP URL credentials from Upstash.

You should see:

Worker started, waiting for jobs...

This means the worker is running and ready to process scans. Leave this terminal open.

Step 6: Start the Frontend

Open another new terminal window and start the frontend:

cd ~/vulnerability-scanner/frontend
npm run dev

You should see:

Ready in XXXms

This means the frontend is running.

Step 7: Access the Application

Open your web browser and go to:

http://localhost:3000

You should see the Vulnerability Scanner interface with a URL input field.

Step 8: Run Your First Scan

  1. In the browser, enter a test URL: https://example.com
  2. Click the "Start Scan" button
  3. Watch the worker terminal - you'll see it pick up the job
  4. Wait 10-30 seconds for the scan to complete
  5. View the results in your browser

The results will show:

  • Open ports
  • SSL/TLS certificate info
  • Security headers status
  • Server software detected
  • HTTP methods allowed

Safe Test Targets

These websites are safe and designed for testing:

Troubleshooting

Worker shows "Connection refused"

This means the worker can't connect to Redis. Check:

  1. Your Redis URL is correct
  2. URL starts with rediss:// (double 's')
  3. Password and host are copied correctly
  4. You can access upstash.com website

Try re-exporting the URL:

export REDIS_URL="rediss://default:PASSWORD@HOST.upstash.io:6379"

Frontend shows "Cannot connect to Redis"

This means the frontend can't reach Upstash. Check:

  1. .env.local file exists in frontend directory
  2. REST URL and REST Token are correct
  3. Restart the dev server: Ctrl+C then npm run dev

"Module not found" errors

Reinstall dependencies:

For frontend:

cd frontend
rm -rf node_modules
npm install
npm run dev

For worker:

cd worker
pip install -r requirements.txt
python worker.py

Frontend won't start on port 3000

Port 3000 might be in use. Try:

npm run dev -- -p 3001

Then access http://localhost:3001

Scan takes too long or times out

This could be due to:

  1. Network issues
  2. Target website is slow or blocked
  3. Firewall blocking port scans

Try scanning a different website like https://example.com

Project Structure

Once everything is running, here's what you have:

Frontend (http://localhost:3000):
- Next.js React application
- Sends scan requests to API
- Receives real-time results
- Beautiful UI with Tailwind CSS

Backend/API (part of frontend):
- Next.js API routes
- Submits jobs to Redis queue
- Retrieves results from Redis

Worker (separate process):
- Python application
- Reads jobs from Redis queue
- Performs actual security scans
- Stores results back to Redis

Redis (cloud):
- Upstash handles this
- Queues incoming scan jobs
- Stores scan results temporarily
- Manages communication between frontend and worker

Next Steps

After successfully running your first scan:

  1. Read the main README.md for more details
  2. Try scanning your own websites (if you own them)
  3. Check the PROJECT_REPORT.md for technical details
  4. Explore the code in frontend/app/page.js and worker/scanner.py
  5. Modify scans to add new security checks

Tips

  • Keep both terminals open (worker and frontend) while using the app
  • Check the worker terminal to see scan progress
  • Results are cached for 24 hours in Redis
  • You can stop either process with Ctrl+C and restart without losing data

Getting Help

If you encounter issues:

  1. Check this guide again for your specific problem
  2. Read error messages carefully - they usually tell you what's wrong
  3. Verify all credentials are copied correctly
  4. Check your internet connection
  5. Open an issue on GitHub: https://github.com/dev0558/vulnerability-scanner/issues

Common Commands Reference

# Start worker
cd ~/vulnerability-scanner/worker
export REDIS_URL="rediss://default:PASSWORD@HOST.upstash.io:6379"
python worker.py

# Start frontend (new terminal)
cd ~/vulnerability-scanner/frontend
npm run dev

# Check Node version
node --version

# Check Python version
python3 --version

# Install frontend deps
cd frontend && npm install

# Install worker deps
cd worker && pip install -r requirements.txt

# View environment variables
cat frontend/.env.local

# Stop any process
Ctrl+C

That's it! You're ready to scan. Happy testing!