Nullsec Documentation

Nullsec is an AI-powered security analysis platform that audits websites, codebases, and MCP servers. It combines deterministic static analysis with LLM-assisted code reasoning to catch vulnerabilities that pattern-based scanners miss — then generates actionable fix prompts and automated pull requests.

47
Security Checks
21+
Secret Patterns
9
Web Modules
5
MCP Modules
ℹNullsec is a first-layer automated audit. It is not a substitute for a professional penetration test. The absence of a finding does not guarantee the absence of a vulnerability.

System Architecture

Nullsec is a distributed system with clear separation between the user-facing application, the scanning engine, the analysis pipeline, and the patch generation layer.

Client (Browser)Next.js 15 App (Vercel)API Routes · Pages · Auth · Badge EndpointBullMQ (Upstash Redis)Worker (Railway)Web Scanner9 modulesCode Scannersecrets·deps·AIMCP Scanner5 modulesPatcherdet.·AI·diffAnalysis PipelineDedup · Contextualize (Claude) · Score · ReportSupabase (PG)Claude APIGitHub APIOSV.dev APIReport · Badge · PR · Fix Prompts
Fig. 1 — Nullsec system architecture

Scan Pipeline

Every scan follows the same multi-stage pipeline. Stages run in sequence, with progress events emitted to the client via Supabase Realtime at each transition.

SUBMITvalidateQUEUEBullMQSCANweb · codemcp · secretsdeps · configANALYZEdedup · scorecontextualizeREPORTgrade + badgeFIXpatches · PR~100ms~200ms30-120s5-15s~500ms3-20sTotal: ~2-4 minutes per full audit
Fig. 2 — Scan pipeline stages with typical timing

Web Surface Scanner

The web scanner probes a live URL across 9 isolated check modules. Each module is an async function that returns findings and never crashes the scan — failures are caught, logged, and reported as "could not complete."

Target URLGROUP 1 — FETCH (parallel)headerstlscookiescorserrorsredirectsGROUP 2 — PATH PROBE (sequential, 200ms delay)paths (30+ sensitive paths)GROUP 3 — PLAYWRIGHT (single browser)javascript (18+ scripts)mixed-content
Fig. 3 — Web scanner execution groups and concurrency model

Code Scanner

The code scanner analyzes a repository's source for vulnerabilities invisible from the web surface. It downloads the repo as a tarball, runs analysis in a temporary sandbox, and deletes all source after completion.

Tarball download→Extract (≤100MB)→Secret scan→Dep audit→Config review→AI analysis→Delete temp

File Priority for AI Analysis

Not all files are equal. The scanner prioritizes by vulnerability likelihood:

Route handlersP1 — highestMiddleware / authP2Agent / AI codeP3Database modelsP4Config filesP5Utilities / helpersP6 — lowest
Fig. 4 — File priority ranking for AI analysis selection (max 50 files)

Secret Detection Engine

The secret detection engine combines 21+ provider-specific regex patterns with Shannon entropy analysis to identify credentials that are hardcoded, committed to git history, or bundled into client-side JavaScript.

Shannon Entropy Formula

H(X) = - Σ p(xᵢ) · log₂ p(xᵢ)Strings with H > 4.5 bits/char assigned to key-like variables are flagged as potential secrets

The entropy analysis catches generic high-entropy strings that don't match a known provider pattern — custom API keys, generated tokens, and obfuscated credentials. It runs on variables matching *_KEY, *_SECRET, *_TOKEN, *PASSWORD*, and *_CREDENTIAL*.

Redaction Policy

Matched secrets are always redacted in storage, output, and display. Only the first 4 and last 4 characters are retained:

sk_live_••••••••••••4xQ2
AKIA••••••••••••B7VX
ghp_••••••••••••••••k9Mn

Dependency Audit

The dependency scanner parses manifests and lockfiles across four ecosystems, then batch-queries the OSV.dev vulnerability database.

npmpackage.jsonPythonrequirements.txtRustCargo.tomlGogo.modOSV.dev Batch APIfree · no auth · all ecosystems
Fig. 5 — Dependency audit: manifests parsed, versions extracted, batch-queried against OSV.dev

AI Code Analysis Pipeline

The AI layer sends prioritized source files to Claude for security-focused reasoning. It identifies vulnerability classes that pattern-based scanners structurally cannot detect — broken access control, insecure business logic, confused-deputy attacks, and architectural auth gaps.

Analysis Decision Tree

Code chunk (≤6K tok)Claude Sonnet AnalysisZod Schema Validation✓ Valid → Accept findings✗ Invalid → Retry (1x)Re-validateAcceptDrop + log
Fig. 6 — AI analysis retry/fallback decision tree. Findings are never invented.

Token Cost Model

Cscan = nchunks × (Tin × Pin + Tout × Pout) + CsynthesisTypical: 5 chunks × (~8K in + ~2K out) + synthesis ≈ $0.28 per full scan

MCP Server Verification

Dedicated verification for Model Context Protocol servers — the tool layer connecting AI models to external capabilities. The scanner inventories tools, classifies capabilities, and analyzes confused-deputy attack surfaces.

Capability Classification

LOW RISKHIGH RISKRread_onlyWwriteNnetworkFfilesystemDdatabase$wallet!shellMITIGATION-AWARETools with guardrails (allowedDirectories, validatePath, read-only connections) areclassified as MITIGATED rather than DANGEROUS. The scanner does not cry wolf.
Fig. 7 — MCP tool capability risk spectrum with mitigation-aware classification

Scoring Formula

The security score is computed deterministically — by code, never by the AI model — ensuring reproducible, auditable results.

Score Computation

S = Σc∈C max(0, Wc - Σf∈Fc D(f))S = total score, C = categories, W = category weight, F = findings in category, D = severity deduction

Category Weight Distribution

100max scoreSecrets20 ptsCode Vulnerabilities20 ptsDependencies15 ptsHTTP Headers15 ptsTLS / SSL10 ptsConfiguration10 ptsInfrastructure10 pts
Fig. 8 — Category weight distribution (total: 100 points)

Severity Deduction Matrix

CRITICAL-15 to -25 pointsHIGH-8 to -15 pointsMEDIUM-3 to -8 pointsLOW-1 to -3INFO0
Fig. 9 — Severity deduction ranges per finding

Hard Override Rules

⛔
Any critical finding → score capped at 40 (Grade F)
Any exposed live secret → score capped at 55 (Grade D)
A codebase with perfect headers and TLS but a committed database password is not a B — it's an F.

Grade Thresholds

FDCBAA+05570809097100
Fig. 10 — Grade threshold scale

Severity Model

Findings are classified by the intersection of exploitability and impact:

EXPLOITABILITY →IMPACT →MEDIUMHigh impact, hard to exploitCRITICALHigh impact, easy to exploitLOWLow impact, hard to exploitHIGHLow impact, easy to exploitor high impact, moderateSQLiexposed secretmissing HSTSIDORserver header
Fig. 11 — Severity classification matrix: exploitability × impact

Fix Prompt Generation

Every finding generates a copy-pasteable prompt for Claude, Cursor, or any AI coding tool. The loop: AI writes code → Nullsec finds the bug → fix prompt → AI fixes it → re-scan.

Prompt Requirements

  • Specific — exact file and line number
  • Descriptive — vulnerability explained precisely
  • Instructive — tells the AI exactly what to change
  • Constrained — specifies what NOT to change
  • Self-contained — works standalone, no references to other findings

Auto-Fix Security PRs

Connect a GitHub repo, scan it, generate minimal patches, and open a pull request — all human-supervised.

Connect GitHub→Scan repo→Classify fixability→Generate patches→Review diffs→Create PR
⛔Nullsec never merges its own PRs. No merge API call exists anywhere in the codebase. The PR is opened; you review and merge on your terms.

Patch Generation Pipeline

TIER 1: DeterministicTemplate-based, no AI neededheaders · .gitignore · cookiesTIER 2: AI-GeneratedClaude with tight constraintssecrets · CORS · rate limitingTIER 3: Not FixableReport only — needs humancomplex SQLi · IDOR · archSAFETY VALIDATION≤50 lines changed · syntax valid · risk classified · Zod-validated · diff computed
Fig. 12 — Three-tier patch generation with safety validation gate

Safety Rails

RailEnforcement
No auto-mergeNo merge API call exists. PRs are opened, never merged.
Patch size limitReject if > 50 lines changed in one file
PR file limitReject if > 5 files touched
Syntax validationEvery patched file parsed for validity before proposal
Risk labelingAuth/session/payment patches marked HIGH RISK
Commit pinningPatches target the exact commit SHA scanned
PR rate limitMax 3 PRs per repo per day
AI validationZod schema, 1 retry, then drop. No invented patches.
Token encryptionAES-256-GCM at rest. App private key in env only.
Audit trailEvery generation, accept, reject, and PR creation logged

Security Reports

Reports are private by default. Publishing generates a shareable URL and enables the trust badge. Dismissed findings are struck through, never deleted — and the score never changes on dismissal.

Trust Badges

Dynamic SVG served from the Nullsec domain. Cannot be forged. Supports dark/light themes. Expires after 90 days (Standard) or 180 days (Priority). MCP servers display "MCP Verified."

<!-- Embed on your site or README -->
<a href="https://app.trynullsec.com/r/a8f3x">
  <img src="https://app.trynullsec.com/api/badge/a8f3x.svg" />
</a>

Plans & Pricing

Surface ScanFull Audit ($79)Priority ($199)
URL scan✓✓✓
GitHub scan—✓✓
AI code analysis—50 files, 6K tok/chunk100 files, 12K tok/chunk
FindingsTop 5AllAll
Fix prompts—✓✓
Auto-fix PRs—✓✓
Badge validity—90 days180 days
Re-scan——1 included (30d)
PDF export—✓✓

Quick Start

CLI (nullsec-guard)

# Scan the current directory — no accounts, no cloud
npx nullsec-guard

# Enable AI-powered deep analysis
export ANTHROPIC_API_KEY=sk-ant-...
npx nullsec-guard

# Get copy-pasteable fix prompts for Claude / Cursor
npx nullsec-guard --fix-prompts

# CI/CD — fail the build on high+ findings
npx nullsec-guard --ci --fail-on high

CLI: nullsec-guard

Open-source CLI. No accounts, no cloud. npmjs.com/package/nullsec-guard

npx nullsec-guard [path] [options]

  --json            JSON to stdout
  --markdown        Save .md report
  --sarif           SARIF 2.1.0 for GitHub
  --fix-prompts     Copy-paste fix prompts
  --no-ai           Skip AI (no API key needed)
  --ci              Exit non-zero on findings
  --fail-on <sev>   Threshold (low|medium|high|critical)
  --mcp             Force MCP analysis

API Reference

MethodEndpointDescription
POST/api/scansCreate and enqueue a scan
GET/api/scans/:idScan status + report
PATCH/api/scans/:id/publicToggle public/private
GET/api/scans/:id/pdfPDF export
GET/api/reposConnected GitHub repos
POST/api/repos/:id/scanScan a connected repo
POST/api/repos/:id/patches/generateGenerate patches
PATCH/api/patches/:idAccept/reject patch
POST/api/repos/:id/prCreate PR
GET/api/badge/:badgeIdDynamic SVG badge

Privacy & Data Handling

  • Zero source code retention. Repos are cloned, analyzed, and deleted. Only redacted findings persist.
  • Secrets always redacted. First 4 + last 4 characters only.
  • Without AI: fully local. No network calls except OSV.dev.
  • With AI:code snippets sent to Anthropic's API. Not the full repo.
  • No telemetry in CLI. No analytics, no tracking.
  • GitHub tokens AES-256-GCM encrypted at rest.

Known Limitations

  • Static analysis only — no runtime testing. Can produce false positives.
  • AI is probabilistic — can miss issues, can flag safe code. Human review required.
  • Documentation false positives — example credentials in docs may be flagged. Dismissal is available.
  • Lockfile preferred for dependency accuracy. Falls back to manifest ranges.
  • bun.lockb not supported (binary format).
  • Max scan depth: 200 files, 100 MB, 10 directory levels.
  • Not a penetration test. Automated first-layer audit only.
@trynullsectrynullsec.comt.me/trynullsecGitHubnpm

© 2026 Nullsec