devscan

DevScan

A developer environment security and health scanner. Detects runtimes, inspects installed packages, and surfaces known vulnerabilities and outdated dependencies — across your global environment or a specific project.

Built with Go. Designed to be scriptable, CI-friendly, and extensible.

Install

go install github.com/DevShedLabs/devscan@latest

Make sure ~/go/bin is on your $PATH. Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.)
if it isn't already:

export PATH="$HOME/go/bin:$PATH"

Then reload your shell (source ~/.zshrc) or open a new terminal.

Or build from source:

git clone https://github.com/DevShedLabs/devscan
cd devscan
go build -o devscan .

Commands

Usage

# Full health report
devscan doctor

# Audit for vulnerabilities, filter to high and above
devscan audit --severity high

# Show exactly where vulnerable packages are installed
devscan locate

# Scan a specific project
devscan doctor --path ./my-app

# Scan a project and all sub-projects up to 2 levels deep
devscan doctor --path ./my-app --depth 2

# Machine-readable output
devscan doctor --format json

# CI: exit non-zero if critical vulns found
devscan audit --severity critical

Reports

Generate a shareable report in Markdown, HTML, or JSON:

# Markdown to stdout
devscan report --md

# HTML file
devscan report --html --output report.html

# JSON file
devscan report --json --output scan.json

# Scoped to a project
devscan report --html --output report.html --path ./my-app

# Traverse sub-projects
devscan report --html --output report.html --path ./my-app --depth 2

Reports include:

• System info: OS, version, chip, architecture
• Summary cards with severity counts and scan duration
• Runtime versions with outdated status
• Vulnerabilities grouped by severity, with OSV advisory links, fixed-in versions, and fix commands
• Filesystem paths for every vulnerable package installation
• Full package inventory

Flags

--format string      Output format: table|json|compact (default "table")
--severity string    Filter by severity: critical|high|medium|low
--ecosystem string   Filter by ecosystem: npm|pypi|packagist|crates.io|go
--global             Scan global packages (default)
--project            Scan current project directory
--path string        Explicit project path to scan
--depth int          Traverse subdirectories up to this depth (0 = path only)
--no-color           Disable color output
--no-cache           Bypass cache and force a fresh advisory lookup
-o, --output string  Write report to file (report command only)

Fix Commands

When a fix is available, devscan generates the exact command to run:

Exit Codes

Useful for CI pipelines:

- name: Security scan
  run: devscan audit --severity high

Cache

Network results are cached locally to keep scans fast.

On Linux: ~/.cache/devscan/ · On Windows: %LocalAppData%\devscan\

Force a fresh lookup at any time:

devscan doctor --no-cache

Config File

Place .devscan.json in your project root or home directory:

{
  "ignore": ["left-pad"],
  "severity_threshold": "medium",
  "ecosystems": ["npm", "pypi"],
  "auto_fix": false
}

Supported Ecosystems

Vulnerability data is sourced from OSV.dev — an open, community-driven vulnerability database covering npm, PyPI, Go, crates.io, Packagist, RubyGems, and more.

Large scans (1000+ packages) are automatically chunked into batches to stay within OSV API limits.

Architecture

devscan/
  cmd/                  # CLI commands (Cobra)
  internal/
    detectors/          # Runtime detection (node, bun, python, git, php, rust, go)
    inspectors/         # Package inspection (npm, pip, composer, cargo, gomod)
    advisory/           # Vulnerability lookups (OSV.dev) with 1hr cache
    versions/           # Runtime latest-version checks with 7-day cache
    sysinfo/            # OS, chip, and architecture detection
    traverse/           # Sub-project discovery by manifest files
    output/             # Terminal renderers (table, JSON, compact)
    report/             # Export renderers (Markdown, HTML, JSON)
    schema/             # Shared types

The JSON output schema is the central contract. The CLI, and future TUI and GUI layers, are all thin wrappers on top of it.

Roadmap

• Runtime latest-version checks — Go, Node, Bun, Python, PHP, Rust, Git
• Fix commands for all supported ecosystems
• Sub-project traversal with --depth
• Filesystem paths for vulnerable packages
• System info in reports (OS, chip, arch)
• HTML and Markdown report export
• Ruby / gem support
• Homebrew package inspection
• System package managers — dpkg (Debian/Ubuntu), rpm (Fedora/RHEL), apk (Alpine)
• Baseline diff (--compare baseline.json)
• CI summary output (GitHub Actions annotations)
• --ignore flag to suppress known/accepted advisories

License

MIT