Skip to content

maiductuan/code-security-scanner

BranchesTags

Repository files navigation

🚀 DeepScan: The Ultimate Open-Source SAST & DevSecOps Scanner

The 100% Free, Lightning-Fast Alternative to Commercial SAST Tools.
Zero False Positives Architecture • AST-Powered Context • AI Auto-Remediation

npm version License: MIT Node.js PRs Welcome DevSecOps

DeepScan is a next-generation open-source security & code quality scanner built for modern DevSecOps pipelines. It combines Static Application Security Testing (SAST), Software Composition Analysis (SCA), and Secrets Detection into a single, blazing-fast CLI tool.

Tired of commercial tools like SonarQube, Checkmarx, or Semgrep drowning your CI/CD in false positives? DeepScan uses Tree-sitter AST parsing and Semantic Context Analysis to reduce false alerts by over 80% compared to traditional regex-based scanners.

✨ Why Choose DeepScan? (Features)

🛡️ Enterprise-Grade SAST (Static Analysis)

  • Injection Detection — Catch SQLi, Command Injection, Code Injection, and SSRF.
  • XSS & Frontend Security — Deep DOM analysis (innerHTML, document.write, React/Vue sinks).
  • Advanced Secrets Detection — Flag hardcoded passwords, API keys, and high-entropy tokens with zero test-file noise.
  • Crypto & Auth — Prevent weak hashing (MD5/SHA1), insecure JWTs, and session misconfigurations.

📊 Code Quality & Clean Code

  • Complexity Analysis — Enforce Cyclomatic & Cognitive complexity limits.
  • Code Duplication — AST-powered semantic duplicate detection.
  • Code Smells — Catch magic numbers, empty catch blocks, and tech debt (TODO/FIXME).

🔗 SCA & Dependency Scanning (Supply Chain Security)

  • Universal Package Support — npm, pip, Maven, Go modules, Cargo, Composer, RubyGems.
  • OSV Database Integration — Real-time vulnerability checking using Google's Open Source Vulnerabilities.

🧠 Next-Gen Capabilities (The "Secret Sauce")

  • AST-Powered False Positive Reduction — DeepScan understands code. It knows the difference between a password in a test fixture vs. production code.
  • Cross-File Taint Tracking — Follows user input from route handlers down to database sinks.
  • AI-Assisted Remediation — Local (Ollama) or Cloud (OpenAI/Anthropic) LLM integration to automatically suggest fixes and weed out edge-case false alarms.

🌍 Universal Language Support

Scan your entire monorepo without installing 10 different tools:
JavaScript, TypeScript, Python, Java, Go, C/C++, C#, PHP, Ruby, Rust, Kotlin, Swift

🚀 Quick Start

Installation

Install globally from npm:

npm install -g deepscan-cli

Basic Usage

# Initialize configuration
deepscan init

# Scan current directory
deepscan scan

# Scan specific path
deepscan scan ./src

# Scan with specific format output
deepscan scan ./src --format json --output results.json

Output Formats

# Console (default) — Beautiful terminal output
deepscan scan ./src

# JSON — Machine-readable
deepscan scan ./src --format json

# CSV — Spreadsheet compatible
deepscan scan ./src --format csv --output results.csv

# HTML — Interactive dashboard report
deepscan scan ./src --format html --output report.html

# SARIF — GitHub Code Scanning compatible
deepscan scan ./src --format sarif --output results.sarif

⚙️ Configuration

Create a .deepscan.yml in your project root:

version: "1.0"

scanners:
  security:
    enabled: true
    severity: [critical, high, medium]
  quality:
    enabled: true
    thresholds:
      maxComplexity: 15
      maxFileLength: 500
      maxFunctionLength: 50
  cve:
    enabled: true
    sources: [osv]
    failOnSeverity: critical

rules:
  include: ["*"]
  exclude:
    - quality/console-log
  custom:
    - ./my-rules/*.yml

paths:
  exclude:
    - node_modules/**
    - dist/**
    - "**/*.test.ts"

output:
  format: json
  file: deepscan-results.json

# AI Validation (optional, OFF by default)
ai:
  enabled: false
  provider: openai  # openai, anthropic, ollama

Presets

# Use a preset for common project types
deepscan scan --preset node-api
deepscan scan --preset python-web
deepscan scan --preset java-spring
deepscan scan --preset minimal

📝 Custom Rules

Create custom rules in YAML format:

# my-rules/no-eval.yml
rules:
  - id: custom/no-eval
    name: "Prohibit eval() usage"
    description: "eval() is dangerous and should never be used"
    category: security
    severity: high
    confidence: high
    cwe: [CWE-95]
    languages: [javascript, typescript]
    patterns:
      - regex: "\\beval\\s*\\("
        message: "eval() usage detected"
    fix:
      description: "Use JSON.parse() or a safe parser"
    tags: [injection]
    references:
      - https://cwe.mitre.org/data/definitions/95.html
# Use custom rules
deepscan scan --rules ./my-rules/

🔧 CLI Reference

Scan Command Options (deepscan scan)

Option Shortcut Description Default Example
--scanners <names> -s Comma-separated list of scanner engines to run (security, quality, cve) security,quality,cve deepscan scan -s security,cve
--security N/A Run security scanner only N/A deepscan scan --security
--quality N/A Run quality scanner only N/A deepscan scan --quality
--cve N/A Run CVE/dependency scanner only N/A deepscan scan --cve
--format <format> -f Output format: json, csv, html, sarif, console console deepscan scan -f html
--output <file> -o Output file path (writes scan results to file) Stdout / console deepscan scan -o report.html
--severity <levels> N/A Filter findings by severity (critical, high, medium, low) All deepscan scan --severity critical,high
--include <patterns> N/A Include file patterns (comma-separated globs) All files deepscan scan --include "src/**/*.ts"
--exclude <patterns> N/A Exclude file patterns (comma-separated globs) Config defaults deepscan scan --exclude "tests/**"
--rules <path> N/A Path to custom rules directory N/A deepscan scan --rules ./custom-rules
--deep N/A Enable deep analysis (taint tracking, semantic analysis) false deepscan scan --deep
--ai N/A Enable AI-assisted validation (requires API key) false deepscan scan --ai
--ai-provider <p> N/A AI provider: openai, anthropic, ollama openai deepscan scan --ai --ai-provider ollama
--parallel <n> N/A Number of parallel execution workers 4 deepscan scan --parallel 8
--incremental N/A Only scan changed files (git-based) false deepscan scan --incremental
--preset <name> N/A Use preset config (node-api, python-web, java-spring, minimal) N/A deepscan scan --preset node-api
--config <path> N/A Path to configuration file .deepscan.yml deepscan scan --config ./deepscan-ci.yml

CLI Subcommands

# Rule management
deepscan rules list                     # List all loaded rules
deepscan rules list --category injection # Filter rules by category
deepscan rules low security/sql-injection  # Show detailed rule details
deepscan rules categories               # Show all available categories

# Configuration
deepscan init                           # Initialize standard config file
deepscan init --preset node-api         # Initialize config with preset

# Report conversion
deepscan report convert results.json --to html --output report.html

🤖 AI-Assisted Validation

Enable AI validation to reduce false positives (optional):

# Set API key
export OPENAI_API_KEY=sk-...
# or
export ANTHROPIC_API_KEY=sk-ant-...

# Run with AI validation
deepscan scan --ai --ai-provider openai

# Or use local Ollama
deepscan scan --ai --ai-provider ollama
# .deepscan.yml
ai:
  enabled: true
  provider: openai  # or anthropic, ollama
  model: gpt-4o-mini
  maxFindings: 20

🏗️ Architecture

CLI → Pipeline → File Discovery → Language Detection
                ↓
        Scanner Engines (parallel)
        ├── Security Scanner (patterns, taint, context)
        ├── Quality Scanner (complexity, duplication, metrics)
        └── CVE Scanner (dependency parsing, OSV query)
                ↓
        Rule Engine (built-in + custom YAML rules)
                ↓
        [Optional] AI Validator
                ↓
        Reporter (JSON / CSV / HTML / SARIF / Console)

📊 Comparison

Feature DeepScan SonarQube Semgrep Trivy
SAST ✅ ✅ ✅ ❌
SCA/CVE ✅ ✅ ❌ ✅
Secrets ✅ ✅ ✅ ✅
Context-Aware ✅ ❌ ❌ ❌
Taint Analysis ✅ ✅ ✅ ❌
AI Validation ✅ ❌ ✅ ❌
Zero Infrastructure ✅ ❌ ✅ ✅
Custom Rules (YAML) ✅ ❌ ✅ ❌
HTML Report ✅ ✅ ✅ ✅
SARIF Output ✅ ✅ ✅ ✅
Free & Open Source ✅ Partial Partial ✅

🛠️ Developer & Source Guide

Note

For our strict quality standards, testing rules, and contribution workflow, please read the Contributing Guide.

This section is intended for developers and users who want to run DeepScan from source, contribute code, modify rule processing scripts, or debug CLI behaviors.

Prerequisites

  • Node.js >= 18.0.0
  • npm or yarn

Setup

Clone the repository and install all dependencies:

git clone https://github.com/your-org/code-scan-security.git
cd code-scan-security
npm install

Running from Source

You can execute DeepScan directly from source code without a build step using JIT compilation.

Important

When running through npm run dev, you must use a double dash (--) before passing arguments and options so that npm passes them correctly:

# General scanning
npm run dev -- scan ./src

# Scan with specific flags (e.g. security-only, JSON output)
npm run dev -- scan ./src --security --format json

# Run rule lists
npm run dev -- rules list

Alternatively, you can run using npx (which does not require the -- separator):

npx tsx src/bin/deepscan.ts scan ./src --security

Building the CLI

To compile the codebase into plain JavaScript for production testing or distribution:

npm run build

This compiles TypeScript source files into the dist/ directory:

  • dist/bin/deepscan.js (Executable entry point)
  • dist/index.js (Library export)

Run the compiled JavaScript CLI bundle:

node dist/bin/deepscan.js scan ./src

Testing, Linting & Typechecking

Before making changes, verify tests and static analysis pass.

# Run all tests once
npm run test

# Run tests in watch mode
npm run test:watch

# Typecheck TypeScript files
npm run typecheck

# Lint codebase (ESLint)
npm run lint

Rule & Script Development

  • To test converting a single Semgrep rule file: 
    npx tsx scripts/convert-rules.ts --input tests/fixtures/semgrep-sample.yml --output rules/built-in/converted-semgrep.yml
  • To run the full automated download/convert script:
    1. Make changes inside scripts/update-rules.ts.
    2. Execute the update script: 
      npm run rules:update
    3. Run the test suite: 
      npm run test

📊 Benchmark & Accuracy Results

To verify DeepScan's detection capability, we maintain a realistic multi-language monorepo benchmark in the examples/ directory. It includes vulnerable controllers, web views, dynamic routing, and dependency manifests alongside their secure counterparts for Node/Express/NestJS, Python/Flask/Django, Go/net/http, and PHP/Laravel.

Our automated evaluation framework measures Recall (detection coverage of ground-truth bugs) and Precision (avoidance of false alarms on clean code).

Latest Benchmark Results (v1.0)

  • Total Ground-Truth Bugs: 29
  • Recall (Detection Rate): 100.0% (29/29 bugs caught)
  • Precision (False Positive Rate): 100.0% (0 false alarms triggered)
  • F1 Score: 100.0%

Language Breakdown

Language / Framework Expected Bugs Caught (TP) Missed (FN) False Alarms (FP) Accuracy (Recall)
JavaScript / TypeScript (Express, NestJS) 13 13 0 0 100.0%
Python (Flask, Django) 7 7 0 0 100.0%
Go (net/http) 3 3 0 0 100.0%
Java (Maven, standard) 3 3 0 0 100.0%
PHP (Laravel, Blade) 3 3 0 0 100.0%

To run the accuracy evaluation script and generate the interactive evaluation-report.html dashboard:

npm run evaluate

📚 Documentation

For detailed setup and operational instructions, see:

  • Administrator Guide — System configuration, automatic ruleset updates, CLI options reference, and rule distribution.

📄 License

MIT © DeepScan Contributors

About

DeepScan is a free and open-source repository security scanner that helps developers find vulnerabilities, secrets, insecure dependencies, and misconfigurations—offering a practical alternative to many commercial security scanning tools.

Topics

scanner static-analysis security-tools vulnerability-scanner sast security-ai deep-scanning

Resources

Readme

License

Apache-2.0 license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Packages

 
 
 

Contributors

Languages