Metadata-Version: 2.4
Name: pinaka-scan
Version: 0.3.0
Summary: Free dependency vulnerability scanner. Like Snyk, but open. Powered by OSV.dev.
Project-URL: Homepage, https://pinaka.sh
Project-URL: Repository, https://github.com/0xparth/pinaka-scan
Project-URL: Issues, https://github.com/0xparth/pinaka-scan/issues
Author-email: Parth Shukla <certsubs@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cve,dependencies,osv,sca,scanner,security,vulnerability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# pinaka-scan

Free dependency vulnerability scanner. Like Snyk, but open.  
Powered by [OSV.dev](https://osv.dev) — no API key, no signup, no limits.

## Install

```bash
pip install pinaka-scan
```

## Usage

```bash
# Auto-detect manifest in current directory
pinaka-scan

# Scan a specific file
pinaka-scan requirements.txt
pinaka-scan package.json
pinaka-scan go.mod

# Verbose output (show descriptions)
pinaka-scan -v

# JSON output (for CI pipelines)
pinaka-scan --json

# Only fail on critical/high severity
pinaka-scan --fail-on high

# Override ecosystem detection
pinaka-scan lockfile.txt -e PyPI
```

### Recursive Scanning

Scan all manifest files in a project tree (monorepos, polyglot repos):

```bash
pinaka-scan --recursive
pinaka-scan --recursive -d /path/to/project
```

Automatically skips `node_modules/`, `.git/`, `venv/`, `.venv/` and other junk directories.

### SARIF Output

Generate [SARIF v2.1.0](https://sarifweb.azurewebsites.net/) output for GitHub Security tab integration:

```bash
pinaka-scan --sarif > results.sarif
```

### Ignoring Vulnerabilities

Create a `.pinaka-ignore` file to suppress accepted vulnerabilities (one ID per line):

```
# Accepted risk: low severity, no fix available
CVE-2021-34141
GHSA-5cpq-8wj7-hf2v
```

```bash
# Uses .pinaka-ignore by default
pinaka-scan

# Custom ignore file path
pinaka-scan --ignore-file my-ignore-list.txt
```

Ignored vulnerabilities are excluded from output and do not affect exit codes.

## CI/CD Integration

### Basic

```yaml
- name: Scan dependencies
  run: |
    pip install pinaka-scan
    pinaka-scan --fail-on high
```

### GitHub Security Tab (SARIF)

Upload scan results to the GitHub Security tab:

```yaml
- name: Scan dependencies
  run: |
    pip install pinaka-scan
    pinaka-scan --sarif > results.sarif
  continue-on-error: true

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

Exit codes:
- `0` — no vulnerabilities (or none above `--fail-on` threshold)
- `1` — vulnerabilities found
- `2` — scan error

## Supported Ecosystems

| Ecosystem | Files |
|-----------|-------|
| Python (PyPI) | `requirements.txt`, `Pipfile.lock` |
| Node.js (npm) | `package.json`, `package-lock.json`, `yarn.lock` |
| Go | `go.mod`, `go.sum` |
| Rust (crates.io) | `Cargo.toml`, `Cargo.lock` |
| Ruby (RubyGems) | `Gemfile.lock` |
| PHP (Packagist) | `composer.json`, `composer.lock` |

## How It Works

1. Reads your dependency manifest
2. Parses package names + versions
3. Batch-queries [OSV.dev](https://osv.dev) (Google's open vulnerability database)
4. Displays results with severity, CVE IDs, and fix versions

No data is stored. No telemetry. Runs entirely on your machine.

## All Flags

| Flag | Description |
|------|-------------|
| `file` | Path to manifest file (auto-detected if omitted) |
| `-e`, `--ecosystem` | Override ecosystem detection |
| `-v`, `--verbose` | Show vulnerability summaries in table |
| `-d`, `--dir` | Directory to scan (default: `.`) |
| `--json` | Output results as JSON |
| `--sarif` | Output results as SARIF v2.1.0 |
| `--recursive` | Scan all manifest files in directory tree |
| `--ignore-file` | Path to ignore file (default: `.pinaka-ignore`) |
| `--fail-on` | Exit 1 only if vulns at this severity or above (default: `any`) |
| `--version` | Show version |

## Built by

[Parth Shukla](https://pinaka.sh)

## License

MIT
