Pinata

AI-powered security scanner that finds vulnerabilities hiding in your codebase. 47 detection categories across security, data integrity, concurrency, and performance domains. Context-aware scanning adjusts rules based on your project type.

Quick Start

``bash


Fast scan (pattern matching only, ~2s)

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

AI-verified scan (eliminates false positives)

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

Prompts for API key if not configured - saved for future runs

`

What It Does

`
$ pinata analyze . --verify

Analyzing: /path/to/project
Project: Web server (high confidence) # Auto-detected
Files: 136 | Languages: Typescript

Pinata Score: 100/100 (A)

AI Verification: 351 total → 0 verified, 351 AI-dismissed

No gaps detected! Your codebase has good test coverage.
`

Key features:
- Project type detection - Adjusts rules for CLI, web server, library, serverless, etc.
- AI verification - Eliminates false positives with Claude/GPT analysis
- Interactive setup - Prompts for API key on first --verify run

Installation

`bash


Via npx (no install)

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

Global install

npm install -g pinata-security-cli
pinata analyze .
`

Commands

`bash
pinata analyze . # Fast scan
pinata analyze . --verify # AI-verified scan
pinata analyze . --execute # Dynamic execution (requires Docker)
pinata analyze . --execute --dry-run # Preview tests without running
pinata analyze . --confidence low # Include all matches
pinata analyze . --output json # JSON output
pinata analyze . --output sarif # SARIF for GitHub
pinata generate --gaps # Generate tests for gaps
pinata audit-deps # Check npm dependencies
pinata config set anthropic-api-key sk-ant-xxx
`

Detection Categories

47 categories across 7 risk domains:

Security (17) - SQL injection, XSS, command injection, path traversal, SSRF, XXE, CSRF, deserialization, hardcoded secrets, LDAP injection, timing attacks, auth failures, file upload, data exposure, rate limiting, dependency risks, prompt injection

Data (8) - Data race, truncation, precision loss, validation, null handling, encoding, schema migration, bulk operations

Concurrency (6) - Deadlock, race condition, missing timeout, missing idempotency, retry storm, thread safety

Reliability (6) - Network partition, timeout, thundering herd, connection failure, high latency, packet loss

Performance (3) - Blocking I/O, memory bloat, CPU spin

Resource (3) - Memory leak, connection pool exhaustion, file handle leak

Input (3) - Injection fuzzing, boundary testing, null/undefined handling

Configuration

Create .pinataignore to exclude paths:

`
tests/
scripts/
*.test.ts
node_modules/
dist/
`

CLI options:

`bash
--verify # AI verification (requires API key)
--execute # Dynamic test execution (requires Docker)
--dry-run # Preview generated tests without running
--confidence # high (default), medium, low
--output # terminal, json, sarif, junit, markdown
--output-file # Write results to file (for SARIF upload)
--domains # security, data, concurrency, etc.
--severity # critical, high, medium, low
--exclude # Comma-separated directories to skip
`

AI Verification

The --verify flag uses AI to analyze each pattern match and filter false positives:

`bash


Just run it - prompts for API key if needed

pinata analyze . --verify

Enter your Anthropic or OpenAI API key: sk-ant-xxx

API key saved to ~/.pinata/config.json

`

Alternative setup methods:
`bash
pinata config set anthropic-api-key sk-ant-xxx # Save to config
export ANTHROPIC_API_KEY=sk-ant-xxx # Environment variable
`

How it works:
- Patterns cast a wide net (351 matches)
- AI analyzes each match in context
- False positives are dismissed with reasoning
- Only real vulnerabilities remain (often 0-5)

Performance: ~2.5 minutes for 350 matches (batched 10/request, 3 concurrent)

Project Type Detection

Pinata auto-detects your project type and adjusts scanning rules accordingly:

| Type | Detection | Adjustments |
|------|-----------|-------------|
| CLI | bin field, commander/yargs | Blocking I/O allowed, SSRF skipped |
| Web Server | express/fastify deps | SQL injection weighted higher |
| API | routes/, NestJS/tRPC | CSRF skipped, auth weighted higher |
| Frontend SPA | react/vue deps | SQL injection skipped |
| SSR Framework | next.config.js | XSS weighted higher |
| Serverless | serverless.yml | Memory leaks skipped |
| Library | exports field | Rate limiting skipped |

This reduces false positives by ~60% for specialized project types.

Dynamic Execution (Layer 5)

The --execute flag runs generated exploit tests in a Docker sandbox to prove vulnerabilities exist:

`bash


Requires Docker

pinata analyze . --execute

Preview tests without running

pinata analyze . --execute --dry-run
`

How it works:
- Generates exploit tests for each vulnerability
- Runs tests in isolated Docker container (no network, limited resources)
- Reports CONFIRMED vs POTENTIAL vulnerabilities
- Evidence includes payload and actual exploit result

Testable vulnerability types:
- SQL injection (boolean blind, UNION attacks)
- XSS (script injection, innerHTML)
- Command injection (shell metacharacters)
- Path traversal (../ attacks)

Security constraints:
- Network disabled (no exfiltration)
- 1 CPU, 512MB RAM, 30s timeout
- Read-only filesystem, unprivileged user
- No capabilities

CI/CD Integration

GitHub Action (recommended)

`yaml
name: Security Scan
on: [push, pull_request]

jobs:
security:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: christiancattaneo/pinata-security@v1
with:
confidence: high
sarif-output: pinata.sarif
# Optional: AI verification
# with:
# verify: true
# env:
# ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
`

Action inputs:
- path - Directory to scan (default: .)
- confidence - high, medium, low (default: high)
- domains - Comma-separated domains to scan
- verify - Enable AI verification (default: false)
- fail-on-gaps - Fail if gaps found (default: true)
- sarif-output - Path for SARIF file (auto-uploads to GitHub Security)

Action outputs:
- score - Pinata score (0-100)
- gaps - Number of gaps found
- sarif-file - Path to SARIF file

Manual workflow (any CI)
`yaml
- run: npx --yes pinata-security-cli@latest analyze . --output sarif --output-file results.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: results.sarif
`

GitLab CI
`yaml
security-scan:
image: node:20
script:
- npx --yes pinata-security-cli@latest analyze . --output json > pinata.json
artifacts:
reports:
sast: pinata.json
`

Output Formats

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

Performance

| Codebase Size | Time |
|---------------|------|
| 100 files | ~0.5s |
| 1,000 files | ~2s |
| 10,000 files | ~15s |

Development

`bash
git clone https://github.com/christiancattaneo/pinata-security.git
cd pinata-security
npm install
npm run build
npm test
``

Documentation

- Getting Started
- All Categories
- How It Works

License

MIT