Documentation

ShipGuard is a CLI-first agentic release gate. This guide covers installation, configuration, and CI integration.

Quick Start

Install ShipGuard globally, initialize your project, and run your first scan in under a minute.

1. Install the CLI

bash

npm install -g @agenticcli/shipguard

2. Initialize your project

bash

cd your-project shipguard init

This creates a shipguard.yaml file in your project root.

3. Run a scan

bash

# Scan all files shipguard scan # Scan only git-changed files (recommended for CI) shipguard scan --changed

💡Use --changed in CI to only scan files modified in the current PR or push. Much faster for large codebases.

Commands

shipguard init

Initialize ShipGuard in the current directory. Creates shipguard.yaml with default policy.

shipguard scan [path]

Scan files for policy violations. Defaults to current directory. Exits with code 1 if blocking findings exist (requires --strict).

shipguard scan --changed

Scan only files changed according to git (staged + unstaged + untracked).

shipguard report

Generate a detailed HTML or Markdown report of the last scan.

Policy File

ShipGuard reads shipguard.yaml from your project root. This file controls which checks run and their severity thresholds.

yaml

# shipguard.yaml
version: 1

# Which check categories to enable
checks:
  secrets: true
  auth: true
  payments: true
  database: true
  deployment: true

# Block the release if any finding matches these severities
block_on:
  - critical

# Files and directories to ignore
ignore:
  - "**/*.test.ts"
  - "**/*.spec.ts"
  - ".next/**"
  - "node_modules/**"
  - "dist/**"

# Override severity for specific rules
overrides:
  deployment/cors-wildcard: medium  # downgrade from critical

ℹ️All paths in ignore are glob patterns matched against the file path relative to the project root.

CLI Flags

Flag	Default	Description
--changed	false	Scan only git-changed files instead of all files.
--json	false	Output findings as JSON instead of human-readable text.
--strict	false	Block on medium-severity findings in addition to critical.
--report <format>	none	Generate a report file. Formats: html, markdown.
--config <path>	shipguard.yaml	Path to the policy config file.
--no-color	false	Disable colored terminal output.

Check Categories

Each category maps to a set of deterministic rules. No AI inference — all checks are regex and static analysis.

secrets

›Hardcoded API keys (OpenAI, Stripe, AWS, etc.)
›Private keys / PEM blocks in source
›Passwords in connection strings
›JWT secrets hardcoded in code

auth

›Unauthenticated admin/internal routes
›Missing CSRF protection on mutations
›Weak or default session secrets
›Auth bypass patterns (commented-out guards)

payments

›Stripe/Paddle webhook signature not verified
›Price or amount read from client request body
›Missing idempotency keys on charge creation
›Test mode keys in production config

database

›String-concatenated SQL queries (injection vectors)
›DELETE/UPDATE without WHERE clause
›Missing transaction on multi-step writes
›Unsafe deserialization patterns

deployment

›DEBUG=true or NODE_ENV=development in prod config
›CORS configured to allow all origins (*)
›Missing required environment variable validation
›Exposed stack traces in error responses

CI Integration

Add ShipGuard to your GitHub Actions workflow to block PRs with critical findings.

yaml

# .github/workflows/shipguard.yml
name: ShipGuard Release Gate

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  shipguard:
    name: Agentic Release Gate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # needed for --changed to work

      - name: Install ShipGuard
        run: npm install -g @agenticcli/shipguard

      - name: Run ShipGuard scan
        run: shipguard scan --changed --json
        env:
          SHIPGUARD_TOKEN: ${{ secrets.SHIPGUARD_TOKEN }}  # optional: Pro rules

⚠️Without fetch-depth: 0, git may not have enough history for --changed to compute the correct diff.

Exit codes

Code	Meaning
0	All checks passed — safe to ship
1	Critical findings found — release blocked
2	Config error (missing or invalid shipguard.yaml)
3	Runtime error (filesystem, permissions, etc.)