DEVELOPER ACCESS

Technical Documentation & API Reference

Dual-Mode Architecture

Shai-Hulud Scan is designed to run in two distinct modes, adapting to the deployment environment while maintaining core detection functionality across both Shai-Hulud 2.0 and Mini Shai-Hulud campaigns.

Dynamic Mode (Docker/Local)

  • • Backend: Next.js API Routes
  • • Database: SQLite (better-sqlite3)
  • • Search: Hybrid (BM25 + Vector)
  • • Analysis: Server-side streaming

Static Mode (GitHub Pages)

  • • Backend: None (Client-side only)
  • • Database: Pre-built JSON export
  • • Search: Client-side text filter
  • • Analysis: In-browser processing

API Reference

GET/api/search/composite
Hybrid Search

Performs a hybrid search combining BM25 keyword matching with vector-based semantic similarity.

curl "http://localhost:3000/api/search/composite?q=react&limit=5"
POST/api/analyze
SBOM Analysis

Analyzes a package-lock.json file against the Shai-Hulud database.

curl -X POST -F "file=@package-lock.json" http://localhost:3000/api/analyze

CLI Tools

The project includes powerful CLI scripts for local analysis and database management.

Check package-lock.json

npx tsx scripts/check-sqlite.ts ./package-lock.json

Rebuild Database

npm run build-db
CI/CD

Dagger Pipeline

We use Dagger to define our CI/CD pipeline as code, ensuring reproducibility across local and remote environments.

# Run full pipeline
dagger call deploy
# Scan local project
dagger call scan
# Run tests
dagger call test
Learn more about Dagger →

Tech Stack

FrameworkNext.js 16
DatabaseSQLite + Vector
StylingTailwind CSS
PipelineDagger (Go)
AI ModelXenova/all-MiniLM