carrot-scan

Command-line tool for detecting vulnerabilities in files and directories.
GitHub Repository

A fast, extensible, and plugin-driven code scanner for JavaScript, TypeScript, and any other file in your project.
It evaluates code quality, complexity, security vulnerabilities, and more, producing a single aggregated score (0–100) and actionable feedback.

Table of Contents

• Features
• Installation
• Usage
• Plugin Management
• API
• Plugin Development
• Configuration
• Contributing
• Support
• License

Features

• 🧠 AI-powered scanning: Uses a lightweight, local AI model to detect potentially malicious code.
• Datenbank für Exploits Exploit-DB-Integration: Sucht in der OSV-Datenbank nach bekannten Schwachstellen in Ihren Abhängigkeiten.
• 🛡️ Critical patterns: Immediately fails on destructive or remote‐execution hooks (rm -rf, include(), eval(), etc.).
• 📏 ESLint integration: Runs ESLint (v9+) with recommended rules on JS/TS files.
• 🔢 Cyclomatic complexity: Uses typhonjs-escomplex to penalize high-complexity code.
• 🔍 AST-based security: Leverages @nodesecure/js-x-ray to detect injection patterns.
• 🌐 Multi-language rules: Integrates Semgrep OWASP Top Ten rules for 35+ languages.
• 🔎 Heuristic scanning: Regex-based patterns for generic vulnerabilities across all file types.
• 🛠️ Dependency audit: Runs npm audit and scores known CVEs.
• ⚙️ Plugin architecture: Easily add or remove checks by dropping in plugins under plugins/.
• 🐳 Dockerfile scanning: Checks for common misconfigurations in Dockerfile.

Recent Improvements

• Enhanced CLI: Added a new outdated command to check for outdated dependencies.
• New Plugin: Added a new dockerfile plugin to check for common misconfigurations in Dockerfile.
• Performance Boost: Parallelized plugin execution and implemented file content caching to improve performance.
• CI/CD Pipeline: Implemented a GitHub Actions workflow to automatically test and lint the code.
• Code Refactoring: Refactored the code for better maintainability and readability.

Installation

Install globally via npm:

1npm install -g carrot-scan

During development:

1git clone https://github.com/SonoTommy/carrot-scan.git
2cd carrot-scan
3npm install
4npm link

Usage

1carrot-scan [options] <target>

• <target>: File or directory to scan (defaults to current folder).
• -f, --fast : Quick scan (ESLint + heuristics only).
• -c, --complete : Full scan (all checks).
• -j, --json : Output machine-readable JSON.
• -v, --version : Show the installed version of carrot-scan.
• --verbose: Output detailed logs during scanning.

Examples

1# Fast lint + heuristics on current folder
2carrot-scan -f
3
4# Full scan on src/ directory
5carrot-scan src/ -c
6
7# JSON output for CI pipelines
8carrot-scan . -c --json > report.json

Supply-Chain (SBOM) Generation

Generate a Software Bill of Materials (SBOM) with embedded vulnerability information from the OSV public API. Supports CycloneDX XML and SARIF formats.

1# Generate CycloneDX SBOM for the current directory (default)
2carrot-scan sbom .
3
4# Generate SARIF output instead of XML
5carrot-scan sbom . --sarif

Doctor Command

Check for potential issues with your carrot-scan setup.

1carrot-scan doctor

Outdated Command

Check for outdated dependencies.

1carrot-scan outdated

Plugin Management

carrot-scan provides commands to manage its plugins:

• list: List all available plugins.
• enable <plugin-name>: Enable a plugin.
• disable <plugin-name>: Disable a plugin.
• create <plugin-name>: Create a new plugin from a template.

API

Programmatic Usage

Use carrot-scan programmatically in your own projects.

1import { scan } from 'carrot-scan';
2
3(async () => {
4  const result = await scan('src/', { mode: 'complete' });
5  console.log(result);
6})();

REST API

The REST API allows you to run scans via HTTP.

• POST /scan: Run a scan.
  • Body: { "target": "./src", "mode": "fast" }
• GET /scan/stream: Get real-time scan results using Server-Sent Events.
  • Query Params: target, mode

For more details, see the OpenAPI specification.

Plugin Development

Plugins are the core of carrot-scan. To create a new plugin, run:

1carrot-scan plugin create my-plugin

This will generate a new plugin file in the plugins/ directory. A plugin is a class that extends Plugin and implements two methods:

• applies(file: string): A static method that returns true if the plugin should be run on the given file.
• run(file: string, context: object): An async method that performs the scan and returns an array of issues.

See the existing plugins for examples.

Configuration

Create a carrot-scan.config.js file in your project root to customize carrot-scan.

1// carrot-scan.config.js
2export default {
3  weights: {
4    eslint: 1.5,
5    xray: 10,
6  },
7  thresholds: {
8    complexity: 12,
9  },
10  plugins: {
11    semgrep: { enabled: false },
12  },
13};

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Development

To get started with development:

1. Clone the repository:

   1git clone https://github.com/SonoTommy/carrot-scan.git

2. Install dependencies:

   1cd carrot-scan
   2npm install

3. Link the package to use the carrot-scan command globally:

   1npm link

Pull Requests

When submitting a pull request, please make sure to:

• Follow the existing code style.
• Add tests for your changes.
• Update the documentation if necessary.
• Run npm test and npm run lint before submitting.

Support

If you find carrot-scan useful, please consider supporting the project.

License

MIT