Getting started

Essential information to help you get set up with VibeScan to secure your dependencies natively.

Installation guide

Downloading VibeScan

1. Open your terminal and install via pip:

pip install vibescan

Or clone the repository and install from source:

git clone https://github.com/AbinVarghexe/vibescan.git
cd vibescan
pip install -e .

You can also install via npm:

npm install -g vibescan

Or run with Docker:

docker pull vibescan/vibescan:latest
docker run --rm -v $(pwd):/app vibescan/vibescan:latest

Note: Requires Python 3.7 or higher. Ensure that you have an updated version of pip installed.

Basic Usage

Once VibeScan is installed, you can scan any directory containing a package.json (npm) or requirements.txt (PyPI) file.

# Scan the current directory
vibescan

# Scan with debug output
vibescan --debug

# Scan a specific path
vibescan check /path/to/project

Implementing in Workflow

After installing VibeScan, plug it into your automated deployment systems to block hallucinated packages.

Add it as a pre-commit hook:

repos:
  - repo: https://github.com/AbinVarghexe/vibescan
    rev: v0.1.0
    hooks:
      - id: vibescan

Or integrate into a CI/CD pipeline:

- name: Run VibeScan
  run: |
    pip install vibescan
    vibescan check .

Tip: If VibeScan detects critical risks (score ≥ 60), it exits with code 1, purposefully failing the pipeline and protecting your production environment.

Configuration

VibeScan works out of the box with sensible defaults. You can customize its behavior using CLI flags.

CLI Flags

# Scan current directory (default)
vibescan

# Scan a specific project
vibescan /path/to/project

# Enable debug logging
vibescan --debug

Risk Scoring Thresholds

VibeScan categorizes dependencies into three risk levels based on the calculated score:

Scoring Factors

Supported Dependency Files

CI/CD Integration

VibeScan is designed to run as a gate in your deployment pipelines. Any critical finding (score ≥ 60) causes the process to exit with code 1, blocking the build.

GitHub Actions

name: VibeScan Dependency Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  vibescan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install VibeScan
        run: pip install vibescan
      - name: Scan dependencies
        run: vibescan check .

GitLab CI

vibescan:
  stage: test
  image: python:3.11-slim
  script:
    - pip install vibescan
    - vibescan check .

Pre-Commit Hook

repos:
  - repo: https://github.com/AbinVarghexe/vibescan
    rev: v0.1.0
    hooks:
      - id: vibescan
        name: VibeScan dependency check
        entry: vibescan check .
        language: python
        pass_filenames: false

Docker

Run VibeScan in any pipeline that supports Docker:

docker run --rm -v $(pwd):/app vibescan/vibescan:latest

Tip: The exit code behavior makes VibeScan a drop-in gate for any CI system. If any dependency scores ≥ 60, the process returns exit code 1.

Architecture

VibeScan follows a simple modular pipeline. Each scan flows through four stages:

Module Overview

cli.py — Entry Point

The CLI parses arguments, discovers package.json and requirements.txt in the target directory, and orchestrates the scan pipeline. It calls each module in sequence and exits with code 1 if critical issues are found.

parsers.py — Dependency Extraction

Reads and normalizes dependency files into a unified format:

# Each dependency is returned as:
{"name": "requests", "version": "==2.31.0", "ecosystem": "pypi"}

# Supported parsers:
# - parse_package_json()  →  reads dependencies + devDependencies
# - parse_requirements_txt()  →  reads all non-comment lines

checkers/ — Verification Layer

Two checker modules validate each dependency:

• registry_checker.py — Queries npm (registry.npmjs.org) and PyPI (pypi.org/pypi/) APIs to verify package existence, creation date, and download counts.
• typosquat_checker.py — Uses difflib.SequenceMatcher to compare package names against a curated list of popular packages. A similarity ratio ≥ 0.8 flags the dependency as a typosquat.

scorer.py — Risk Calculation

Aggregates signals from the checkers into a single 0–100 risk score. See the Scoring Factors table above for the full breakdown.

reporter.py — Output & Exit Code

Groups results into Safe, Suspicious, and Critical categories using colorized terminal output via colorama. Returns False if any critical packages exist, which causes the CLI to exit with code 1.

Project Structure

vibescan/
├── __init__.py             # Package init
├── cli.py                  # CLI entry point (argparse)
├── parsers.py              # package.json & requirements.txt parsers
├── scorer.py               # Risk score calculator (0-100)
├── reporter.py             # Colorized terminal output
└── checkers/
    ├── __init__.py
    ├── registry_checker.py # npm + PyPI API verification
    └── typosquat_checker.py# Name similarity detection