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.
Run one command
npx safeweave-mcpThis starts the SafeWeave MCP server locally. SAST, Secrets, and Dependency scanning are free -- no account required.
Connect your AI coding tool
claude mcp add safeweave -- npx -y safeweave-mcp{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"]
}
}
}Ask your AI to scan
"Scan this project for security vulnerabilities" -- SafeWeave handles the rest.✨ Tip
"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
:9000
8 Scanners
Scan Flow
User prompt
"Scan this project"
MCP call
scan_project tool
Gateway
Route to scanners
Parallel scan
8 scanners run
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.
{
"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.
{
"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.
{
"mcpServers": {
"safeweave": {
"url": "https://api.safeweave.dev/mcp",
"headers": {
"Authorization": "Bearer YOUR_LICENSE_KEY"
}
}
}
}How to upgrade from Free to Pro
Create an account and get your license key.
Go to Upgrade and subscribe to Self-Hosted Pro ($15/mo).
Add your license key to your MCP config as SAFEWEAVE_LICENSE_KEY. Restart your editor.
ℹ️ Note
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)
Run one command to add SafeWeave:
claude mcp add safeweave -- npx -y safeweave-mcpStart a new Claude Code session. SafeWeave tools will be loaded automatically.
✨ Tip
.mcp.json in your project root:{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"],
"env": {
"SAFEWEAVE_LICENSE_KEY": "sw_live_xxxxxxxxxxxxxxxx"
}
}
}
}Cursor
Open Cursor and go to Settings → MCP, or edit the config file directly:
{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"]
}
}
}Restart Cursor. You should see SafeWeave tools in your MCP tool list.
VS Code + GitHub Copilot
Create .vscode/mcp.json in your workspace:
{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"]
}
}
}Reload VS Code window (Cmd+Shift+P → Reload Window).
Open Copilot Chat and ask it to scan your project. SafeWeave tools will appear in the tool list.
Windsurf
Edit your Windsurf MCP config file:
{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"]
}
}
}Restart Windsurf to load SafeWeave tools.
Warp Terminal
Open Warp Settings → MCP Servers → Add Server.
Configure the server with SSE transport:
{
"mcpServers": {
"safeweave": {
"command": "npx",
"args": ["-y", "safeweave-mcp"]
}
}
}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 SemgrepAnalyzes 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 GitleaksScans 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 auditAudits 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 TrivyScans 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 TrivyScans 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 NucleiTests 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-licensesChecks 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 checksAnalyzes your server code for 12 API security best practices including authentication, rate limiting, CORS, and more.
| Check ID | Description | CWE |
|---|---|---|
| POSTURE-001 | Missing authentication middleware | — |
| POSTURE-002 | No rate limiting | CWE-770 |
| POSTURE-003 | Missing security headers | — |
| POSTURE-004 | No request body size limit | — |
| POSTURE-005 | CORS wildcard (*) configuration | CWE-346 |
| POSTURE-006 | Missing CSRF protection | CWE-352 |
| POSTURE-007 | Plain HTTP without TLS | CWE-319 |
| POSTURE-008 | Detailed error messages exposed | CWE-209 |
| POSTURE-009 | No request logging / audit trail | CWE-778 |
| POSTURE-010 | Unsafe JSON.parse without try-catch | CWE-502 |
| POSTURE-011 | Server binds to 0.0.0.0 | CWE-668 |
| POSTURE-012 | No input validation library | CWE-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.
| Tool | Description | Parameters |
|---|---|---|
| scan_file | Scan a single file for vulnerabilities | file_path (string) |
| scan_project | Run full security scan on entire project | directory (string, optional) |
| scan_dependencies | Audit dependencies for known CVEs | directory (string, optional) |
| get_findings | Retrieve scan findings with filters | severity (enum), file (string) |
| set_profile | Switch active compliance profile | profile (enum) |
| get_security_score | Get overall security posture score | directory (string, optional) |
| suggest_fix | Get remediation for a specific finding | finding_id (string) |
| scan_iac | Scan infrastructure-as-code files | directory (string, optional) |
| check_container | Scan container images for CVEs | directory (string, optional) |
| check_license | Check license compliance | directory (string, optional) |
| dast_check | Run dynamic security testing | directory, target_url (string) |
| check_posture | Check API security posture | directory (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)
| URI | Description |
|---|---|
| safeweave://profiles | List all available compliance profiles |
| safeweave://findings/summary | Summary of current scan findings |
| safeweave://config | Current 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
DefaultBalanced 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
ComplianceDesigned 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
CompliancePayment 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
ComplianceHealthcare 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:
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.0API 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 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
| Method | Endpoint | Description |
|---|---|---|
POST | /api/scan | Run a scan with specified scanners and files |
GET | /api/health | Check gateway and scanner health status |
GET | /api/scanners | List all available scanners and their status |
POST | /api/auth | Authenticate and receive a session token |
POST | /api/register | Create a new account |
GET | /api/customer/license | Get license info, plan, and status |
GET | /api/customer/scans | List scan history (paginated) |
GET | /api/customer/trends | Get security trends over time |
GET | /api/customer/score | Get overall security score (0-100) |
Base URL: https://api.safeweave.dev
Response format
{
"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.
96/100
Security Score
142
Total Scans
23
Findings
0
Critical
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:
| Severity | Deduction | Example |
|---|---|---|
| Critical | -25 points | Exposed API key in source |
| High | -15 points | SQL injection vulnerability |
| Medium | -8 points | Missing rate limiting |
| Low | -3 points | Informational header missing |
| Info | 0 points | Best practice suggestion |
Plans & Pricing
All paid plans include a 14-day money-back guarantee. Yearly billing saves 40%.
| Feature | self-hosted Self-Hosted | self-hosted-pro Self-Hosted Pro | cloud Cloud | team 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 | — | — | — | |
| Hosting | Your machine | Your machine | Managed | Managed |
| Support | Community | Community | Priority email | Dedicated |
ℹ️ Note
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.
# 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
Option 2: Docker Compose (advanced)
For teams that want to run the full microservices stack locally. Requires Docker and at least 4 GB RAM.
# 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/healthServices & ports
| Service | Port | Tool | Description |
|---|---|---|---|
| Gateway | 9000 | — | MCP server, API gateway, orchestrator |
| SAST | 9001 | Semgrep | Static code analysis |
| Dependencies | 9002 | Multi-audit | Dependency vulnerability scanning |
| Secrets | 9003 | Gitleaks | Credential detection |
| IaC | 9004 | Trivy | Infrastructure-as-code scanning |
| Container | 9005 | Trivy | Container image scanning |
| DAST | 9006 | Nuclei | Dynamic application testing |
| License | 9007 | license-checker | License compliance |
| Posture | 9008 | Custom | API security posture checks |
Environment variables
| Variable | Default | Description |
|---|---|---|
| SCAN_DIR | (required) | Host directory to scan — mounted read-only into containers |
| SAFEWEAVE_LICENSE_KEY | (optional) | Your license key for feature gating |
| SAFEWEAVE_LICENSE_URL | https://license.safeweave.dev | License server URL |
| SCANNER_*_ENABLED | true | Enable/disable individual scanners |
| SCAN_MOUNT | /scan | Container-side mount path for project files |
Local MCP config (Docker)
If using the Docker Compose stack, point your AI tool at the local gateway:
{
"mcpServers": {
"safeweave": {
"url": "http://localhost:9000/mcp"
}
}
}Run a scan via CLI
# 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:
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.mdThen restart Claude Code. The skill activates automatically whenever you commit, push, or create a PR.
What it does
| Severity | Action | Blocks push? |
|---|---|---|
| Critical / High | Fix immediately, re-scan | Yes |
| Medium | Warns, asks for confirmation | User decides |
| Low / Info | No action needed | No |
ℹ️ Note
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.