Samurai

Language / Idioma
English | Español

Samurai : XWA submodule focused on web cybersecurity — under active development

More screenshots...

---

Overview

Samurai is a cybersecurity analysis platform with two interfaces sharing the same database:

Interface	Directory	Language	Type
Samurai Web	/frontend + /backend	Angular 22 + FastAPI/Python 3.13	Web application (100% local, SQLite by default)
Samurai TUI	/samurai-tui	Rust	Terminal application (standalone or Docker)

Capabilities

• Port Scanning — Nmap with configurable profiles (quick, balanced, deep, UDP)
• Web Reconnaissance — DNS enumeration, subdomain discovery, API probing, security headers audit, technology fingerprinting
• Vulnerability Crawling (DAST) — Page discovery, HTTP header analysis, CORS/cookie/JS-secret checks, optional SQLMap and Nuclei modules with explicit timeouts
• Database Export — Full analytics dump as JSON (raw) or AES-256-GCM encrypted binary (SAMURAI_DB_EXPORT_V1)
• History & Archive — Persistent scan storage with findings and discovered topology
• Unified API — xwa-sdk envelopes: Analysis responses and Event WebSocket streams

---

Quick Start (Local — SQLite, no Docker)

Requirements: Python 3.13 (uv recommended) and Node 24. External scanners (nmap, sqlmap, nuclei) are optional — missing binaries are reported as DEPENDENCY_MISSING instead of crashing.

# From the samurai repository root
./samurai.sh          # same as: ./samurai.sh local

The script creates backend/.venv with uv (Python 3.13), installs the local xwa-sdk binding when present, installs requirements, and starts:

Service	URL
Frontend (Angular)	http://localhost:4200
Backend (FastAPI)	http://localhost:8000 — docs at /docs
Health	http://localhost:8000/api/health
SQLite database	<repo>/samurai.db

Manual backend start

cd backend
~/.local/bin/uv venv --python 3.13 --seed .venv
.venv/bin/pip install -r requirements.txt
# Optional: local xwa-sdk binding (Event/Analysis dataclasses)
.venv/bin/pip install -e ../../xwa-sdk/bindings/python
.venv/bin/uvicorn app.main:app --port 8000

Manual frontend start

cd frontend
export PATH="$HOME/.local/share/mise/installs/node/24/bin:$PATH"
npm ci          # reproducible install from package-lock.json
npm start       # ng serve --host 0.0.0.0 --poll 2000
npm test        # Vitest via @angular/build:unit-test
npm run build   # @angular/build:application (production)

Docker (PostgreSQL)

./samurai.sh docker

Compose starts frontend, backend (DB_DRIVER=postgresql) and PostgreSQL 17 with a healthcheck. Redis and Celery are no longer part of the stack.

Cleanup (clean.sh)

./clean.sh

Kills leftover processes, removes Docker containers/volumes/images, deletes node_modules/, .venv, dist/, Python cache, .angular/ cache and the local samurai.db* files. package-lock.json is preserved.

---

Database Architecture (Dual: SQLite / PostgreSQL)

• DB_DRIVER=sqlite (default) — local file database, zero external services. SQLite is opened with check_same_thread=False plus PRAGMA foreign_keys=ON, journal_mode=WAL and busy_timeout=5000.
• DB_DRIVER=postgresql — optional; uses DATABASE_URL when set, otherwise DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASS, with pool_pre_ping=True.
• DB_PATH overrides the SQLite file location (default <repo>/samurai.db).
• wait_for_db() retries only for PostgreSQL; SQLite connects immediately.

TUI compatibility: the table schema (scans, discovered_links, findings) and the encrypted export format (SAMURAI_DB_EXPORT_V1: header + 16-byte salt + 12-byte nonce + AES-256-GCM ciphertext, PBKDF2-SHA256 600k iterations) are frozen and shared with samurai-tui. Do not change column types or the header.

WebSocket Event Protocol (xwa-sdk)

The three live endpoints (/api/scan/live, /api/vuln/live, /api/recon/live) stream JSON Event envelopes instead of plain text:

{
  "seq": 4,
  "type": "item_found",
  "tool": "samurai",
  "analysis_id": "42",
  "ts": "2026-09-12T10:00:04Z",
  "payload": {
    "kind": "open_port",
    "port": "22", "protocol": "tcp", "service": "ssh", "version": "OpenSSH 9.6",
    "severity": "info"
  }
}

Event type	Payload
analysis_started	{id, target, scan_type, profile?, modules?, timeout?}
log	{line} — one terminal line (raw nmap output included)
analysis_progress	{phase, message, data?} — e.g. contact intel with data.url/emails_count/phones_count
item_found	Finding or port: {kind:"open_port", port, protocol, service, version, severity}, {kind:"unsanitized_input", url, forms}, {kind:"reflected_input", url}
analysis_completed	{summary:{total_items, by_severity, ...}, status, scan_id, results?, ports?}
analysis_error	{error:{code, message, detail, retryable}}

seq is monotonic per connection starting at 1 and analysis_id is always the persisted scan id serialized as a string. If the optional xwa-sdk Python package is not installed, the backend emits the exact same structure via a built-in fallback.

REST API (selected)

Method	Path	Description
GET	/api/health	{status, database, version, tool} (rate-limit exempt)
GET	/api/scans, /api/scans/{id}	Legacy history endpoints (kept)
GET/DELETE	/api/analyses, /api/analyses/{id}	Unified xwa-sdk Analysis aliases
GET	/api/analyses/{id}/export?format=json|csv	Single-analysis export with Content-Disposition
GET	/api/database/export/raw	Full DB export (JSON)
POST	/api/database/export/encrypted	{"password": "..."} → AES-256-GCM binary (TUI-compatible)

Errors use the unified envelope {"error":{"code","message","detail","retryable"}}. CORS is configurable via XWA_CORS_ORIGINS (comma-separated origins or regexes; default localhost/LAN) with allow_credentials=False. In-process rate limiting defaults to 120 req/min per IP (SAMURAI_RATE_LIMIT_MAX, window SAMURAI_RATE_LIMIT_WINDOW seconds; 0 disables).

Environment Variables

Variable	Default	Purpose
DB_DRIVER	sqlite	sqlite or postgresql
DB_PATH	<repo>/samurai.db	SQLite file path
DATABASE_URL	—	PostgreSQL URL (overrides DB_* parts)
DB_HOST/DB_PORT/DB_NAME/DB_USER/DB_PASS	localhost/5432/samurai/postgres/postgres	PostgreSQL parts
XWA_CORS_ORIGINS	localhost/LAN regex	Allowed origins (comma-separated)
SAMURAI_RATE_LIMIT_MAX	120	Requests per window per IP (0 disables)
SAMURAI_RATE_LIMIT_WINDOW	60	Rate-limit window in seconds
SAMURAI_JWT_SECRET	—	Enables JWT auth + RBAC when set (POST /api/auth/login issues tokens; WebSockets take ?token=)
SAMURAI_ADMIN_PASSWORD	changeme	Admin password for /api/auth/login (role admin; analysts are read-only)

Tests

cd backend
.venv/bin/pip install -r requirements.txt -r requirements-dev.txt
.venv/bin/pip install -e ../../xwa-sdk/bindings/python   # optional but recommended
.venv/bin/pytest -q

The suite covers health/contracts, analyses CRUD + cascade, raw and encrypted exports (SAMURAI_DB_EXPORT_V1 roundtrip), parser helpers, the rate limiter, subprocess timeout helpers and the Event WebSocket shape (nmap is monkeypatched). The Angular 22 frontend ships its own Vitest suite (npm test): ApiService contracts, pure Event parsers, theme/i18n and the shared export toolbar.

---

Related Documents

Document	Description
docs/manual.md	Development and production deployment guide
docs/ui-architecture.md	Frontend feature-driven architecture specification
docs/python-libraries.md	Backend Python dependency inventory
docs/uses/dast.md	DAST vulnerability scanning usage
samurai-tui/README.md	Terminal application: installation, configuration, Docker, usage
ROADMAP.md	Development phases and milestones

---

Project Structure

samurai/
├── frontend/              # Angular 22 SPA (zoneless, core/shared/features)
│   └── src/environments/  # apiBaseUrl / wsBaseUrl (no hardcoded hosts)
├── backend/               # FastAPI Python (REST + WebSocket)
│   ├── app/
│   │   ├── main.py        # API routes, lifespan, CORS, rate limit
│   │   ├── database.py    # dual SQLite/PostgreSQL engine + PRAGMAs
│   │   ├── events.py      # xwa-sdk Event emitter (WS protocol)
│   │   ├── middleware.py  # in-process sliding-window rate limiter
│   │   ├── scanner.py     # Nmap port scanning engine
│   │   ├── crawler.py     # DAST vulnerability crawler (sqlmap/nuclei timeouts)
│   │   ├── db_exporter.py # Database export (raw + encrypted V1)
│   │   └── recon/         # Web reconnaissance modules
│   ├── tests/             # pytest suite (SQLite tmp DB)
│   └── requirements*.txt  # base / postgres / dev pins
├── samurai-tui/           # Rust terminal application (shares schema + export)
├── docs/                  # Technical documentation
├── samurai.sh             # Launcher: local (default) | docker
├── clean.sh               # Cleanup script (containers, caches, samurai.db)
└── docker-compose.yml     # frontend, backend (postgresql), postgres 17

X

& &