Getting Started

Installation

ShipSafe is distributed as an npm package. Install it globally:

npm install -g @shipsafe/cli

Verify the installation:

shipsafe --version
# v1.0.6

Requires Node.js 18 or later. Works on macOS, Linux, and Windows.

Your First Scan

Navigate to any project directory and run:

cd your-project
shipsafe scan

ShipSafe scans all JavaScript, TypeScript, and Python files in your project. It respects your .gitignore file and skips node_modules automatically.

The scan typically completes in 2-10 seconds depending on project size. No internet connection is required — everything runs locally on your machine.

Understanding Results

Scan output shows findings grouped by severity:

$ shipsafe scan

  CRITICAL  secrets/stripe-live-key
  src/payments.ts:3
  Stripe live secret key detected.
  Fix: Move to environment variable — process.env.STRIPE_SECRET_KEY

  HIGH  sql-injection/template-literal-in-query
  src/routes/users.ts:12
  User input interpolated directly into SQL query.
  Fix: Use parameterized queries.

  MEDIUM  auth/missing-csrf-protection
  src/routes/api.ts:8
  POST endpoint has no CSRF protection.

Scan complete: 3 findings (1 critical, 1 high, 1 medium)
Duration: 2.3s | Files scanned: 47

Each finding includes:

• •Severity — CRITICAL, HIGH, MEDIUM, or LOW
• •Rule ID — category/specific-rule for easy reference
• •Location — file path and line number
• •Description — what was detected
• •Fix suggestion — how to remediate the issue

Git Hooks

Install pre-commit hooks to automatically scan before every commit. This blocks hardcoded secrets and critical vulnerabilities from entering your git history.

shipsafe hooks install

The hook scans only staged files (fast) and blocks the commit if CRITICAL findings are detected. HIGH findings generate warnings but allow the commit. This is configurable in shipsafe.config.json.

This is especially valuable when using claude --dangerously-skip-permissions — the hooks act as a safety net for autonomous AI coding.

Setting a Baseline

If you are adding ShipSafe to an existing project, set a baseline to suppress existing findings. Future scans will only show new issues.

# Save current findings as baseline
shipsafe scan --baseline

# Future scans only show NEW findings
shipsafe scan --delta

The baseline is stored in .shipsafe/baseline.json. Commit this file to share the baseline with your team.

MCP Server Setup

Add ShipSafe as an MCP server so your AI coding assistant can scan for security issues while writing code.

// .mcp.json or claude_desktop_config.json
{
  "mcpServers": {
    "shipsafe": {
      "command": "shipsafe",
      "args": ["mcp-server"]
    }
  }
}

Once configured, your AI assistant can call tools like shipsafe_scan and shipsafe_check_package directly. See the full MCP tools reference.

Next Steps