---
title: "Configuration Guide | ShipSafe"
description: "Configure ShipSafe with .shipsafe.yml and .shipsafeignore. Customize scan behavior, suppress rules, and set severity thresholds."
doc_version: 2026-09-23
last_updated: 2026-09-23T09:33:01.305Z
canonical: https://ship-safe.co/docs/configuration
---

# Configuration Guide | ShipSafe

● Configuration

# Tune it. Without the YAML cult.

Two files run the show: `.shipsafe.yml` picks the rules, `.shipsafeignore` silences the noise.

▸ .SHIPSAFE.YML

## .shipsafe.yml

Drop a `.shipsafe.yml` at the project root to override defaults. Generate one with:

TERMINAL

Copy

```bash
npx @ship-safe/cli init
```

### Full Example

TERMINAL·.shipsafe.yml

Copy

```yaml
# .shipsafe.yml — drop this in your project root

# Rules to include (default: all — omit this block to run every category)
# Available categories:
# secrets, injection, xss, auth, crypto, config
# pii, authz, baas, llm, headers, deps
# client, ai-agent, cost, nextjs, express, django
# supabase, rails, react, nestjs, fastify, hono
# remix, astro, trpc, expo, aspnet, spring
# goweb, symfony, fastapi, flask, firebase, vue
# nuxt, svelte, laravel
rules:
  include:
    - secrets
    - injection
    - baas
    # ...any category listed above
  # exclude:
  #   - deps    # skip dependency checks

# Glob patterns to exclude from scanning
exclude:
  - "node_modules"
  - ".git"
  - "dist"
  - "build"
  - "*.min.js"
  - "*.test.*"
  - "*.spec.*"

# Minimum severity to report: critical, high, medium, low
severity: low
```

▸ RULE OVERRIDES

## Config Options

### rules.include

Rule categories to scan. Omit it and every category runs.

Categories: secrets, injection, xss, auth, authz, crypto, config, pii, baas, llm, headers, deps

### rules.exclude

Categories to skip. Use it when you want everything except one noisy bucket.

### exclude

Glob patterns to skip, layered on top of the defaults.

Default exclusions: node\_modules, .git, .next, dist, build, coverage, \*.min.js, \*.map, lock files, test files

### severity

Minimum severity to report: critical, high, medium, low (default). Anything below gets hidden.

▸ IGNORE PATTERNS

## .shipsafeignore

Silence rules you've already triaged. Ignored findings don't fail CI and show up as "suppressed" in the dashboard.

TERMINAL·.shipsafeignore

Copy

```bash
# .shipsafeignore — suppress specific rules
# Format: rule-id # optional reason

# These findings won't block CI or show in reports
secrets/generic-api-key  # Test fixture, not a real key
xss/dangerously-set-html # Sanitized by DOMPurify
injection/eval-usage     # Required for plugin system
```

### Managing rules via CLI

TERMINAL

Copy

```bash
# Suppress a rule
npx @ship-safe/cli ignore secrets/generic-api-key -r "Test API key"

# Re-enable a rule
npx @ship-safe/cli unignore secrets/generic-api-key
```

▸ FILE SYNTAX

## Ignore File Format

| Syntax                 | Meaning                           |
| ---------------------- | --------------------------------- |
| secrets/aws-access-key | Suppress this rule ID             |
| rule-id # reason       | Suppress with a documented reason |
| \# comment             | Comment line (ignored)            |
| (empty line)           | Ignored                           |

▸ SUPPORTED FILES

## Supported File Types

ShipSafe scans these automatically. Files over 1MB get skipped. JavaScript, TypeScript, and Python get the deepest pattern coverage; PHP, Ruby, Go, Java, C#, Swift, Kotlin, and Rust have dedicated framework rules plus a language-aware AI review. Your report lists the coverage depth per language.

JavaScript

.js, .jsx, .mjs, .cjs

TypeScript

.ts, .tsx

Python

.py

Ruby

.rb

Go

.go

Java

.java

PHP

.php

Rust

.rs

C#

.cs

Swift

.swift

Kotlin

.kt

Config

.env, .yml, .json

▸ TIPS

## Tips

TIP

**Commit .shipsafeignore** so the whole team inherits the same suppressions.

TIP

**Always add a reason** when suppressing a rule. Future-you will thank past-you.

NOTE

ShipSafe already honors **.gitignore**. Don't duplicate those patterns in .shipsafe.yml.

[← PreviousGit History Secrets](https://ship-safe.co/docs/git-history-scanning)[Next →Security Rules](https://ship-safe.co/docs/rules)

## Sitemap

Every page of this site, in markdown: [https://ship-safe.co/sitemap.md](https://ship-safe.co/sitemap.md)