ship-safe

The independent security agent for AI-written software. It finds issues, investigates whether they are real, and shows you the evidence.

Website · Docs · Security & Data Flow · Benchmark · Pricing · Blog · Contribute

Ship Safe CLI

Ship Safe runs locally in your repo and works in two layers.

A deterministic engine finds issues across application code, AI agents, MCP configs, prompts, dependencies, CI/CD, secrets, and cloud-adjacent configuration. Fast, repeatable, and benchmarked — this is the sensor layer.

An investigation layer then decides what the findings are worth. It traces the value that reaches a sink, searches the project for controls a rule says are missing, builds attack chains across configuration no single file contains, and — when you ask it to — probes a leaked key against its provider. Every conclusion carries the pass that reached it and the lines it read:

CONFIRMED — traced end to end (10)

    NoSQL Injection via $where [high]
    app/data/allocations-dao.js:78  NOSQL_INJECTION_WHERE
    why: threshold is assigned from the HTTP request and reaches the sink without validation on that path.
    decided by: dataflow
      1. value reaches NOSQL_INJECTION_WHERE here  app/data/allocations-dao.js:78
      2. getByUserIdAndThreshold is called here with threshold  app/routes/allocations.js:23
      3. threshold is assigned here  app/routes/allocations.js:20
    fix: Replace $where with standard MongoDB operators ($eq, $gt, $regex, etc.)

Real output from ship-safe investigate against OWASP NodeGoat. The tainted value is destructured in a route file and passed into a DAO three directories away.

Start with one command:

npx ship-safe

No signup. No API key required for scanning. Works offline for core checks. AI-backed red-team modes use your configured provider when available.

Use --no-ai to guarantee a fully local scan. Provider-backed classification, deep analysis, and GPT-Red send bounded context directly to your selected provider after best-effort credential masking. See Security & Data Flow for exact boundaries and context limits.

Quick Start

Requires Node.js 22.13+ on the 22.x line, or Node.js 24+. Node 18 and 20 are no longer supported by the current development version.

# Interactive REPL: scan, fix, and ask questions in one session
npx ship-safe

# Full audit: secrets + 31 agents + deps + remediation plan
npx ship-safe audit .

# Investigate: confirmed / likely / unresolved / refuted, with the evidence
npx ship-safe investigate .
npx ship-safe investigate . --all       # also detail unresolved and refuted
npx ship-safe investigate . --verify    # probe leaked keys against their providers

# Before you open an unfamiliar folder with an agent: what runs on open?
npx ship-safe trust ~/Downloads/take-home
npx ship-safe trust . --json

# What can an AI agent working in this repo actually reach?
npx ship-safe capabilities .

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

# Interactive fix agent: plan, diff, approve, verify the path closed
npx ship-safe agent .
npx ship-safe agent . --severity critical   # critical findings only
npx ship-safe agent . --branch --pr         # fix on a branch + open a PR

# Undo the last fix
npx ship-safe undo

# CI/CD mode — fails on any critical finding
npx ship-safe ci . --sarif results.sarif
npx ship-safe ci . --fail-on high              # stricter: critical or high

# Gate on evidence instead of severity: block only what was established
npx ship-safe ci . --fail-on-verdict confirmed
npx ship-safe ci . --ignore-refuted            # do not block on what was argued away

For pull requests, compare a trusted base scan with the head scan so existing repository debt remains visible without blocking unrelated changes:

# On the trusted base revision
npx ship-safe ci . --fail-on none --no-deps \
  --write-baseline-report /tmp/ship-safe-base.json

# On the pull request head
npx ship-safe ci . --base-report /tmp/ship-safe-base.json --fail-on high

The base artifact contains hashed finding identities, relative paths, and rule metadata. It does not store raw matched secrets. PR results classify findings as introduced, resolved, unchanged, or uncertain; ambiguous matches are shown but do not block the pull request.

Machine-readable report contract

scan --json, audit --json, and ci --json include schemaVersion: 1, the Ship Safe version, and a UTC generatedAt timestamp. Finding paths are project-relative by default so reports can move between workstations and CI without leaking local directory names. Use --absolute-paths only when a consumer explicitly needs host paths. SARIF reports carry the same package version in their tool metadata.

What Ship Safe Finds

How It Works

1. Scan locally - Ship Safe inspects your repo with targeted agents and skips checks that do not apply.

2. Investigate each finding - Separate passes decide whether it is real, ranked so a cheaper one never overturns a more expensive one: a traced data path outranks a model's reading of the same file, and a probe that authenticated outranks both.

3. Read the evidence - Findings resolve to confirmed, likely, unresolved, or refuted, each citing the lines it was concluded from, so you can disagree with a step instead of a severity label.

4. Fix with control - The agent proposes a plan and diff, asks before writing, verifies the result, and keeps changes reversible.

5. Gate in CI - Use ship-safe ci to fail risky builds and upload SARIF into GitHub code scanning.

"Why not just ask my coding agent to review the repo?"

You can, and you should. It will find real things. But there are three questions it structurally cannot answer about its own work.

Did the agent that wrote this code just mark its own homework? Asking the author whether the author made a mistake is not a review. Ship Safe is a separate reviewer with a separate method, and it disagrees with itself in public — a data-flow trace overturns the heuristic pass, and a live probe overturns both.

Can it see what it can reach? A coding agent reviewing your repo cannot read your MCP server config, cannot enumerate the permissions it was launched with, and is the actor whose reach is in question. ship-safe capabilities reads all of it from outside and reports the combinations that are dangerous together while unremarkable apart:

  CRITICAL  Repository-controlled instructions reach an unattended write capability
    1. CLAUDE.md is read as instructions and can be changed by anyone who lands a commit
       CLAUDE.md:1
    2. Claude Code runs without per-action approval
       .claude/settings.json:2
    3. shell execute granted: Bash(git push:*)
       .claude/settings.json:3
    4. filesystem write granted: Write
       .claude/settings.json:3
    5. mcp-tool write granted: mcp__github__create_pull_request
       .claude/settings.json:3
    Impact: Text committed to this repository can direct the agent to write files
            or run commands with no human in the loop.
    Boundary: Require approval for write and execute tools during sessions on
              untrusted branches, or remove the pre-granted entries.

Each of those lines is unremarkable on its own. Together they are a path from a pull request to a privileged write, and no single-file review can see it, because no single file contains it.

Is it consistent, and can you prove it got better? Ask twice, get two answers. Ship Safe's engine is deterministic, and its conclusions are gated in CI by a benchmark that scores conclusion quality, not pattern coverage: how many known-real findings it settles, how much known noise it refutes, and whether it ever refutes something real. That last number's budget is zero — it is the only error class that loses a vulnerability silently. See benchmarks/.

Why Developers Use It

• Built for AI-native apps: catches risks in agents, MCP servers, prompts, RAG flows, managed-agent configs, and AI-powered CI.
• Works with AI clients: expose Ship Safe to Codex, Claude Desktop, Cursor, Windsurf, and other MCP clients through the local stdio server.
• Fast local feedback: run it before a PR, during review, or inside CI without sending code to a hosted scanner.
• Fixes are reviewable: every suggested change is shown as a diff before it touches your files.
• Works with your stack: JavaScript, TypeScript, Python, config files, infrastructure files, GitHub Actions, and more.
• Open source core: MIT-licensed CLI with docs, examples, and a growing agent system.

Free CLI, Paid Team Workflows

The open-source CLI is the fastest way to scan any repo locally. Upgrade when you need a hosted workflow around the same scanner:

Compare plans at shipsafe.sh/pricing.

Ship Safe Cloud, the hosted dashboard for scan history, PR Guardian, billing, and team workflows, is developed in a private repository because it contains commercial product code and hosted infrastructure workflows. The public ship-safe repo remains focused on the MIT-licensed CLI, security agents, rules, fixtures, CI integrations, and documentation. See Ship Safe Cloud for the repo boundary.

Security Agents

All agents run in parallel. Each skips irrelevant projects automatically.

Investigation passes, in the order their evidence outranks each other:

A claim whose cited file or line does not resolve is recorded but never decides a verdict. Two passes of equal rank that disagree resolve to unresolved rather than to whichever verdict is scarier.

Also: ScoringEngine

The REPL

$ ship-safe

  ███████╗██╗  ██╗██╗██████╗     ███████╗ █████╗ ███████╗███████╗
  ...

  v9.4.1  ·  DeepSeek  ·  ~/my-project

  /scan to find issues  ·  /agent to fix them  ·  /help for more

shipsafe ›

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

CI/CD

# .github/workflows/security.yml
name: Security Audit
on: [push, pull_request]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Security gate
        run: npx ship-safe ci . --sarif results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

A GitLab CI version is in docs/examples/gitlab-security-workflow.yml.

GitHub Action with inline PR findings

Use the Action from a pull_request workflow when you want critical and high findings attached to the changed lines. Keep pull_request_target out of this path for forked contributions: Ship Safe refuses that privileged combination because the checkout may contain untrusted code.

name: Ship Safe
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: asamassekou10/ship-safe@v9.9.0
        with:
          fail-on: high
          inline: true

Inline comments are opt-in and only post critical/high findings. Re-running the job updates the summary without creating duplicate inline comments.

LLM Support

Works with any provider — auto-detected from environment variables. Use --provider to override.

Anthropic · OpenAI · Google · DeepSeek · Kimi K3 / Moonshot · Groq · Together · Mistral · xAI · Perplexity · Ollama · LM Studio · any OpenAI-compatible endpoint

Kimi defaults to kimi-k3 through MOONSHOT_API_KEY or KIMI_API_KEY. Use --provider kimi --model kimi-k3 for long-context GPT-Red and deep-analysis runs.

For Kimi K3-specific long-context red teaming:

npx ship-safe red-team . --gpt-red --provider kimi --model kimi-k3 --k3-long-context

Ship Safe also checks Kimi K3 / OpenAI-compatible tool-call implementations for dynamic tool loading from prompt context, missing tool allowlists, forced tool calls on untrusted input, and replayed tool results without the original assistant tool-call message.

No API key required for core scanning. AI classification and red-team --gpt-red use your configured provider when available, with deterministic offline fallback for GPT-Red checks.

Suppress False Positives

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 is meant 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, so the highest severities do not honor it. Every suppression is counted, so a scan that silenced findings never reads like one that had none.

Ordinary code rules do not grade Markdown prose or fenced code examples as deployed source. Secrets are still scanned everywhere, and agent-readable files such as AGENTS.md and CLAUDE.md keep their dedicated prompt-injection and trust-boundary checks. To review fenced examples intentionally, use --include-doc-examples with scan, audit, or ci.

# .ship-safeignore
tests/fixtures/
docs/

How noisy is it?

Recall is the easy half of a scanner. A tool that flags everything catches everything and is useless, so we also track what Ship Safe reports on mature projects with no known active vulnerabilities. These are raw findings, not confirmed defects.

The original four total 38 raw findings, down from 1,031 before v9.6.3. The current five-project clean corpus also includes Hermes Agent, which reports 662 findings, including 66 critical. Neither count is a false-positive rate or a claim of accuracy; automated investigation labels and the remaining workload are documented in the benchmark. Detection-floor checks on NodeGoat and DVWA still pass.

Corpus pinned by commit, reproducible with one command, limits documented: benchmarks/false-positives/

How does it compare to Semgrep, Gitleaks, Trivy, CodeQL?

Run Ship Safe alongside them, not instead of them. CodeQL does interprocedural taint analysis Ship Safe does not attempt, Gitleaks is the specialist for secrets, and Trivy has a real CVE database behind it.

Ship Safe covers a narrower question: what an AI coding agent just did to your repository, your CI, and your local tool configuration. MCP client config, agent memory poisoning, hallucinated-package imports and AIBOM are the areas where we found no equivalent public rules in the other four.

Full coverage matrix, verified against their public registries, including where they beat us: docs/comparison.md

Add a Badge

[![Ship Safe](https://img.shields.io/badge/Ship_Safe-A+-22c55e)](https://shipsafe.sh)

What's Next

10.1 is a precision release. It keeps the verified Hermes Agent 10.0 baseline and tightens attestation so Ship Safe's own advisory citations are not mistaken for unsigned agent resources. Existing plugin and adapter checks are partial; terminal posture, ACP/TUI, current cron lifecycle, and credential reachability remain explicit work rather than implied coverage. See the coverage matrix.

See the roadmap for what is planned and what is deliberately not. Focused contributions and benchmark-backed fixes are welcome.

Contributing

Ship Safe is open source, and the best contributions are small, focused improvements that make AI-assisted development safer.

Good first areas:

• Add a focused security agent for an AI, MCP, CI, cloud, or supply-chain risk
• Add a precise security rule to an existing agent
• Add vulnerable fixtures and regression tests
• Write examples for local scans, CI gates, red-team workflows, and MCP/agent setup

Start here:

• Good first issues
• Contributor guide
• Add an agent
• Add a security rule
• Write a custom agent plugin
• Handle MCP environment variables safely
• Use Ship Safe with Codex
• Use Ship Safe with Claude Code
• Release process

Sponsors

Ship Safe is MIT-licensed and free forever.

Star History

Ship fast. Ship safe. — shipsafe.sh