Ship Safe CLI

Installation

Ship Safe requires Node.js 18 or later. No signup or API key required for core scans.

# Run directly (no install)
npx ship-safe audit .

# Or install globally
npm install -g ship-safe
ship-safe audit .

For AI-powered deep analysis, set one of these environment variables (optional):

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_AI_API_KEY=AIza...

Quick Start

# Full security audit with remediation plan + HTML report
npx ship-safe audit .

# Red team: 29 agents, 80+ attack classes
npx ship-safe red-team .

# AI agent red-team scenarios for agent-readable content
npx ship-safe red-team . --gpt-red

# Quick secret scan
npx ship-safe scan .

# Security health score (0-100, A-F)
npx ship-safe score .

# Fun emoji security grade
npx ship-safe vibe-check .

# Scan only changed files (fast pre-commit)
npx ship-safe diff --staged

# CI/CD mode with threshold gating
npx ship-safe ci . --threshold 80

Commands

Core Audit

Interactive Agent & REPL

Exit the REPL with /quit, Ctrl-D, or Ctrl-C.

REPL Slash Commands

Anything not starting with / is sent to the LLM as a free-form prompt with the latest scan results as context.

AI-Powered

CI/CD & Baseline

Infrastructure

Flags

29 Security Agents

All agents run in parallel with per-agent timeouts. Each implements shouldRun(recon) to skip irrelevant projects automatically.

Post-processors: ScoringEngine (8-category weighted scoring), VerifierAgent (secrets liveness verification), DeepAnalyzer (LLM-powered taint analysis)

Scoring System

Starts at 100. Each finding deducts points by severity and category, weighted by confidence level (high: 100%, medium: 60%, low: 30%).

Grades: A (90-100), B (75-89), C (60-74), D (40-59), F (0-39)

Exit codes: 0 for A/B (>= 75), 1 for C/D/F. Use in CI to fail builds.

CI/CD Integration

# Basic CI: fail if score < 75
npx ship-safe ci .

# Strict: fail on any critical finding
npx ship-safe ci . --fail-on critical

# Custom threshold + SARIF for GitHub Security tab
npx ship-safe ci . --threshold 80 --sarif results.sarif

# Post results as PR comment
npx ship-safe ci . --github-pr

# Only report new findings (not in baseline)
npx ship-safe ci . --baseline

Export formats: --json, --sarif, --csv, --md, --html, --pdf

GitHub Action

# .github/workflows/security.yml
name: Security Audit
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: asamassekou10/ship-safe@v6
        with:
          path: .
          threshold: 75
          sarif: true
          comment: true

      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: /tmp/ship-safe-results.sarif

Multi-LLM Support

AI classification and GPT-Red scenario mode are optional. All core commands work fully offline. Use --provider <name> or set the matching environment variable. Kimi defaults to kimi-k3 for long-context AI-agent red teaming; add --k3-long-context to expand GPT-Red context with package, CI, deployment, docs, and prior findings. Ship Safe also scans Kimi K3/OpenAI-compatible tool-call code for dynamic tool loading, missing allowlists, forced tool calls on untrusted input, and tool-result replay issues. Review the exact context limits and provider boundaries on the Security and Data Flow page.

Incremental Scanning

Ship Safe caches file hashes and findings in .ship-safe/context.json. Only changed files are re-scanned on subsequent runs.

• ~40% faster on repeated scans
• Auto-invalidation after 24 hours or when ship-safe updates
• --no-cache to force a full rescan

LLM responses are cached in .ship-safe/llm-cache.json with a 7-day TTL to reduce API costs.

Suppressing Findings

Inline: Add # ship-safe-ignore on any line:

password = get_password()  # ship-safe-ignore

Critical findings are always reported. An inline comment cannot hide one, and an attempt to suppress one is recorded in the scan. The comment exists for a human ruling out a false positive, and anything that can write a line of your source — including an AI agent — can write the comment too. Every suppression is counted, so a scan that silenced findings never reads like one that had none.

File-level: Create .ship-safeignore (gitignore syntax):

# Exclude test fixtures
tests/fixtures/
*.test.js

# Exclude documentation
docs/

Policy-as-Code

npx ship-safe policy init

Creates .ship-safe.policy.json:

{
  "minimumScore": 70,
  "failOn": "critical",
  "requiredScans": ["secrets", "injection", "deps", "auth"],
  "ignoreRules": [],
  "maxAge": { "criticalCVE": "7d", "highCVE": "30d", "mediumCVE": "90d" }
}

OWASP Coverage

Compliance mapping to SOC 2 Type II, ISO 27001:2022, and NIST AI RMF is included in audit reports.

OpenClaw Security

# Focused OpenClaw security scan
npx ship-safe openclaw .

# Auto-harden configs (0.0.0.0->127.0.0.1, add auth, ws->wss)
npx ship-safe openclaw . --fix

# Red team: simulate ClawJacked, prompt injection, data exfil
npx ship-safe openclaw . --red-team

# CI preflight
npx ship-safe openclaw . --preflight

# Scan a skill before installing
npx ship-safe scan-skill https://clawhub.io/skills/some-skill

# Generate Agent Bill of Materials
npx ship-safe abom .

# Update threat intelligence (ClawHavoc IOCs, malicious skills)
npx ship-safe update-intel

OpenClaw GitHub Action

Drop-in CI action that blocks PRs introducing agent config vulnerabilities:

# .github/workflows/openclaw-security.yml
name: OpenClaw Security Check
on: [pull_request]
permissions:
  contents: read
jobs:
  openclaw:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: asamassekou10/ship-safe/.github/actions/openclaw-check@main
        with:
          fail-on-critical: 'true'

Scans openclaw.json, .cursorrules, CLAUDE.md, Claude Code hooks, and MCP configs. Checks against the bundled threat intelligence database for known ClawHavoc IOCs.

Claude Code Plugin

claude plugin add github:asamassekou10/ship-safe

Configuration Files

The .ship-safe/ directory is automatically excluded from scans and should be added to .gitignore.

Supply Chain Hardening

Ship Safe practices what it preaches. Our own supply chain is hardened against the 2026 Trivy/CanisterWorm attack chain:

• All GitHub Actions pinned to full commit SHAs
• CI token scoped to contents: read
• npm ci --ignore-scripts in all pipelines
• OIDC trusted publishing with provenance attestation
• CODEOWNERS on supply-chain-critical files
• Strict files allowlist in package.json
• Self-scanning with ship-safe in CI
• 5 direct dependencies (minimal attack surface)