{"_id":"@ankur700/npm-scan","name":"@ankur700/npm-scan","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@ankur700/npm-scan","version":"1.0.0","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"npm-scan":"bin/npm-scan.js"},"repository":{"type":"git","url":"git+https://github.com/ankur700/npm-scan.git"},"bugs":{"url":"https://github.com/ankur700/npm-scan/issues"},"homepage":"https://github.com/ankur700/npm-scan#readme","engines":{"node":">=18"},"scripts":{"build":"bun build --minify --sourcemap --target=node ./src/index.ts --outdir ./dist","scan":"node ./bin/npm-scan.js","test":"bun test","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier --write .","format:check":"prettier --check .","prepare":"bun run build","prepublishOnly":"bun run build"},"publishConfig":{"access":"public","tag":"latest"},"keywords":["npm","scan","dependencies","vulnerabilities","security"],"author":"Ankur Singh","contributors":["Subash Rijal"],"license":"GPL-3.0-only","dependencies":{"chalk":"^5.6.2","figlet":"^1.11.2","inquirer":"^14.0.2","listr":"^0.14.3","execa":"^9.6.1"},"devDependencies":{"@eslint/js":"^10.0.1","@types/bun":"latest","@types/execa":"^2.0.2","@types/figlet":"^1.5.2","@types/inquirer":"^9.0.0","@types/listr":"^0.14.1","eslint":"^10.8.0","eslint-config-prettier":"^10.1.8","eslint-plugin-security":"^4.0.1","globals":"^17.7.0","prettier":"^3.9.6","typescript-eslint":"^8.65.0"},"peerDependencies":{"typescript":"^5"},"_id":"@ankur700/npm-scan@1.0.0","_integrity":"sha512-UyyYVEE7+2Ptm4AcgPAHV1zWcYdRja1iaRNNXlZDCcpQ3lbGhFcedZznFMIozV7DZfb1HSpTmwM6iAih5EcI5Q==","_nodeVersion":"24.3.0","_npmVersion":"10.8.3","shasum":"bd84bfcb8904edbabbec7d64033f294898b02a6e","dist":{"integrity":"sha512-UyyYVEE7+2Ptm4AcgPAHV1zWcYdRja1iaRNNXlZDCcpQ3lbGhFcedZznFMIozV7DZfb1HSpTmwM6iAih5EcI5Q==","shasum":"bd84bfcb8904edbabbec7d64033f294898b02a6e","tarball":"https://registry.npmjs.org/@ankur700/npm-scan/-/npm-scan-1.0.0.tgz","fileCount":8,"unpackedSize":2311927,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCJToa3cLoi5+SNTkruslRiPmj4/J6+sCpbg1doPoe9QAIgCpIxSnuvZdVYO61VXhUwSf66zUrbR7vILBlMdTStxFo="}]},"_npmUser":{"name":"ankur700","email":"abishek.singh.chauhan@gmail.com"},"directories":{},"maintainers":[{"name":"ankur700","email":"abishek.singh.chauhan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/npm-scan_1.0.0_1785097728170_0.011557874238310228"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-26T20:28:48.055Z","1.0.0":"2026-07-26T20:28:48.340Z","modified":"2026-07-26T20:28:48.502Z"},"maintainers":[{"name":"ankur700","email":"abishek.singh.chauhan@gmail.com"}],"homepage":"https://github.com/ankur700/npm-scan#readme","keywords":["npm","scan","dependencies","vulnerabilities","security"],"repository":{"type":"git","url":"git+https://github.com/ankur700/npm-scan.git"},"contributors":["Subash Rijal"],"author":"Ankur Singh","bugs":{"url":"https://github.com/ankur700/npm-scan/issues"},"license":"GPL-3.0-only","readme":"# npm-scan\n\n> An interactive, multi-package-manager dependency security scanner for Node.js and Bun projects.\n\n`npm-scan` is a powerful command-line tool designed to audit project dependencies for known security vulnerabilities (CVEs), track published dates, separate direct dependencies from transitive dependencies, and export detailed JSON security reports.\n\nPowered by Google's **Open Source Insights API** (`deps.dev`), `npm-scan` provides real-time vulnerability data, CVSS v3 severity scores, and dependency breakdown across `npm`, `yarn`, `pnpm`, and `bun`.\n\n---\n\n## ✨ Features\n\n- 🌐 **GitHub Repo & Folder Scanning**: Scan any public/accessible GitHub repository URL or any absolute/relative local directory path (`file://`, `/path/to/project`) without needing to navigate into the folder.\n- 🔍 **Vulnerability Scanning**: Fetches up-to-date security advisories, CVSS v3 scores, and vulnerability titles using the `deps.dev` API.\n- 🎯 **Direct vs. Transitive Detection**: Automatically categorizes packages as **🎯 DIRECT** (`dependencies` / `devDependencies`) or **🔗 TRANSITIVE** (nested sub-dependencies).\n- 🗃️ **Multi-Package Manager Support**: Seamlessly detects and parses:\n  - **npm** (`package-lock.json`)\n  - **Yarn** (`yarn.lock`)\n  - **pnpm** (`pnpm-lock.yaml`)\n  - **Bun** (`bun.lockb` / `package.json` fallback)\n- 💬 **Interactive & Non-Interactive CLI**:\n  - **Interactive Mode**: Guided terminal prompts using `inquirer` for command selection, target folder/URL input, cache clearing, and report saving.\n  - **Scripting Mode**: Command-line subcommands and flags for automated execution in CI/CD pipelines.\n- ⚡ **Smart SHA-256 Caching**: Computes lockfile SHA-256 fingerprints to cache API responses locally (`.npm-scan-cache.json`), preventing redundant network requests.\n- 📄 **Exportable Security Reports**: Saves complete or filtered vulnerability reports as structured JSON files for auditing.\n- 📅 **Dependency Insights**: Identifies the oldest installed packages to help address technical debt.\n\n---\n\n## 📦 Installation\n\n### Global Installation\n\nUsing **npm**:\n```bash\nnpm install -g npm-scan\n```\n\nUsing **bun**:\n```bash\nbun install -g npm-scan\n```\n\nUsing **yarn**:\n```bash\nyarn global add npm-scan\n```\n\nUsing **pnpm**:\n```bash\npnpm add -g npm-scan\n```\n\n### Direct Execution (Without Installing)\n\n```bash\nnpx npm-scan\n# or\nbunx npm-scan\n```\n\n---\n\n## 🚀 Usage\n\n### 1. Interactive Mode\n\nRun `npm-scan` without any arguments to launch the interactive prompt wizard:\n\n```bash\nnpm-scan\n```\n\nYou will be presented with a menu to:\n1. **Choose a command**:\n   - `Scan dependencies`: Complete security scan of direct and/or transitive dependencies.\n   - `List all installed packages and report`: Displays all installed packages across the lockfile.\n   - `Generate report for vulnerable packages`: Scans and isolates packages with active security advisories.\n   - `Show help`: Displays usage guidance.\n2. **Target repository or folder**: Enter a GitHub repo URL (e.g. `https://github.com/expressjs/express`) or local project directory path / `file://` URL (leave blank for current directory).\n3. **Clear cache** option.\n4. **Direct dependencies only** toggle.\n5. **Save report to disk** prompt with custom filename selection.\n\n---\n\n## 2. Command Line Interface (CLI)\n\n```bash\nnpm-scan <command> [options] [url|path]\n```\n\n#### Available Commands\n\n| Command | Description |\n| :--- | :--- |\n| `scan` | Scans project dependencies for vulnerabilities (scans transitive by default). |\n| `all-installed` | Lists all installed packages parsed from the lockfile. |\n| `generate-report` | Performs a security scan and displays/saves only vulnerable packages. |\n| `help` | Displays help information and usage examples. |\n\n---\n\n### 🎛️ CLI Options & Flags\n\n| Flag | Short / Alias | Description | Default |\n| :--- | :--- | :--- | :--- |\n| `--url <url\\|path>` | `-u`, `--path`, `-p` | GitHub repo URL or local project folder path / `file://` URL. | Current directory (`.`) |\n| `--direct-only` | | Restricts scan to direct dependencies in `package.json`. | `false` |\n| `--full` | | Includes all direct and transitive dependencies in the scan. | `true` (for `scan`) |\n| `--clear-cache` | `--invalidate-cache` | Clears local cache before running the scan. | `false` |\n| `--cache-file <path>` | | Path to custom cache file. | `.npm-scan-cache.json` |\n| `--save [filename]` | | Saves the scan report to a JSON file on disk. | `security-scan.json` |\n| `--help` | `-h` | Shows usage instructions and exit. | |\n\n---\n\n## 💡 Examples\n\n#### Scan a GitHub repository\n```bash\nnpm-scan scan --url https://github.com/expressjs/express\n# or positional URL\nnpm-scan https://github.com/expressjs/express\n```\n\n#### Scan a local project directory or file URL\n```bash\nnpm-scan scan --url /Users/ankur/projects/my-app\nnpm-scan scan --url file:///Users/ankur/projects/my-app\n```\n\n#### Scan direct dependencies only\n```bash\nnpm-scan scan --direct-only\n```\n\n#### Scan all dependencies (full transitive tree) and clear cache\n```bash\nnpm-scan scan --full --clear-cache\n```\n\n#### Generate a vulnerability report for a remote repo and save to JSON\n```bash\nnpm-scan generate-report --url https://github.com/facebook/react --save report.json\n```\n\n#### Use a custom cache file location\n```bash\nnpm-scan scan --cache-file .cache/security-cache.json\n```\n\n#### List all installed packages in project lockfile\n```bash\nnpm-scan all-installed\n```\n\n---\n\n## 📊 JSON Report Output Format\n\nWhen using `--save` or confirming save in interactive mode, `npm-scan` generates a structured JSON report:\n\n```json\n{\n  \"scanDate\": \"2026-07-21T21:17:00.000Z\",\n  \"summary\": {\n    \"totalPackages\": 420,\n    \"directDependencies\": 5,\n    \"transitiveDependencies\": 415,\n    \"vulnerablePackages\": 1,\n    \"vulnerableDirect\": 0,\n    \"vulnerableTransitive\": 1\n  },\n  \"results\": [\n    {\n      \"package\": \"example-pkg\",\n      \"currentVersion\": \"1.2.3\",\n      \"dependencyType\": \"transitive\",\n      \"publishedAt\": \"2021-05-10T12:00:00Z\",\n      \"isDefault\": true,\n      \"vulnerabilities\": [\n        {\n          \"id\": \"GHSA-xxxx-xxxx-xxxx\",\n          \"title\": \"Prototype Pollution in example-pkg\",\n          \"severity\": \"high\",\n          \"cvss\": 7.5,\n          \"summary\": \"A prototype pollution flaw allows attackers to modify object prototypes...\"\n        }\n      ],\n      \"vulnerabilityCount\": 1\n    }\n  ]\n}\n```\n\n---\n\n## 💻 Programmatic Usage (TypeScript / Node.js API)\n\n`npm-scan` exports the `Scanner` class and `main` function for programmatic use in Node.js or TypeScript projects:\n\n```typescript\nimport Scanner from 'npm-scan';\nimport type { DependencyResult } from 'npm-scan/dist/types';\n\nconst scanner = new Scanner();\n\n// Scan project dependencies\nconst results: DependencyResult[] = await scanner.scanDependencies(\n  './package.json',\n  true, // includeTransitive\n  { clearCache: false }\n);\n\n// Print formatted console report\nscanner.generateReport(results);\n\n// Save report to disk\nscanner.saveResults(results, 'security-report.json');\n```\n\n---\n\n## 🛠️ Development & Building\n\n### Requirements\n- **Node.js** >= 18 or **Bun** >= 1.0\n\n### Local Setup\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/ankur700/npm-scan.git\n   cd npm-scan\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   bun install\n   ```\n\n3. **Build the CLI executable**:\n   ```bash\n   bun run build\n   ```\n\n4. **Run the test suite**:\n   ```bash\n   bun run test\n   ```\n\n5. **Test locally**:\n   ```bash\n   bun run check\n   # or\n   node ./bin/npm-scan.js help\n   ```\n\n---\n\n## 🤝 Contributing\n\nContributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/ankur700/npm-scan/issues).\n\n### How to Contribute\n\n1. **Fork the Repository**: Click the **Fork** button at the top right of the GitHub repository page.\n2. **Clone Your Fork**:\n   ```bash\n   git clone https://github.com/YOUR-USERNAME/npm-scan.git\n   cd npm-scan\n   ```\n3. **Create a Working Branch**:\n   ```bash\n   git checkout -b feature/amazing-feature\n   # or for bug fixes:\n   git checkout -b fix/issue-description\n   ```\n4. **Install Dependencies**:\n   ```bash\n   bun install\n   ```\n5. **Make Your Changes**: Add your feature or fix in the `src/` directory. Ensure your code follows the strict TypeScript rules.\n6. **Build and Test**:\n   ```bash\n   # Compile TypeScript & bundle\n   bun run build\n\n   # Verify the CLI works\n   bun run check\n   ```\n7. **Commit Your Changes**: Use descriptive commit messages.\n   ```bash\n   git commit -m \"feat: add support for custom output format\"\n   ```\n8. **Push to GitHub**:\n   ```bash\n   git push origin feature/amazing-feature\n   ```\n9. **Submit a Pull Request (PR)**: Open a PR against the `main` branch of `ankur700/npm-scan` explaining your changes and motivation.\n\n### Guidelines\n\n- Keep code typed strictly in TypeScript.\n- Follow existing CLI UX and formatting conventions.\n- Ensure error handling is clean and informative.\n\n---\n\n## 📜 License\n\nThis project is licensed under the **GPL-3.0-only** License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## 👤 Author\n\n**Ankur Singh**\n- GitHub: [@ankur700](https://github.com/ankur700)\n","readmeFilename":"README.md","_rev":"1-34cf110b4e7bca0888da026ae5825a39"}