Documentation

Pinata scans your codebase for security vulnerabilities and test coverage gaps across 45 detection categories. Get started in under a minute.

Installation

Run Pinata instantly with npx (no install required):

$ npx --yes pinata-security-cli@latest analyze .

Or install globally:

$ npm install -g pinata-security-cli

Quick Start

Scan any directory:

$ pinata analyze ./src

Pinata Score: 85/100 (B)

High Severity Gaps (3):
  sql-injection     src/db/queries.ts:45
  hardcoded-secrets src/config/api.ts:12
  missing-timeout   src/http/client.ts:89

Understanding the Score

Pinata calculates a coverage score from 0-100 based on:

Gap count - Detected vulnerabilities weighted by severity
Domain coverage - Which risk domains have been scanned
Confidence levels - Higher confidence findings weigh more

Grade	Score	Meaning
A	90-100	Excellent coverage, minimal gaps
B	80-89	Good coverage, some gaps to address
C	70-79	Moderate coverage, action recommended
D	60-69	Below average, significant gaps
F	0-59	Poor coverage, immediate action needed

Configuration

Configure Pinata via CLI flags or a .pinatarc file:

# .pinatarc (JSON)
{
  "excludeDirs": ["node_modules", "dist", "vendor"],
  "minConfidence": "high",
  "output": "terminal"
}

AI Features

Enable AI-powered explanations and test generation by setting your API key:

$ pinata config set anthropic-api-key sk-ant-xxx

# Or use environment variable
$ export ANTHROPIC_API_KEY=sk-ant-xxx

pinata analyze

Scan a directory for security gaps:

$ pinata analyze [path] [options]

Option	Description	Default
`-c, --confidence`	Minimum confidence: high, medium, low	high
`-o, --output`	Output format: terminal, json, sarif, junit	terminal
`-d, --domain`	Filter by domain (security, data, etc)	all
`-v, --verbose`	Show detailed output	false
`--exclude`	Directories to exclude	node_modules,dist

pinata generate

Generate security tests for detected gaps (requires AI API key):

$ pinata generate --gaps

Generated 5 tests:
  tests/security/sql-injection.test.ts
  tests/security/xss.test.ts
  ...

pinata explain

Get AI explanations for specific gaps:

$ pinata explain sql-injection src/db/queries.ts:45

SQL Injection at src/db/queries.ts:45

The query concatenates user input directly into SQL:
  const query = `SELECT * FROM users WHERE id = ${userId}`;

Risk: Attackers can inject malicious SQL to read, modify, 
or delete data. Could lead to full database compromise.

Fix: Use parameterized queries:
  const query = 'SELECT * FROM users WHERE id = $1';
  db.query(query, [userId]);

pinata dashboard

Launch the interactive TUI dashboard:

$ pinata dashboard

Navigate with arrow keys, press Enter to drill into gaps, q to quit.

pinata config

Manage persistent configuration:

$ pinata config set anthropic-api-key sk-ant-xxx
$ pinata config get anthropic-api-key
$ pinata config list
$ pinata config unset anthropic-api-key

CI/CD Integration

GitHub Actions

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

jobs:
  pinata:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Pinata
        run: npx --yes pinata-security-cli@latest analyze . --output sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI

# .gitlab-ci.yml
security-scan:
  image: node:20
  script:
    - npx --yes pinata-security-cli@latest analyze . --output json > pinata.json
  artifacts:
    reports:
      sast: pinata.json

Fail on Gaps

Use --fail-on critical to exit with code 1 if critical gaps are found. Perfect for blocking PRs with security issues.

Output Formats

terminal - Human-readable output with colors
json - Machine-readable JSON for scripting
sarif - SARIF 2.1.0 for GitHub Advanced Security
junit - JUnit XML for CI systems
markdown - Markdown report for PRs

Ignore Files

Create a .pinataignore file to exclude paths:

# .pinataignore
tests/
scripts/
*.test.ts
*.spec.js
vendor/
dist/
node_modules/

Patterns follow gitignore syntax.