SpearHead Reference

The system is composed of five specialized agents that run in sequence, each feeding results into the next phase:

No Python, Node.js, or Neo4j installation required. Just Docker Desktop.

$ git clone https://github.com/ismaellaya/SpearAI.git
$ cd SpearAI
$ cp .env.example .env
# Edit .env — set GEMINI_API_KEY or adjust OLLAMA_BASE_URL
$ docker compose up --build

Open http://localhost:3000 once the three services are running. See the Docker Compose section below for full details, Ollama tips, and runtime key management.

Requires Python 3.10+, Node.js 20+, and Docker Desktop already installed. The scripts start Neo4j via Docker Compose, activate the virtualenv, run the FastAPI backend, and launch the Next.js dev server.

$ git clone https://github.com/ismaellaya/SpearAI.git
$ cd SpearAI
$ cp .env.example .env
# Install Python dependencies (first time only)
$ python -m venv .venv
$ source .venv/bin/activate   # Linux / macOS
$ .venv\Scripts\activate      # Windows PowerShell
$ pip install -r requirements.txt
# Install dashboard dependencies (first time only)
$ cd dashboard && npm install && cd ..
# Run everything
$ chmod +x run_dashboard.sh && ./run_dashboard.sh   # Linux / macOS
$ .\run_dashboard.ps1                               # Windows PowerShell

Only Docker Desktop (Mac/Windows) or Docker Engine + Compose v2 (Linux) is required. No Python, Node.js, or Neo4j installation needed on the host.

$ git clone https://github.com/ismaellaya/SpearAI.git
$ cd SpearAI
$ cp .env.example .env

Open .env and set at least one LLM provider. For Gemini (recommended for first run):

LLM_PROVIDER=gemini
GEMINI_API_KEY=your_key_here

# First run builds images (~5 min). Subsequent starts are instant.
$ docker compose up --build
# Run in the background
$ docker compose up --build -d

All three services start together. The backend connects to Neo4j automatically once it is ready (typically within ~60 seconds of first startup). You will see logs from all three services interleaved in the terminal.

On first visit, the Setup Screen will appear asking you to select a use case (Academic, Red Team, etc.). This choice is stored in .env automatically.

You do not need to edit .env before every key change. Open the dashboard → Settings panel → OSINT Tools, enter the key and click Save. The backend writes it to .env immediately and picks it up on the next pipeline run — no container restart needed.

# Starts Neo4j at bolt://localhost:7687
# Web UI at http://localhost:7474
$ docker-compose up -d

Default credentials: neo4j / changeme (set in .env).

1. 1Enable Deep Search (the "Deep" button in the sidebar turns amber when active).
2. 2Add context in parentheses after the target name using natural language — avoid commas as they are used to separate targets. Example: "John Smith (CTO at Acme Corp based in Madrid)".
3. 3Fill the Engagement Context panel with the target organisation's known domains.
4. 4Run in Full mode. The pipeline creates a Person node in Neo4j with high-confidence properties.

Once the node exists in Neo4j, right-click it in the graph and launch a new pipeline directly from the context menu. On this second pass:

• ›The ProfilerAgent sees existing node properties and discards entities that contradict the established profile.
• ›Re-running with Deep Search adds more OSINT depth without duplicating existing confident nodes.

Right-click any node → Annotate to mark it with one of three statuses:

Annotations are stored as Neo4j node properties and persist across runs. They help the LLM on future executions by providing a curated, validated context.

Add context in parentheses directly in the target field. The more specific, the better:

The scope_notes field in the Engagement Context panel is injected into the ProfilerAgent prompt. Use it to explicitly rule out categories:

# Example scope notes
Target is the CTO of Acme Corp Madrid — discard any results
related to sports, music, or other industries. Focus only
on software engineering and corporate leadership.

Use the confidence filter in the graph toolbar (ALL / MED+ / HIGH) to hide low-confidence nodes during review. Person nodes are always shown regardless of the filter. Switch to HIGH first to inspect the reliable core, then expand to ALL to review edge cases.

• +WHOIS lookup — registrant org, registrar, creation/expiry dates
• +DNS enumeration — MX records reveal email provider (Google Workspace / M365 / custom), TXT records expose SPF + DMARC policy
• +crt.sh Certificate Transparency — subdomain discovery, cert issuer
• +HIBP domain breach check — free lookup of corporate email domain against known breaches
• +Org-scoped DuckDuckGo search — "target name" site:domain.com for confirmed association evidence
• +Email pattern inference — ProfilerAgent derives first.last@domain, flast@domain patterns from DNS + confirmed Email nodes

• ›Edit Node — update properties directly from the dashboard
• ›Annotate Node — set confirmed / false_positive / needs_review status with optional notes and tags
• ›Generate Email — runs AttackAgent + ReviewerAgent using this node's Neo4j neighbourhood as RAG context
• ›Delete Node — removes the node and all its relationships
• ›Right-click on canvas background — opens Add Node picker to manually insert a new entity

Export the current graph (FileDown → GEXF) before clearing the database. GEXF files can be opened directly in Gephi for offline analysis. Then use Clean DB in Settings → Danger Zone (requires confirmation) to start fresh.

Before passing to the LLM summarizer, _deduplicate_sources() applies:

• +Max 3 results per domain (prevents link-farm flooding)
• +Snippet prefix dedup (first 80 chars) removes near-duplicates
• +Hard cap: 50 sources total
• +Apify sources (image_url) and HIBP breach entries (DATA_BREACH) are always preserved, exempt from caps

When known org domains are present in the Engagement Context, ProfilerAgent automatically infers email address patterns by cross-referencing confirmed Email nodes against each domain and scoring format candidates:

Inferred patterns are stored as Email nodes with the property inferred_pattern: true for visual distinction in the graph.

Before calling the LLM, all OSINT data is sanitized against a blocklist of prompt injection patterns (</s>, <|system|>,[INST], ###, etc.). Blocked patterns are stripped silently so the injection attempt is defused without halting the pipeline.

AttackAgent queries Neo4j for the target's 1-hop neighbors:

MATCH (p:Person {name: $name})-[r]-(neighbor)
RETURN type(r), labels(neighbor), neighbor.name, neighbor.source_context
LIMIT 25

Retrieved neighbors (organizations, education, topics, usernames) are injected into the system prompt as structured context. This grounds the generated email in verifiable facts about the target rather than generic templates.

Score range: 0 (obvious spam) to 10 (would likely bypass detection):

API keys can be updated without restarting the backend. Open the dashboard Settings panel (gear icon in the sidebar) and expand the OSINT Tools section. Keys are saved to .env via POST /config/tools and take effect immediately. Use the Test button to verify each key before running a scan.

1. 1Fill the Engagement Context panel: org name, type (Corporation), known email domains, scope notes referencing the SoW number.
2. 2Add employee names as batch targets — use hints like "Alice Johnson (IT Helpdesk)" to help the LLM disambiguate common names.
3. 3Run in full mode with 3 variations to generate Authority, Rapport, and Opportunity angle emails for each target.
4. 4Review results in the Compare pane — sort by Reviewer score to prioritize the most convincing simulations.
5. 5Export as HTML report (Pro) or JSON for evidence documentation.
6. 6Test top emails against your email gateway (Proofpoint, Mimecast) to measure detection rate.

1. 1Run the pipeline on public personas related to your industry (e.g., public LinkedIn profiles of CISOs at peer companies).
2. 2Export phishing emails from View Results — copy the raw email body or use the JSON export.
3. 3Import into your phishing simulation platform (GoPhish, KnowBe4) as custom email templates.
4. 4Use the Reviewer critique text as ground truth for what features make an email convincing — build detection rules targeting those features.
5. 5Export the knowledge graph as GEXF to visualize organizational attack surface in Gephi.

1. 1Add employee names as batch targets (up to 10 at a time). The system processes them sequentially.
2. 2Run in full mode — each email is personalized to the individual's public professional profile.
3. 3Review scores in the results panel. Lower-scoring emails may need manual refinement before deployment.
4. 4Use generated emails in your authorized simulated phishing platform.
5. 5Include the Reviewer critique in post-campaign follow-up training materials to explain exactly what made the email convincing.

Click the FileDown icon in the toolbar to export:

The toolbar confidence control (ALL / MED+ / HIGH) hides low-confidence inferred nodes. Person nodes are always shown regardless of confidence. Useful for cleaning up cluttered graphs from large batch runs.

Useful Cypher queries you can paste into POST /run-query or the dashboard's Query panel:

-- Get full profile of a person
MATCH (p:Person {name: "Alice Smith"})-[r]-(n)
RETURN p, type(r) AS rel, n

-- Find all inferred email addresses
MATCH (p:Person)-[:HAS_EMAIL]->(e:Email)
WHERE e.inferred_pattern IS NOT NULL
RETURN p.name AS person, e.name AS email, e.inferred_pattern AS pattern
ORDER BY person

-- List all companies with their employees
MATCH (p:Person)-[:WORKS_AT]->(c:Company)
RETURN c.name AS company, collect(p.name) AS employees
ORDER BY size(employees) DESC

-- Export high-confidence nodes only
MATCH (p:Person)-[r]-(n)
WHERE n.confidence IS NOT NULL
  AND ANY(v IN values(apoc.convert.fromJsonMap(n.confidence)) WHERE v = "High")
RETURN p.name, type(r), n.name, labels(n)