Documentation

SafeWeave Documentation

Everything you need to set up SafeWeave and start scanning your code for security vulnerabilities. 8 specialized scanners, one MCP command.

Version 1.0 · Last updated March 2026

Quick Start

Get up and running in under 30 seconds. No account, no API key, no Docker required.

1

Run one command

Start scanning immediately with npx -- no install needed:
terminal
npx safeweave-mcp

This starts the SafeWeave MCP server locally. SAST, Secrets, and Dependency scanning are free -- no account required.

2

Connect your AI coding tool

Add SafeWeave to your editor. See IDE Integration for all editors, or use this quick setup:
Claude Code (one command)
claude mcp add safeweave -- npx -y safeweave-mcp
Cursor / VS Code / Windsurf (.mcp.json)
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"]
    }
  }
}
3

Ask your AI to scan

Tell your AI assistant: "Scan this project for security vulnerabilities" -- SafeWeave handles the rest.
terminal
$ Ask your AI: "Scan this project for security issues"
Connecting to SafeWeave MCP server...
Running 8 scanners in parallel...
SAST2 findings(1 high, 1 medium)
Secrets1 finding(1 critical)
Dependencies3 findings(1 high, 2 medium)
IaC0 findings
Container1 finding(1 medium)
DAST0 findings
License0 findings
Posturepassed
Score: 89/100 7 findings (1 critical, 2 high, 3 medium, 1 low)

Tip

After adding the config, restart your editor or reload the MCP server list. Verify the connection by asking your AI: "What SafeWeave tools are available?"

Architecture

SafeWeave runs as a set of microservices — one gateway and 8 specialized scanners. The gateway exposes an MCP server that your AI coding tool connects to. When you request a scan, the gateway routes your request to the appropriate scanners, runs them in parallel, and returns aggregated results.

Platform Architecture

Clients

Cursor
VS Code
Claude Code
Windsurf
Warp
CLI / cURL
MCP / HTTP
Gateway

:9000

MCP Server
Profile Engine
License Client
HTTP

8 Scanners

SAST:9001Semgrep
Dependencies:9002npm/pip/cargo audit
Secrets:9003Gitleaks
IaC:9004Trivy
Container:9005Trivy
DAST:9006Nuclei
License:9007license-checker
Posture:9008Custom checks

Scan Flow

1

User prompt

"Scan this project"

2

MCP call

scan_project tool

3

Gateway

Route to scanners

4

Parallel scan

8 scanners run

5

Results

Findings returned

Gateway

MCP server + REST API. Orchestrates scanners, manages profiles, validates licenses, and aggregates results.

Scanners

8 isolated microservices, each running a specialized security tool. They communicate with the gateway over HTTP.

License Server

Validates license keys, enforces plan-level feature gating, and tracks usage for billing.

MCP Server Setup

SafeWeave uses the Model Context Protocol (MCP) -- an open standard that lets AI assistants call external tools. Your AI coding tool connects to SafeWeave's MCP server and gains access to security scanning tools.

Self-Hosted Configuration (recommended)

Run SafeWeave locally with npx safeweave-mcp. No Docker, no API keys needed for free-tier scanning.

MCP configuration (stdio)
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"]
    }
  }
}

Free tier: SAST, Secrets, and Dependency scanning. No account required.

Self-Hosted Pro Configuration

Unlock all 8 scanners + compliance profiles by adding your license key. Still runs entirely on your machine -- only license verification is remote.

MCP configuration (Self-Hosted Pro)
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"],
      "env": {
        "SAFEWEAVE_LICENSE_KEY": "sw_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cloud Configuration

Cloud and Team plans connect to hosted infrastructure. Replace YOUR_LICENSE_KEY with the key from your dashboard settings.

MCP configuration (Cloud)
{
  "mcpServers": {
    "safeweave": {
      "url": "https://api.safeweave.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LICENSE_KEY"
      }
    }
  }
}

How to upgrade from Free to Pro

1

Create an account and get your license key.

2

Go to Upgrade and subscribe to Self-Hosted Pro ($15/mo).

3

Add your license key to your MCP config as SAFEWEAVE_LICENSE_KEY. Restart your editor.

ℹ️ Note

Self-Hosted = runs entirely on your machine via npx safeweave-mcp. Your code never leaves your machine.
Cloud = we host everything. Code is transmitted over TLS for scanning and is never stored.

What happens after setup

  • SafeWeave registers security scanning tools your AI assistant can call
  • Free tier: SAST, dependency, and secrets scans. Pro: all 8 scanners with compliance profiles
  • Results are returned inline in your conversation -- no context switching
  • Scan history and trends appear in your cloud dashboard (Cloud/Team plans)

IDE Integration

Step-by-step setup for each supported editor using npx safeweave-mcp. No Docker or API keys needed for free-tier scanning.

Claude Code (CLI)

1

Run one command to add SafeWeave:

terminal
claude mcp add safeweave -- npx -y safeweave-mcp
2

Start a new Claude Code session. SafeWeave tools will be loaded automatically.

Tip

For Self-Hosted Pro, add the license key via config file instead. Create or edit .mcp.json in your project root:
.mcp.json (project root, Pro users)
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"],
      "env": {
        "SAFEWEAVE_LICENSE_KEY": "sw_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

1

Open Cursor and go to Settings MCP, or edit the config file directly:

~/.cursor/mcp.json
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"]
    }
  }
}
2

Restart Cursor. You should see SafeWeave tools in your MCP tool list.

VS Code + GitHub Copilot

1

Create .vscode/mcp.json in your workspace:

.vscode/mcp.json
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"]
    }
  }
}
2

Reload VS Code window (Cmd+Shift+P Reload Window).

3

Open Copilot Chat and ask it to scan your project. SafeWeave tools will appear in the tool list.

Windsurf

1

Edit your Windsurf MCP config file:

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"]
    }
  }
}
2

Restart Windsurf to load SafeWeave tools.

Warp Terminal

1

Open Warp Settings → MCP Servers → Add Server.

2

Configure the server with SSE transport:

Warp MCP config
{
  "mcpServers": {
    "safeweave": {
      "command": "npx",
      "args": ["-y", "safeweave-mcp"]
    }
  }
}
3

Restart Warp. SafeWeave tools will appear in the AI assistant.

All 8 Scanners

SafeWeave includes 8 specialized security scanners. Each runs as an isolated microservice. All 8 scanners run in parallel — average scan time is 12 seconds.

SAST — Static Application Security Testing

self-hostedPowered by Semgrep

Analyzes your source code for security vulnerabilities without executing it. Detects OWASP Top 10 issues including injection flaws, XSS, broken authentication, cryptography misuse, and more.

What it detects

  • SQL injection, command injection
  • Cross-site scripting (XSS)
  • Broken authentication patterns
  • Insecure cryptography usage
  • Hardcoded credentials

Supported languages

  • TypeScript, JavaScript, Python, Go
  • Java, Ruby, PHP, Rust, C/C#

Plan details

self-hosted Included free

Secrets — Credential Detection

self-hostedPowered by Gitleaks

Scans your codebase for accidentally committed secrets, API keys, passwords, tokens, and private keys. All findings are marked as CRITICAL severity (CWE-798).

What it detects

  • AWS access keys, GCP service accounts
  • API keys and tokens (Stripe, Twilio, etc.)
  • Database connection strings
  • Private key files (RSA, SSH)
  • OAuth / JWT tokens

Plan details

self-hosted Included free

Dependencies — Vulnerability Auditing

self-hostednpm/pip/cargo/go/bundle audit

Audits your project dependencies for known CVEs across 5 package ecosystems. Detects vulnerable versions and suggests upgrades.

Supported ecosystems

  • npm — package-lock.json
  • pip — requirements.txt
  • cargo — Cargo.lock
  • go — go.sum
  • bundle — Gemfile.lock

Features

  • Auto-detects ecosystem from lockfiles
  • CVSS score-based severity mapping
  • License compliance checking
  • Configurable CVSS thresholds per profile

IaC — Infrastructure as Code

self-hosted-proPowered by Trivy

Scans Terraform, CloudFormation, Kubernetes manifests, and Dockerfiles for security misconfigurations.

  • Missing encryption, open security groups, overly permissive IAM policies
  • Kubernetes pod security issues, missing resource limits
  • Dockerfile best practice violations

Container — Image Scanning

self-hosted-proPowered by Trivy

Scans container images and OS packages for known CVEs. Reports vulnerable versions and suggests fixed versions.

  • Base image vulnerabilities, OS package CVEs
  • Installed vs fixed version comparison
  • Automatic upgrade suggestions

DAST — Dynamic Application Security Testing

self-hosted-proPowered by Nuclei

Tests running web applications for vulnerabilities by sending real HTTP requests. Requires a target URL.

  • SQL injection, reflected/stored XSS, SSRF
  • Open redirects, missing security headers
  • Default credentials, known service vulnerabilities

License — License Compliance

self-hosted-prolicense-checker / pip-licenses

Checks your dependency tree for copyleft or restricted licenses that may conflict with your project's licensing.

  • Detects GPL-3.0, AGPL-3.0, and other copyleft licenses
  • Supports npm and Python ecosystems
  • Customizable blocked license list via profiles

Posture — API Security Posture

self-hosted-proCustom pattern checks

Analyzes your server code for 12 API security best practices including authentication, rate limiting, CORS, and more.

Check IDDescriptionCWE
POSTURE-001Missing authentication middleware
POSTURE-002No rate limitingCWE-770
POSTURE-003Missing security headers
POSTURE-004No request body size limit
POSTURE-005CORS wildcard (*) configurationCWE-346
POSTURE-006Missing CSRF protectionCWE-352
POSTURE-007Plain HTTP without TLSCWE-319
POSTURE-008Detailed error messages exposedCWE-209
POSTURE-009No request logging / audit trailCWE-778
POSTURE-010Unsafe JSON.parse without try-catchCWE-502
POSTURE-011Server binds to 0.0.0.0CWE-668
POSTURE-012No input validation libraryCWE-20

MCP Tools Reference

When connected, SafeWeave exposes 12 tools your AI assistant can call. You don't need to call these directly — just ask your AI in natural language.

ToolDescriptionParameters
scan_fileScan a single file for vulnerabilitiesfile_path (string)
scan_projectRun full security scan on entire projectdirectory (string, optional)
scan_dependenciesAudit dependencies for known CVEsdirectory (string, optional)
get_findingsRetrieve scan findings with filtersseverity (enum), file (string)
set_profileSwitch active compliance profileprofile (enum)
get_security_scoreGet overall security posture scoredirectory (string, optional)
suggest_fixGet remediation for a specific findingfinding_id (string)
scan_iacScan infrastructure-as-code filesdirectory (string, optional)
check_containerScan container images for CVEsdirectory (string, optional)
check_licenseCheck license compliancedirectory (string, optional)
dast_checkRun dynamic security testingdirectory, target_url (string)
check_postureCheck API security posturedirectory (string, optional)

Example prompts

"Scan this project for security issues"

calls scan_project

"Check my dependencies for vulnerabilities"

calls scan_dependencies

"Are there any secrets in my code?"

calls scan_file / scan_project

"Switch to SOC 2 compliance profile"

calls set_profile

"What's my security score?"

calls get_security_score

"How do I fix finding X?"

calls suggest_fix

"Run DAST against localhost:3000"

calls dast_check

"Check my API for security posture"

calls check_posture

MCP Resources (read-only)

URIDescription
safeweave://profilesList all available compliance profiles
safeweave://findings/summarySummary of current scan findings
safeweave://configCurrent gateway configuration
safeweave://compliance/{profile}Details for a specific compliance profile

Compliance Profiles

Profiles control which scanners run, what rules are enforced, and severity thresholds. Switch profiles with: "Switch to SOC 2 profile"

Standard

Default

Balanced security for most projects. Covers the most common vulnerability classes.

Scanners

SAST, Dependencies, Secrets

Rules

OWASP Top 10

Severity threshold

Error: high, Warn: medium

Hardened

Stricter rules for security-sensitive applications. Blocks AGPL-3.0 licensed dependencies.

Scanners

SAST, Dependencies, Secrets

Rules

OWASP Top 10, crypto best practices, auth best practices, enforce-tls-1.2, no-eval, no-dynamic-require

Severity threshold

Error: medium, Warn: low

OWASP

OWASP-focused profile with DAST testing for web applications.

Scanners

SAST, Dependencies, Secrets, IaC, DAST

Rules

Full OWASP Top 10, injection, XSS, SSRF, broken access control

Severity threshold

Error: high, Warn: medium

SOC 2

Compliance

Designed for SOC 2 Type II compliance. Requires non-root containers and low CVSS threshold (5.0).

Scanners

SAST, Dependencies, Secrets, Container, IaC

Rules

Enforce TLS, audit logging, session timeout, no hardcoded credentials

Severity threshold

Error: medium, Warn: low

PCI-DSS

Compliance

Payment Card Industry compliance. Blocks latest base images, requires non-root containers, CVSS threshold 4.0.

Scanners

SAST, Dependencies, Secrets, Container, IaC

Rules

Enforce TLS, no weak ciphers, no plaintext PAN, input validation, audit logging

Severity threshold

Error: medium, Warn: low

HIPAA

Compliance

Healthcare data compliance. Focused on protecting PHI with encryption and access control requirements.

Scanners

SAST, Dependencies, Secrets, Container, IaC

Rules

Enforce TLS, encryption at rest, no PHI in logs, audit logging, access control, session timeout

Severity threshold

Error: medium, Warn: low

Custom Profiles

Extend any built-in profile with a .safeweave/profile.yaml file in your project root:

.safeweave/profile.yaml
extends: standard
rules:
  sast:
    custom_rules:
      - enforce-tls-1.2-minimum
      - no-eval
  dependencies:
    blocked_licenses:
      - GPL-3.0
      - AGPL-3.0
    max_cvss: 5.0

API Reference

You can call the SafeWeave API directly for CI/CD integration or custom tooling.

Authentication

All API requests require your license key as a Bearer token:

cURL example
curl https://api.safeweave.dev/api/scan \
  -H "Authorization: Bearer YOUR_LICENSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scanners": ["sast", "deps", "secrets"],
    "files": {
      "app.js": "const password = \"admin123\";"
    }
  }'

Endpoints

MethodEndpointDescription
POST/api/scanRun a scan with specified scanners and files
GET/api/healthCheck gateway and scanner health status
GET/api/scannersList all available scanners and their status
POST/api/authAuthenticate and receive a session token
POST/api/registerCreate a new account
GET/api/customer/licenseGet license info, plan, and status
GET/api/customer/scansList scan history (paginated)
GET/api/customer/trendsGet security trends over time
GET/api/customer/scoreGet overall security score (0-100)

Base URL: https://api.safeweave.dev

Response format

Scan response example (JSON)
{
  "score": 89,
  "findings": [
    {
      "id": "sast-001",
      "scanner": "sast",
      "severity": "high",
      "title": "SQL Injection in user query",
      "file": "src/db/users.ts",
      "line": 42,
      "cwe": "CWE-89",
      "description": "User input is concatenated directly...",
      "remediation": "Use parameterized queries instead..."
    }
  ],
  "summary": {
    "total": 7,
    "critical": 1,
    "high": 2,
    "medium": 3,
    "low": 1,
    "info": 0
  }
}

Dashboard Guide

The cloud dashboard gives you a visual overview of your security posture, scan history, and findings trends. Available on cloud and team plans.

SafeWeave Dashboard

96/100

Security Score

142

Total Scans

23

Findings

0

Critical

Dashboard
Findings
History
Trends
Settings
SAST2 medium
Secrets1 critical
Deps3 high

Dashboard

Security score gauge (0-100), total scans, findings count, 7-day trend chart, recent scans, and scanner health grid.

Findings

Paginated table of all scan results with severity badges, file paths, CWE references, and remediation guidance.

History

Timeline of all scans with timestamps, finding counts, and severity breakdowns. Infinite scroll pagination.

Trends

Stacked area chart of findings by severity over time. Bar chart of daily scan frequency. Configurable time ranges (7d-90d).

Settings

License info, plan management, upgrade/cancel subscription, API token visibility, and license key regeneration.

Upgrade

Compare plans, switch billing frequency (monthly/yearly), and upgrade to higher tiers directly from the dashboard.

Security score calculation

Your security score starts at 100 and deducts points per finding:

SeverityDeductionExample
Critical-25 pointsExposed API key in source
High-15 pointsSQL injection vulnerability
Medium-8 pointsMissing rate limiting
Low-3 pointsInformational header missing
Info0 pointsBest practice suggestion

Plans & Pricing

All paid plans include a 14-day money-back guarantee. Yearly billing saves 40%.

Featureself-hosted Self-Hostedself-hosted-pro Self-Hosted Procloud Cloudteam Team
Monthly price$0$15/mo$29/mo$99/mo
Yearly price$0$9/mo$17.40/mo$59.40/mo
SAST scanning
Secrets detection
Dependency scanning
MCP integration
Runs locally (npx)
All 8 scanners
Compliance profiles
Cloud dashboard
Hosted scanning
Trend analytics
Team management
SSO
Custom profiles
HostingYour machineYour machineManagedManaged
SupportCommunityCommunityPriority emailDedicated

ℹ️ Note

Self-Hosted (Free) includes SAST, Secrets, and Dependency scanning via npx safeweave-mcp. No account required. Upgrade to Self-Hosted Pro ($15/mo) for all 8 scanners + compliance profiles.

Self-Hosting

There are two ways to run SafeWeave locally: the recommended npx safeweave-mcp approach (no Docker required), or the full Docker Compose stack for advanced use.

Option 1: npx (recommended)

The simplest way to run SafeWeave. No Docker, no setup, no account required for free-tier scanning.

terminal
# Run directly (free: SAST, Secrets, Dependencies)
npx safeweave-mcp

# With Pro license (all 8 scanners + compliance profiles)
SAFEWEAVE_LICENSE_KEY=sw_live_xxx npx safeweave-mcp

Tip

The npx approach runs scanners directly on your machine. No containers, no network calls (except license verification for Pro). Your code never leaves your machine.

Option 2: Docker Compose (advanced)

For teams that want to run the full microservices stack locally. Requires Docker and at least 4 GB RAM.

terminal
# Clone the repository
git clone https://github.com/nickfluxk/safeweave.git
cd safeweave

# Start all services
docker compose up -d

# Verify all scanners are healthy
curl http://localhost:9000/api/health

Services & ports

ServicePortToolDescription
Gateway9000MCP server, API gateway, orchestrator
SAST9001SemgrepStatic code analysis
Dependencies9002Multi-auditDependency vulnerability scanning
Secrets9003GitleaksCredential detection
IaC9004TrivyInfrastructure-as-code scanning
Container9005TrivyContainer image scanning
DAST9006NucleiDynamic application testing
License9007license-checkerLicense compliance
Posture9008CustomAPI security posture checks

Environment variables

VariableDefaultDescription
SCAN_DIR(required)Host directory to scan — mounted read-only into containers
SAFEWEAVE_LICENSE_KEY(optional)Your license key for feature gating
SAFEWEAVE_LICENSE_URLhttps://license.safeweave.devLicense server URL
SCANNER_*_ENABLEDtrueEnable/disable individual scanners
SCAN_MOUNT/scanContainer-side mount path for project files

Local MCP config (Docker)

If using the Docker Compose stack, point your AI tool at the local gateway:

MCP config for Docker self-hosted
{
  "mcpServers": {
    "safeweave": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Run a scan via CLI

terminal
# Check all scanners are healthy
curl http://localhost:9000/api/health

# Run a scan
curl http://localhost:9000/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "scanners": ["sast", "deps", "secrets"],
    "files": {
      "app.js": "const password = \"admin123\";"
    }
  }'

Skills & Plugins

SafeWeave offers a Claude Code skill that automatically scans your code for vulnerabilities before every git commit, push, or PR creation. Once installed, it works in the background — no manual scanning required.

secure-before-push

This skill tells Claude to run a full SafeWeave scan before any git operation. Critical and high severity findings block the push. Medium findings warn you. Low and info findings pass through.

Install the skill

Run in your terminal:

Terminal
mkdir -p ~/.claude/skills/secure-before-push
curl -sL https://raw.githubusercontent.com/nickfluxk/safeweave/main/skills/secure-before-push/SKILL.md \
  -o ~/.claude/skills/secure-before-push/SKILL.md

Then restart Claude Code. The skill activates automatically whenever you commit, push, or create a PR.

What it does

SeverityActionBlocks push?
Critical / HighFix immediately, re-scanYes
MediumWarns, asks for confirmationUser decides
Low / InfoNo action neededNo

ℹ️ Note

The skill requires SafeWeave MCP to be configured in your editor. Run npx safeweave-mcp first if you haven't set it up yet.

Verify installation

Start a new Claude Code session and ask it to commit or push code. You should see SafeWeave scan automatically before the git operation.

Troubleshooting

My AI doesn't see SafeWeave tools

Restart your editor after adding the MCP config. Verify the config file is in the correct location for your editor. Ask your AI: "What MCP tools are available?" to confirm.

"Unauthorized" error when scanning

Check that your license key is correct and active. Go to Settings in the dashboard to view your key. Make sure the Authorization header uses "Bearer" prefix.

Scans are timing out

Large projects may take longer. Try scanning a specific file first with scan_file. For self-hosted, ensure Docker has at least 4 GB RAM allocated.

Self-hosted scanners not starting

Run "docker compose logs" to check for errors. Ensure Docker Desktop is running and has enough resources. Try "docker compose down && docker compose up -d" to restart.

DAST scanner returns no results

DAST requires a running target URL. Make sure your application is accessible at the URL you provide. The scanner sends real HTTP requests — the target must be reachable.

Dashboard shows no data

Dashboard data is available on Cloud and Team plans only. Self-Hosted plans show results in-line in your AI conversation.

How do I cancel my subscription?

Go to Settings → Plan & Billing in the dashboard and click "Cancel Subscription". Your access continues until the end of the current billing period.

Frequently Asked Questions

Does SafeWeave read or store my source code?

No. On Self-Hosted plans (Free and Pro), all scanning happens locally via npx -- code never leaves your machine. On Cloud plans, code is transmitted over TLS for scanning and is never stored. We only store scan results (findings, severity, file paths).

What is the difference between Self-Hosted and Self-Hosted Pro?

Self-Hosted (Free) includes SAST, Secrets, and Dependency scanning -- no account required. Self-Hosted Pro ($15/mo) unlocks all 8 scanners plus compliance profiles (SOC 2, PCI-DSS, HIPAA). Both run entirely on your machine via npx safeweave-mcp. Only license verification is remote on Pro.

Can I use SafeWeave in CI/CD?

Yes. Use the REST API directly in your CI/CD pipeline. Send scan requests with your license key and process the JSON response. Works with GitHub Actions, GitLab CI, Jenkins, and any CI system that can make HTTP requests.

Which compliance frameworks are supported?

Built-in profiles for SOC 2, PCI-DSS, HIPAA, and OWASP. You can also create custom profiles by extending any built-in profile with a .safeweave/profile.yaml file.

How is the security score calculated?

Starts at 100, deducts per finding: Critical (-25), High (-15), Medium (-8), Low (-3), Info (0). Minimum score is 0.

Can I upgrade or downgrade at any time?

Yes. Upgrade anytime from Settings → Plan & Billing. When you cancel, access continues until the end of the billing period. All paid plans include a 14-day money-back guarantee.

What happens if I lose my license key?

Go to Settings → License Key Regeneration in the dashboard. Enter your email and password to generate a new key. The old key is invalidated immediately.