# pinaka-scan — Codebase Context Prompt

## What this project is
`pinaka-scan` is a CLI-based open-source dependency vulnerability scanner built in Python.
It is the open-source, free alternative to Snyk — no API key, no signup, no telemetry.
It queries Google's OSV.dev (Open Source Vulnerabilities) database in batch to find known
vulnerabilities in project dependencies across multiple ecosystems.

It is published as a PyPI package (`pip install pinaka-scan`) and is also the engine
powering the web version at https://pinaka.sh/dependency-scan.

## Repo structure
pinaka_scan/
├── __init__.py       # Package init, version export
├── cli.py            # Entry point — argparse CLI, orchestrates scan flow, handles exit codes
├── parsers.py        # Manifest parsers — reads requirements.txt, package.json, go.mod, Cargo.toml, etc.
└── scanner.py        # Core logic — queries OSV.dev API, processes vulnerability results, formats output
pyproject.toml        # Package metadata, dependencies, entry point definition
README.md             # User-facing documentation

## Architecture — how it works end to end
1. User invokes `pinaka-scan [file] [flags]` via CLI
2. `cli.py` parses args, auto-detects or accepts explicit manifest file path
3. `parsers.py` reads the manifest and extracts `(package_name, version, ecosystem)` tuples
4. `scanner.py` batch-queries the OSV.dev API (`https://api.osv.dev/v1/querybatch`) with the extracted packages
5. OSV.dev returns vulnerability records — scanner processes severity, CVE IDs, fix versions
6. Output is rendered to stdout (human-readable table OR JSON if `--json` flag is set)
7. Exit code is set based on findings and `--fail-on` threshold (0 = clean, 1 = vulns found, 2 = error)

## Supported ecosystems and their manifest files
| Ecosystem   | Files parsed                                        |
|-------------|-----------------------------------------------------|
| PyPI        | requirements.txt, Pipfile.lock                      |
| npm         | package.json, package-lock.json, yarn.lock          |
| Go          | go.mod, go.sum                                      |
| Rust        | Cargo.toml, Cargo.lock                              |
| RubyGems    | Gemfile.lock                                        |
| Packagist   | composer.json, composer.lock                        |

## CLI flags
- (no args) — auto-detect manifest in current directory
- `[file]` — scan a specific manifest file
- `-v` — verbose output, include vulnerability descriptions
- `--json` — output as JSON (for CI pipelines or programmatic consumption)
- `--fail-on [critical|high|medium|low]` — only exit 1 if vulns at or above this severity exist
- `-e [ecosystem]` — manually override ecosystem detection

## Exit codes
- `0` — no vulnerabilities found (or none at/above --fail-on threshold)
- `1` — vulnerabilities found at or above threshold
- `2` — scan error (network failure, parse failure, invalid manifest)

## External dependency
- **OSV.dev API** (`https://api.osv.dev/v1/querybatch`) — Google's open vulnerability database
  - No authentication required
  - Batch query format: POST with list of `{package: {name, ecosystem}, version}` objects
  - Returns vulnerability records with severity, aliases (CVE IDs), affected ranges, fix versions

## Design principles
- Zero telemetry — nothing leaves the machine except the OSV.dev query
- No API keys, no accounts, no rate limits
- Single-purpose: scan dependencies, report vulnerabilities, exit with meaningful codes
- CI/CD first — JSON output and exit codes are first-class features, not afterthoughts

## What this is NOT
- Not a SAST tool (no source code analysis)
- Not a container scanner (no image/layer scanning)
- Not a license compliance tool
- Not a secrets scanner
- Strictly: dependency manifest → OSV.dev lookup → vulnerability report

## Owner context
Built by Parth Shukla (https://pinaka.sh). This is the open-source distribution of the
scanning engine that powers Pinaka's commercial/web platform. Changes to this repo may
eventually be reflected in the Pinaka platform. Treat this codebase as production-grade
open-source with a real user base on PyPI.

## When working on this codebase
- The primary language is Python. Follow PEP8. Use type hints.
- `parsers.py` is the most likely place to add new ecosystem support — each parser is a function
  that takes a file path and returns a list of `(name, version, ecosystem)` tuples
- `scanner.py` owns the OSV.dev integration — any changes to query logic, response parsing,
  or severity mapping happen here
- `cli.py` is the user-facing surface — keep it thin, delegate to scanner and parsers
- `pyproject.toml` defines the `pinaka-scan` entry point — do not rename the CLI command
  without updating this
- When adding a new ecosystem, update: parsers.py (parser function) + cli.py (auto-detect logic)
  + README.md (supported ecosystems table)
- All network calls go through OSV.dev only — do not introduce new external dependencies
  without strong justification
- Test against real manifests, not mocked ones — OSV.dev is free and available, use it
