# AgenticCLI / ShipGuard — Full Agent Integration Guide

## 1. What ShipGuard Is

ShipGuard is a local-first release gate CLI for AI-generated code. It runs 5 check
modules (secrets, auth, payments, database, deployment) against your project files
locally in seconds. No code, file contents, or paths are transmitted to any server.

**Who it is for:** AI coding agents (Claude Code, Cursor, Codex CLI, Windsurf, etc.)
and the CI pipelines they commit to. Run ShipGuard after each edit session and before
every deploy.

**What it catches:** hardcoded API keys, unprotected admin routes, unsigned webhooks,
destructive database migrations, CORS wildcards, Docker misconfigurations, and more.

**What it does NOT replace:** dependency vulnerability scanning (SCA), SAST for
injection/XSS, or a full penetration test. Use a dedicated security platform alongside.

---

## 2. Per-Platform Setup

### Claude Code (invoke after editing files)

Add to your agent instructions or CLAUDE.md:

```
After generating or editing code, run:
  npx @agenticcli/shipguard scan --changed --strict --json
Parse the JSON output. If exit code is 1 (blocked), fix all findings where
blocking:true before proceeding. If exit code is 2 (degraded), note this in
your response — the scan ran with incomplete results.
```

### Cursor (add to .cursor/rules or as a system prompt directive)

```
After each file edit session, before committing:
  npx @agenticcli/shipguard scan --changed --strict --json
Review any findings with severity "high" or "critical". Fix all where blocking:true.
Note: --strict is required for exit code 1 to be emitted on blocking findings.
```

### Codex CLI

```bash
npx @agenticcli/shipguard scan --changed --strict --json
```

Parse stdout as JSON. Exit 0 = safe to proceed. Exit 1 = fix blocking findings first.

### GitHub Actions (add as a gate step)

```yaml
- name: Checkout
  uses: actions/checkout@v4
  with:
    fetch-depth: 0          # Required: --changed needs full git history

- name: ShipGuard security gate
  run: npx @agenticcli/shipguard scan --changed --strict --json
```

The step fails the workflow on exit code 1 (blocking findings) or 3 (runtime error).
Exit code 2 (degraded) does NOT fail the step — handle it downstream if needed.

---

## 3. System Prompt Snippet (canonical)

Copy this verbatim into any agent system prompt or coding rules file:

```
After generating or editing code, run:
  npx @agenticcli/shipguard scan --changed --strict --json

Parse the JSON output (stdout). Decision logic:
  Exit 0 → safe to proceed
  Exit 1 → fix every finding where blocking:true, then re-scan
  Exit 2 → scan ran with incomplete results (degraded) — note this
  Exit 3 → scan itself failed — report the error

Each finding has: id, title, severity, category, file, line, explanation,
recommendation, blocking. Fix blocking findings before proceeding.
```

---

## 4. Exit Code Contract

| Code | Meaning | When |
|------|---------|------|
| 0 | Safe | No blocking findings, OR --strict flag not used |
| 1 | Blocked | --strict flag AND at least one finding with blocking:true |
| 2 | Config/degraded | Pro rules unavailable, files skipped, scan incomplete |
| 3 | Runtime error | Scan itself failed to run |

**Important:** exit code 1 is ONLY set when both conditions are true: the --strict
flag is passed AND at least one finding has blocking:true. Without --strict, blocking
findings are reported in the JSON but do not change the exit code from 0.

---

## 5. --json Output Schema

When --json is passed, ShipGuard writes a single JSON object to stdout.

### Top-level shape

```
{
  findings:          Finding[]        // array of individual findings (may be empty)
  riskScore:         RiskScore        // aggregate risk summary
  filesScanned:      number           // count of files actually scanned
  timestamp:         string           // ISO 8601 UTC timestamp
  policyUsed:        string           // name of the policy applied
  recommendation:    "SAFE_TO_SHIP" | "REVIEW_BEFORE_SHIP" | "DO_NOT_SHIP"
  schemaVersion:     string           // "2" (current)
  degraded:          boolean?         // true if scan ran with incomplete results
  degradedReasons:   DegradedReason[] // present only when degraded:true
  creditsWarning:    boolean?         // true if pro credits are low
  rulesVersion:      string?          // version tag of the rule set applied
  aiCodeIssues:      number?          // count of findings flagged for AI-generated code
  rulesApplied:      number?          // pro only: count of pro rules applied
  rulesBreakdown:    Record<string, number>? // pro only: findings per rule category
}
```

### Finding shape

```
{
  id:              string        // rule identifier, e.g. "hardcoded_secret"
  title:           string        // human-readable title, e.g. "OpenAI API Key"
  severity:        "info" | "low" | "medium" | "high" | "critical"
  category:        "secrets" | "auth" | "payments" | "database" | "deployment"
                   | "injection" | "supply-chain" | "crypto" | "config"
  file:            string        // relative file path
  line:            number?       // line number (omitted for file-level findings)
  evidence:        string?       // redacted snippet (secrets are partially masked)
  explanation:     string        // why this finding is a risk
  recommendation:  string        // how to fix it
  blocking:        boolean       // if true + --strict flag → exit code 1
  fix:             string?       // concrete fix snippet when available
  confidence:      "HIGH" | "MEDIUM" | "LOW"?
  aiCodeTarget:    boolean?      // true if this pattern is specific to AI-generated code
  suppressed:      boolean?      // true if suppressed by shipguard.yaml config
  cwe:             string[]?     // CWE identifiers, e.g. ["CWE-798"]
}
```

### RiskScore shape

```
{
  score:            number    // 0-100 (100 = most risky)
  recommendation:   "SAFE_TO_SHIP" | "REVIEW_BEFORE_SHIP" | "DO_NOT_SHIP"
  totalFindings:    number
  criticalCount:    number
  highCount:        number
  mediumCount:      number
  lowCount:         number
  infoCount:        number
  blockingCount:    number   // count of findings where blocking:true
}
```

### DegradedReason shape

```
{
  code:    "FILE_TOO_LARGE" | "OUTPUT_TRUNCATED" | "CODEREF_SKIPPED"
           | "PRO_RULES_UNAVAILABLE"
  detail:  string?    // optional human-readable explanation
}
```

---

## 6. Parsing Guide for Agents

Recommended pattern for consuming --json output:

```javascript
// Parse stdout after running: npx @agenticcli/shipguard scan --changed --strict --json
const result = JSON.parse(stdout);

// 1. Check if scan ran with incomplete results
if (result.degraded) {
  const reasons = (result.degradedReasons || []).map(r => r.code).join(', ');
  console.warn('ShipGuard scan was degraded:', reasons);
  // Proceed with caution — findings may be incomplete
}

// 2. Extract blocking findings
const blocking = result.findings.filter(f => f.blocking && !f.suppressed);

// 3. Each blocking finding has actionable fields:
for (const f of blocking) {
  console.log(f.file, f.line, f.title, f.recommendation);
  // f.fix contains a concrete code snippet when available
}

// 4. Check aggregate recommendation
console.log(result.riskScore.recommendation);
// "SAFE_TO_SHIP" | "REVIEW_BEFORE_SHIP" | "DO_NOT_SHIP"
```

---

## 7. Platform Support Matrix

| Platform | Support | Notes |
|----------|---------|-------|
| Next.js | Full | App Router + Pages Router; auth middleware detection |
| Express | Full | Route-level auth guard detection |
| Fastify | Full | Route-level auth guard detection |
| Node.js | Full | Secrets + deployment checks across all .js/.ts files |
| Python | Partial | Secrets + deployment patterns only |
| Go | Partial | Secrets + deployment patterns only |
| Rust | Partial | Secrets + deployment patterns only |
| Docker | Full | Dockerfile + docker-compose.yml |
| GitHub Actions | Full | Workflow .yml files (secrets, permissions) |

---

## 8. Starter (Free) Tier vs Pro Tier

| Feature | Starter (Free) | Pro ($29/mo or $19/mo annual) |
|---------|----------------|-------------------------------|
| Local scans | Unlimited | Unlimited |
| Cloud scans | 5/mo (soft cap; falls back to local) | 100/mo (full current corpus + CI gate) |
| Secrets detection | Yes | Yes + 150+ additional patterns |
| Auth checks | Yes | Yes + framework-specific guards |
| Payment checks | Yes | Yes + provider-specific patterns |
| Database checks | Yes | Yes + ORM-specific patterns |
| Deployment checks | Yes | Yes + cloud-provider configs |
| Total rules | 33 bundled | 200+ fetched at scan time |
| Pro rules on disk | N/A | Never — loaded into memory only |
| Network calls during scan | Zero | Auth API call to fetch pro rules |
| Account required | No | Yes |

---

## 9. Privacy Guarantee

- All scanning runs locally on your machine.
- No code, file contents, or file paths are transmitted to any server.
- Free tier: zero network calls during scan.
- Pro tier: one authenticated API call to fetch rule definitions (not your code).
  Rule definitions are loaded into memory for the duration of the scan and discarded.
- Telemetry: anonymous verdict (SAFE_TO_SHIP / DO_NOT_SHIP), scan duration, and
  CLI version. No file names, no findings, no code. Disable with SHIPGUARD_TELEMETRY=0.

---

## 10. Configuration (shipguard.yaml)

Optional config file at the project root:

```yaml
# shipguard.yaml
ignore:
  - "**/*.test.ts"        # skip test files
  - "scripts/seed/**"     # skip seed scripts
rules:
  db-push-in-scripts:
    enabled: false        # disable a specific rule
```

---

## Links

- Concise index: https://agenticcli.dev/llms.txt
- A2A agent card: https://agenticcli.dev/.well-known/agent.json
- Agent skills index: https://agenticcli.dev/.well-known/agent-skills/index.json
- MCP server card (planned V2): https://agenticcli.dev/.well-known/mcp/server-card.json
- Free rules catalog: https://agenticcli.dev/shipguard/rules.json
- API catalog: https://agenticcli.dev/.well-known/api-catalog
- npm: https://www.npmjs.com/package/@agenticcli/shipguard
- Docs: https://agenticcli.dev/shipguard/docs