SAMURAI
Automated Vulnerability Discovery & Reconnaissance Engine
A full-stack cybersecurity analysis platform combining Angular 21 on the frontend with a FastAPI backend and real-time WebSocket push — purpose-built for running concurrent nmap, SQLMap, Nuclei, and Playwright scan pipelines against target infrastructure. Every finding is classified by severity, enriched with CVSS scoring, and exported in CSV, JSON, PDF, or binary format.
System Architecture
A three-layer pipeline connecting the Angular frontend to FastAPI backend and WebSocket-driven scan engines.
The pipeline flows unidirectionally: Angular 21 issues scan requests over HTTP/2 REST to FastAPI. FastAPI validates the payload, creates a scan record in PostgreSQL, and dispatches the scan job to Celery workers over Redis. Workers execute the appropriate engine (nmap, SQLMap, Nuclei, or Playwright) via subprocess and stream progress events back through a Redis pub/sub channel. FastAPI aggregates these events and pushes them to the Angular client over a persistent WebSocket connection. Result: every port discovered, every injection tested, and every vulnerability found appears in the UI within milliseconds of detection.
Severity Indicators
Five severity levels with distinct colors and proportional weight — from critical (red, full width) to info (blue, narrow).
Severity is determined by a weighted algorithm combining CVSS 3.1 base score, exploitability metrics (attack vector, complexity, privileges required, user interaction), and contextual impact (confidentiality, integrity, availability). The final severity label maps directly to the colour coding shown above. Each severity level has a distinct hex code that is used consistently across the entire platform — from the scan results table to the export reports and the real-time dashboard widgets.
Status Badges
Text-based status indicators using the system's monospace font. No icons, no decorative elements — pure typographic signal.
background: #004400; color: #44cc44;background: #004488; color: #4488ff;background: #440000; color: #ff4444;background: #444400; color: #ffdd00;Status badges use dark-coloured backgrounds with bright text for WCAG AA compliance at small sizes (11px). The monospaced letter-spacing of 0.08em improves readability at badge scale. Each status maps to a colour that carries semantic meaning: green for success, blue for in-progress, red for failure, amber for queued. These same colours are reflected in the status bar of the live scan dashboard and the notification system.
Light Palette
Light mode swatches using the documented SAMURAI surface and text tokens for elevated-background readability.
Light mode swatches are designed for extended security audit sessions. The near-white background (#FAFAFA) reduces eye strain during long reviews while the deep navy foreground (#1A1A2E) provides maximum contrast for reading dense technical finding descriptions. The primary security red (#CC2233) is used sparingly — only for severity-critical elements, scan alert banners, and destructive action buttons — ensuring that red always commands attention when it appears.
Dark Palette
Dark mode swatches using the documented SAMURAI OLED black surface and high-contrast text tokens.
Dark mode transforms the palette for low-light security operations — pen-testing sessions, war rooms, and overnight automated scan reviews. The background deepens to near-black (#0A0A14) to eliminate glare while the foreground holds at a comfortable off-white (#E8E8F0). The security red primary is intensified to (#FF3355) for improved contrast against the dark canvas, ensuring critical-severity findings remain unmistakable. The card background (#12121E) sits one step above the page surface to create a layered elevation effect that helps distinguish content containers from the page backdrop.
Key differences between light and dark palettes centre on three tokens: <strong>background</strong> shifts from #FAFAFA to #0A0A14 (a delta of 240 points on the luminance scale), <strong>primary</strong> shifts from #CC2233 to #FF3355 (lightened to pop against dark), and <strong>card-bg</strong> inverts its relationship to the background — in light mode the card is darker than the page, in dark mode the card is lighter, creating a consistent elevation metaphor where cards always appear to sit above the page surface regardless of theme.
Typography — Space Grotesk & Space Mono
Two typefaces define the SAMURAI voice: Space Grotesk for body text and UI labels, Space Mono for data, code, and terminal output. Doto is reserved exclusively for hero moments.
SCAN REPORT
TARGET: 10.0.0.0/24
Doto is the platform display face — used exclusively for hero titles, section headers in the scan dashboard, and large-format metric readouts. Its monospaced DNA gives it a technical, authoritative feel that aligns with the security domain, while the heavy weight (900) ensures maximum impact at any viewport size.
The scan discovered 14 open ports across the target range, including 2 high-severity SQL injection vectors in the login endpoint. Further analysis with SQLMap confirmed time-based blind injection on the /api/auth endpoint, returning the database banner and user table structure within 4.2 seconds of payload delivery.
Space Grotesk serves as the primary body face across all resource pages, finding descriptions, documentation panels, and dashboard commentary. Its wide glyph aperture improves readability at small sizes, and the moderate x-height ensures clear distinction between similarly shaped characters — critical when reading IP addresses, domain names, and technical instructions.
POST /api/scan/live HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
{
"target": "10.0.0.1/32",
"engines": ["nmap", "sqlmap"],
"profile": "full-audit"
}Space Mono is the data face — used for all code blocks, terminal output, API request previews, payload representations, configuration snippets, and raw finding data. Monospaced alignment ensures that tabular data (port numbers, CVSS scores, IP octets) remains vertically aligned and scannable at a glance.
Finding Card
A compact vulnerability card showing severity, type, CVSS score, affected URL, payload evidence, and action buttons for export or detail view.
/api/users?id=1 OR 1=1' OR '1'='1The finding card above demonstrates the complete vulnerability entry format. Each finding contains: a <strong>severity</strong> header coloured by level (HIGH shown above maps to #FF8800), a <strong>type</strong> label identifying the vulnerability class (SQL Injection, XSS, LFI, RCE, etc.), a <strong>CVSS score</strong> with vector string available on the detail view, the affected <strong>URL</strong> with the vulnerable parameter highlighted, the proof-of-concept <strong>payload</strong> that triggered the detection, the vulnerable <strong>parameter</strong> name and HTTP method, and action buttons to export the single finding or navigate to its full detail page.
In the full scan results table, findings are grouped by severity with critical and high findings expanded by default. Each row can be expanded inline to reveal the full payload, request/response pair, and remediation recommendation. Findings can be bulk-selected for batch export, or individually dismissed as false positives with an auditor comment.
Border Styles
Four border variants used across the platform: standard for cards, active focus for inputs, destructive red for dangerous actions, and export gold for download controls.
Used for all standard cards, panel containers, and section wrappers throughout the platform. The border is subtle — 66% opacity of the border token — keeping the container boundary visible without competing with content. This is the baseline border applied to scan result cards, configuration panels, and dashboard widgets.
border: 1px solid color-mix(in srgb, var(--border) 66%, transparent);Applied to focused form inputs, selected scan rows in the results table, active navigation items, and any interactive element in its engaged state. The primary colour bleeds into the border at 40% to signal interactivity while maintaining enough border-token presence to avoid colour pollution across the interface.
border: 1px solid color-mix(in srgb, var(--primary) 40%, var(--border) 60%);Reserved for error states, destructive action confirmations, critical severity finding highlights, and scan failure banners. The full-saturation red border (#FF2222) immediately draws the operator's attention to the affected element. Used sparingly to preserve the signal value of red across the interface.
border: 1px solid #FF2222;Exclusive to export action buttons and premium feature indicators. The gold border (#FFD700) distinguishes export controls from standard interface elements, signalling that these actions produce downloadable artefacts. The gold accent is carried through to the exported document headers, creating visual continuity between the platform and its outputs.
border: 1px solid #FFD700;Export Actions
Gold-accented export buttons (CSV, JSON, PDF, BIN) following the system's FF D700 convention for download actions.
~4.2 kB per 100 findings~12.8 kB per 100 findings~85 kB per report~6.1 kB per 100 findingsAll export formats support both single-finding and bulk (selected or all) export. Exports are generated server-side by FastAPI using background tasks and delivered via signed download URLs valid for 24 hours. CSV and JSON are generated synchronously for small payloads, while PDF and BIN exports are queued through Celery for larger scans exceeding 1,000 findings. The gold hover state on export buttons (#FFD700) provides a consistent visual cue that these actions produce downloadable outputs.
Terminal Output
A faithful simulation of terminal-based scanning output. Green prompts, blue port numbers, grey system messages, and a blinking cursor.
The terminal emulator displays live nmap scan output streamed over WebSocket. Ports are coloured blue, open states are green, and system messages are dimmed grey to create a clear visual hierarchy that mirrors the familiar terminal experience. The blinking cursor (animated via CSS @keyframes blink) signals that the scan is actively progressing. When the scan completes, the cursor stops and the final line displays "Scan complete — 4 ports open, 3 services identified, 1 vulnerability detected." This component is used across the platform: in the live scan view, in the audit log replay, and in the embedded documentation terminal demos.
Font Weight Spectrum
Four weights create the typographic hierarchy: light (300) for secondary data, regular (400) for body, medium (500) for emphasis, and bold (700) for headings and metrics.
The quick brown fox jumps over the lazy dog near the riverbank. All 14 open ports were scanned and 3 critical vulnerabilities identified across the target range during this automated security assessment.
font-weight: 300The quick brown fox jumps over the lazy dog near the riverbank. All 14 open ports were scanned and 3 critical vulnerabilities identified across the target range during this automated security assessment.
font-weight: 400The quick brown fox jumps over the lazy dog near the riverbank. All 14 open ports were scanned and 3 critical vulnerabilities identified across the target range during this automated security assessment.
font-weight: 500The quick brown fox jumps over the lazy dog near the riverbank. All 14 open ports were scanned and 3 critical vulnerabilities identified across the target range during this automated security assessment.
font-weight: 700The font weight spectrum provides four distinct levels: <strong>Light (300)</strong> for data-dense table cells and secondary metrics where high weight would create visual noise; <strong>Regular (400)</strong> for body copy, descriptions, and paragraph content throughout the platform; <strong>Medium (500)</strong> for subheadings, navigation items, and emphasised metadata labels; and <strong>Bold (700)</strong> for section titles, severity labels, stat values, and any text requiring maximum hierarchical prominence. The weights are applied consistently across Space Grotesk (body) and Space Mono (data) faces, while Doto display text exclusively uses weight 900 for its distinctive heavy appearance.
Database Schema
Three tables with cascade delete relationships connecting scans to discovered links and findings.
The database schema follows a strict cascade-delete relationship: when a scan is deleted, all its discovered links are removed, which in turn removes all associated findings. This ensures referential integrity without orphaned records. The <code>profile</code> field in the scans table stores the scan configuration as a JSONB object — containing the selected engines, port ranges, template paths, and browser scripts — enabling full audit traceability of every scan execution. Foreign key constraints are enforced at the database level with ON DELETE CASCADE clauses, and all timestamp fields use TIMESTAMPTZ for timezone-aware storage across distributed worker deployments.
Button Patterns
Four button tiers mapped to the SAMURAI action hierarchy: primary scan, secondary export, destructive delete, and ghost cancel.
Fixed Light Mode
Button appearance under a fixed light palette (#fafaf9 background).
Fixed Dark Mode
Button appearance under a fixed dark palette (#0c0a09 background).
SVG Graphics — Monochromatic Data Display
Text-first SVG graphics that follow the SAMURAI design system: monochromatic base, dot-grid texture, Space Mono typography, and accent colours used sparingly for data content only.
Scan results table — the primary output format for port scanning. Each row shows port, state, service, and version. Findings are highlighted in the documented alert red (#D71921). Data is rendered in Space Mono.
Dot-grid security motif — the background pattern uses the documented dot-grid utility class. The overlaid panel displays a text-based scan summary with monospace typography and status colours.
Text-based progress indicators using ASCII bar charts — each engine reports completion via WebSocket. The coloured first character (#D71921, #FFD700, #4A9E5C) indicates engine status without relying on graphical fills.
Severity distribution as text-based bar chart — each severity level uses a coloured block character followed by a monospace bar and count. The format mirrors the SAMURAI terminal output convention.
SamuraiSkillPage.svgNote
Border Radius
Two radius levels define the surface language: sharp (0) for data-dense elements and subtle (2px) for interactive controls and cards.
Sharp corners (0) are reserved for data-dense elements: data tables, terminal output, code blocks, scan result grids, and finding lists where maximum content density is required. Soft corners (4px) are applied to scan cards, config panels, form inputs, sidebars, and metric tiles, providing a gentle friendliness that invites interaction. Rounded corners (8px) frame modal dialogs, dropdown menus, floating panels, and tooltip containers where the content benefits from a softer boundary. Pill rounding (999px) is exclusive to status badges, severity dots, toggle handles, avatar indicators, and count bubbles — elements that represent atomic units of identity or state.
Line Height Rhythms
Four line heights tuned to different content roles: compact for headers, data for tables, code for terminal output, and label for badges and severity markers.
A targeted security scan of 10.0.0.1/24 was executed using the full-audit profile with nmap, SQLMap, Nuclei, and Playwright engines. The scan completed in 42 seconds, discovering 14 open ports, 23 live endpoints, and 5 vulnerabilities including 1 critical SQL injection on the login endpoint with a CVSS score of 9.2.
Section headers, metric values, stat displaysA targeted security scan of 10.0.0.1/24 was executed using the full-audit profile with nmap, SQLMap, Nuclei, and Playwright engines. The scan completed in 42 seconds, discovering 14 open ports, 23 live endpoints, and 5 vulnerabilities including 1 critical SQL injection on the login endpoint with a CVSS score of 9.2.
Table cells, finding descriptions, scan resultsA targeted security scan of 10.0.0.1/24 was executed using the full-audit profile with nmap, SQLMap, Nuclei, and Playwright engines. The scan completed in 42 seconds, discovering 14 open ports, 23 live endpoints, and 5 vulnerabilities including 1 critical SQL injection on the login endpoint with a CVSS score of 9.2.
Terminal output, payload previews, config blocksA targeted security scan of 10.0.0.1/24 was executed using the full-audit profile with nmap, SQLMap, Nuclei, and Playwright engines. The scan completed in 42 seconds, discovering 14 open ports, 23 live endpoints, and 5 vulnerabilities including 1 critical SQL injection on the login endpoint with a CVSS score of 9.2.
Badges, tags, severity markers, status pillsCompact (1.2) provides tight vertical rhythm for section headers, metric values, and stat displays where every line carries weight. Data (1.4) balances readability with density for table cells, finding descriptions, and scan results where information-dense layouts require efficient use of vertical space. Code (1.6) provides comfortable spacing for terminal output, payload previews, and configuration blocks where character-level legibility is critical. Label (1.0) collapses spacing for badges, tags, severity markers, and status pills — small-format elements where visual grouping matters more than line-level readability.
API Endpoints
REST and WebSocket endpoints exposed by the FastAPI backend for scan management, live updates, and data export.
/api/scan/startRESTInitiate a new security scan against a target domain/api/scan/{id}/statusRESTRetrieve current scan status and progress percentage/api/scan/{id}/findingsRESTList all findings for a completed scan with severity filters/api/scan/{id}RESTCancel a running scan or delete a completed scan record/ws/scan/{id}/liveWebSocketReal-time stream of scan progress events and new findings/ws/dashboard/statsWebSocketLive dashboard statistics: active scans, queue depth, rateREST endpoints use standard HTTP methods (POST to create, GET to retrieve, DELETE to remove) and follow resource-oriented URL conventions. All endpoints require JWT authentication and return consistent JSON responses with appropriate HTTP status codes. Rate limiting is applied at the IP level with a default of 100 requests per minute per client.
WebSocket endpoints provide real-time bidirectional communication using the WSS protocol. The <code>/ws/scan/{id}/live</code> endpoint streams scan progress events as they happen, with a heartbeat ping every 15 seconds to maintain the connection. The <code>/ws/dashboard/stats</code> endpoint pushes aggregate statistics to all connected dashboard clients at 5-second intervals.
Color Token Application
The documented SAMURAI colour tokens mapped to their UI roles. All values reference the fixed design-tokens.md palette, independent of the global application theme.
<strong>--black (#000000)</strong> serves as the primary background for OLED displays, the terminal area, and the hero section — providing the deepest possible blacks for maximum contrast. <strong>--surface (#111111)</strong> sits one step above for elevated surfaces: card backgrounds, sidebar panels, and finding cards, creating subtle layering. <strong>--text-primary (#E8E8E8)</strong> carries all body text, section headings, finding descriptions, and table cell content in dark mode. <strong>--text-secondary (#999999)</strong> handles labels, captions, metadata, timestamps, placeholder text, and helper content.
<strong>--border-visible (#333333)</strong> draws intentional borders: card outlines, table separators, input borders, and divider lines that must be seen. <strong>--border (#222222)</strong> defines subtle dividers used decoratively — wireframe lines, section boundaries — where the border is present but should not compete with content. <strong>--accent / --error (#D71921)</strong> colours scan button fills, severity critical indicators, alert banners, and destructive actions in the signature SAMURAI red. <strong>--success (#4A9E5C)</strong> marks completed scans, passed checks, low severity indicators, and confirmation badges with a restrained green.
Spacing Scale
A disciplined 8px-based spacing scale from 2px to 96px, with semantic meaning assigned to each level: tight for belonging, medium for grouping, wide for separation, and vast for context changes.
The spacing scale follows an 8px-based system with four named levels. XS (4px, 0.25rem) handles inline gaps between badges and icon spacing — the smallest meaningful distance. SM (8px, 0.5rem) governs button groups and field-label adjacency where elements share a close relationship. MD (16px, 1rem) is the workhorse: card padding, grid gutters between sections, and the standard interior spacing of most components. LG (32px, 2rem) creates deliberate separation: section margins, hero padding, and modal interiors where content needs room to breathe. Each level is exactly double the previous one, creating a consistent geometric progression that feels natural across the interface.
--space-xs0.25rem4pxBadge gaps, icon spacing, severity dot margins--space-sm0.5rem8pxButton groups, field-label pairs, cond. action bars--space-md1rem16pxCard padding, grid gaps, section interiors--space-lg2rem32pxSection margins, hero padding, modal interiorsCVSS Score Distribution
Severity distribution metrics mapped across the 0-10 CVSS scale, showing the proportion of critical, high, medium, low, and info findings.
The CVSS distribution shows a right-skewed profile typical of automated scanning results: the majority of findings cluster in the medium-to-low range (4.0-6.9 and 0.1-3.9), with critical (9.0-10.0) and high (7.0-8.9) findings representing a smaller but more actionable subset. Info-level findings (0.0) provide contextual data without security impact. The distribution chart updates in real time as scans complete, giving operators an immediate visual summary of the current risk posture across all active and completed scans.
Scan Engine Comparison
Four integrated scan engines with their respective capabilities, protocol coverage, and performance characteristics.
nmap -sV -sC -p- -T4 target/24sqlmap -u target/api?id=1 --batch --level 3nuclei -u target.com -t cves/ -severity criticalplaywright open --browser chromium target.com/loginNmap 7.95 handles port discovery and service fingerprinting across all 65,535 TCP and UDP ports, completing a full subnet scan in under 4 minutes. SQLMap 1.8 performs automated database injection testing, supporting time-based, boolean-based, error-based, and out-of-band techniques across all major database engines. Nuclei 3.2 runs template-based vulnerability scanning against a growing library of 10,000+ community-contributed templates covering CVEs, misconfigurations, and exposed services. Playwright automates browser-based security testing: DOM injection, clickjacking, form auto-fill testing, and client-side security header validation.
Performance Benchmarks
Key performance metrics measured across different scan sizes and engine configurations.
Performance benchmarks are measured across three scan profiles: Quick Scan (nmap only, top 100 ports, single target) completes in 12-18 seconds with approximately 2 MB of memory usage per target. Standard Scan (all engines, top 1000 ports, /24 subnet) completes in 45-90 seconds with approximately 50-120 findings generated and 4 concurrent workers consuming ~120 MB. Full Audit (all engines, all ports, /16 subnet with 16 workers) scales linearly with target count and typically completes in 8-15 minutes with 500+ findings and ~500 MB total memory consumption across the worker pool.
Vulnerability Type Tags
Common vulnerability types detected by the platform, each mapped to a severity level and colour.
The platform currently identifies 28 distinct vulnerability types across 9 categories: Injection (SQL, NoSQL, Command, LDAP), XSS (Reflected, Stored, DOM-based, Blind), Server-Side (SSRF, Path Traversal, File Inclusion, Deserialization), Authentication (Brute Force, Session Fixation, Weak Password Policy, CSRF), Configuration (Default Credentials, Open Buckets, Misconfigured Headers, Directory Listing), Information Disclosure (Version Banner, Error Details, Stack Traces, Debug Endpoints), Cryptographic (Weak Cipher, Expired Certificate, Mixed Content), and Network (Open Port, DNS Zone Transfer).
Samurai's design language proves that security tools can be both information-dense and visually restrained — where every pixel earns its place.
Samurai's monochromatic design language proves that security tools can be both information-dense and visually restrained. By limiting the palette to five neutral tones and reserving colour exclusively for severity signalling, the platform achieves a clarity that helps operators focus on what matters: finding and fixing vulnerabilities. The codebase is open source and available for audit, contribution, and custom deployment.