vulnerability-scanner 0.1.2

A developer-centric security toolkit that unifies multiple scanning engines (including a custom, AST-based Python scanner and Semgrep) to find OWASP Top 10 vulnerabilities. Designed for seamless integration into development workflows and CI/CD pipelines.

Vulnerability Scanner

A developer-centric, multi-engine security toolkit for Python applications.

This tool was developed as part of a Master's thesis project by Javier Ocampo at CCT College Dublin.

---

The Problem

In the modern software development lifecycle, developers are increasingly responsible for writing secure code. However, the landscape of security tools is often fragmented, complex, and difficult to integrate into a seamless workflow. This friction creates a significant barrier to the adoption of secure coding practices from the outset of a project, leading to vulnerabilities that are often discovered too late.

This project aims to solve that problem by providing a unified, intuitive, and powerful toolkit that embeds security scanning directly into the development process.

Features

• Unified Workflow: Integrates multiple scanning engines into a single, cohesive CLI interface.
• Dual-Engine Philosophy:
  • Custom Engine: A high-fidelity, Python-specific scanner built from the ground up to detect OWASP Top 10 vulnerabilities with low false positives. Uses AST parsing for deep code analysis and integrates pip-audit for dependency checking.
  • Semgrep Engine: An integrated wrapper around the industry-standard Semgrep tool, providing broad, fast, multi-language scanning capabilities based on a vast community-driven ruleset.
• Developer-Centric: Designed for ease of use by developers, providing clear, actionable feedback.
• Educational: Each finding from the Custom Engine includes an explanation of the vulnerability, potential attack scenarios, and remediation guidance, making it a valuable learning tool.
• Flexible Output: Provides results in both a human-readable table for quick assessment and a machine-readable JSON format for CI/CD integration.
• CI/CD Ready: Easily integrates into pipelines like GitHub Actions to automate security testing.
• VS Code Integration: Features a companion Visual Studio Code extension, OWASP Guardian, for real-time security feedback in the editor.

Installation

Install the tool from PyPI using pip or uv:

# With pip
pip install vulnerability-scanner

# With uv
uv pip install vulnerability-scanner

Usage

The primary command is scan. You must choose to run either the Custom Engine (--scanners) or the Semgrep Engine (--semgrep).

Running the Custom Engine

To run the Custom Engine, use the --scanners (-s) flag. You can specify a comma-separated list of scanners or use all to run every available custom scanner.

# Run all custom scanners on the current directory
vuln-scan --scanners all

# Run specific scanners on a given path
vuln-scan --scanners injection,cryptographic_failures --path ./my_project/

# Save results to a JSON file
vuln-scan --scanners all --path . --output results.json

Running the Semgrep Engine

To run the integrated Semgrep engine, use the --semgrep flag.

# Run Semgrep on the current directory
vuln-scan --semgrep

# Run Semgrep on a specific path
vuln-scan --semgrep --path ./my_project/

CI/CD Integration

The tool is designed to be used in CI/CD pipelines. You can make the scan fail if vulnerabilities of a certain severity are found, blocking insecure code from being merged.

# Fail the build if any "critical" severity issues are found
vuln-scan --scanners all --fail-on-severity critical --path .

Full Options

Usage: vuln-scan [OPTIONS]

Option	Alias	Description
--scanners	-s	Comma-separated list of custom scanners to run (e.g., injection,crypto) or all.
--semgrep		Activates the Semgrep engine. Cannot be used with --scanners.
--path	-p	File or directory to scan (defaults to current directory).
--output	-o	Optional path to save results to a JSON file.
--fail-on-severity		Fail the process if vulnerabilities of this level or higher are found (low, medium, high, critical).
--verbose	-v	Enable verbose output with detailed information about the scan.

Available Custom Scanners

The Custom Engine provides a suite of scanners, each targeting a specific category of the OWASP Top 10:

• broken_access_control
• cryptographic_failures
• injection
• insecure_design
• security_misconfiguration
• vulnerable_and_outdated_components

How It Works

The tool is architected around a core orchestrator that manages two distinct, mutually exclusive scanning engines:

1. The Custom Engine (--scanners): This engine is designed for deep, context-aware analysis of Python code. It uses Python's own Abstract Syntax Tree (AST) module to parse the code and identify complex vulnerability patterns with high accuracy. It also integrates specialized tools like pip-audit to handle dependency scanning (vulnerable_and_outdated_components).

2. The Semgrep Engine (--semgrep): This engine acts as a wrapper for the powerful Semgrep tool. It leverages Semgrep's extensive, community-curated rulesets to perform fast, broad, pattern-based analysis. This engine is excellent for catching a wide range of security "smells" and common misconfigurations.

This dual-engine approach allows you to choose the best tool for the job: deep analysis with the Custom Engine or broad coverage with Semgrep.