Skip to content

getting-started.md

Latest commit

 

History

History
142 lines (99 loc) · 6.14 KB

getting-started.md

File metadata and controls

142 lines (99 loc) · 6.14 KB
Raw

Getting Started

This tutorial will walk you through your first ExploitHunter.app research session from start to finish. You'll set up the app, create a project, authorize a target, and run a basic recon session against the bundled Hard Juice Shop lab.

ExploitHunter has two supported ways to run:

  • Packaged desktop app: install or build the Electron package for a normal app window. It starts the same local service for you.
  • Local service: run the service yourself and open http://localhost:3210 in your OS browser. This is the default path below and the clearest mode for development.

Prerequisites

  • Node.js >= 24.0.0
  • pnpm 10.34.3 via Corepack
  • Docker and Docker Compose (v2), only for bundled labs and containerized tooling
  • Either Ollama installed locally or an OpenRouter API key (dashboard)

1. Start Everything

# Clone and enter the repo
git clone https://github.com/justsml/ExploitHunter.app.git
cd ExploitHunter.app

# Use the pinned package manager
corepack enable
corepack prepare pnpm@10.34.3 --activate

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env

Open .env and review the local defaults:

# Everything persistent lives here by default.
EXPLOIT_HUNTER_DATA_DIR=.data
SQLITE_DATABASE_URL=sqlite://.data/exploit-hunter.sqlite
MASTRA_DATABASE_URL=sqlite://.data/mastra.sqlite
LANCEDB_URI=.data/lancedb
OBJECT_STORAGE_MODE=filesystem

# Optional: leave blank to use the local Ollama fallback when available.
OPENROUTER_API_KEY=
# Or use OpenRouter:
# OPENROUTER_API_KEY=sk-or-v1-your-key-here
MODEL_DEFAULT=llm://openrouter/deepseek/deepseek-v4-flash

Start the bundled lab if you want the tutorial target, then start the app:

# Optional lab target
docker compose up -d hard-juice-shop

# Seed demo data (optional, gives you a sample project)
pnpm db:seed

# Start the app
pnpm dev

Open http://localhost:3210. If you are using a packaged Electron build instead, open the app; it launches this local service behind the desktop window.

To inspect agents, tools, memory, and traces in Mastra Studio, start it in a second terminal:

pnpm studio

Open http://localhost:4111. Studio uses a separate .data/mastra-studio-observability.duckdb file by default, allowing it to run beside the app without a DuckDB file-lock conflict. Override it independently with MASTRA_STUDIO_DUCKDB_PATH when needed.

2. Create a Project

  1. You should see the Create Project screen (or an empty project list)
  2. Click New Project and name it something like "Hard Juice Shop Recon"
  3. Enter a description: "First pass at the bundled Hard Juice Shop"
  4. Click Create

You now have a durable project with Mastra memory, artifact storage, and a dedicated lab workspace.

3. Authorize Your Target

Before Hunter can touch anything, you need to declare and authorize the target:

  1. In the project chat, send:

    I want to authorize the target http://127.0.0.1:3323 for testing

  2. Hunter should respond with a target authorization request surface
  3. Review the target details and click Approve

The target is now authorized for the project. This is deliberate: scope should live in the app's authorization ledger, not in a temporary prompt or environment variable.

4. Start Recon

Now that your target is authorized, start exploring:

Let's run a baseline HTTP probe against the Hard Juice Shop lab

Hunter will:

  1. Create a research plan with tasks
  2. Run an HTTP probe against the target
  3. Save the probe output as an artifact
  4. Index the evidence into the project's RAG memory

You'll see the plan panel update with task progress. When the probe completes, the findings surface will show what was discovered.

5. Review Evidence

  1. Click the Evidence tab in the right panel
  2. Browse the HTTP probe artifact — it includes the raw request/response
  3. Hunter may suggest next steps based on what they found

6. Explore Further

Try these prompts to explore more features:

  • Create a system map of the target's endpoints
  • Check for missing security headers
  • Run a deeper probe on the login endpoint
  • Walk me through the attack surface

Next Steps

Troubleshooting

Problem Likely Cause Fix
No projects or artifacts after moving machines .data was not copied Copy the whole .data directory or restore a tar/zip backup of it
Agent won't run probes Target not authorized or active action not approved Authorize the target in chat and approve the specific probe/action when asked
"Model not available" errors Ollama model not pulled, Ollama missing, or OpenRouter quota exhausted Run pnpm ollama:gemma4, verify Ollama is installed, or check OPENROUTER_API_KEY billing
pnpm dev fails on startup Missing .env or wrong Node version cp .env.example .env, check node --version (must be >= 24.0)
Hard Juice Shop not loading Container not started docker ps | grep juice-shop should show the lab container on port 3323
Recall quality changed after switching embeddings Existing vectors were built with another embedding identity Check .data/lancedb/thread-rag-indexes.json; re-index disk artifacts when prompted