Manel — Security Health Monitor CLI

Manel is a security CLI for development environments that locally scans installed software (OS, tools, languages, databases), queries known vulnerabilities from public sources (OSV, NVD, GitHub Advisories), and generates a Security Score (0-100) with actionable recommendations.

Quick Start

# Global installation
npm install -g manel

# Or run directly
npx manel scan

# Quick status check
manel status

Installation

Prerequisites

Node.js 18+ — Download from nodejs.org
npm — Included with Node.js
Git — For installing from source

# Check versions
node --version   # Should show v18.x.x or higher
npm --version
git --version

Method 1: From npm (recommended)

npm install -g manel

Method 2: Automatic installation script

# Clone the repository
git clone https://github.com/devcristianlopez/manel.git
cd manel

# Run installer
bash setup.sh

# Or with development mode (includes test tools)
bash setup.sh --dev

The installation script:

✅ Detects your operating system
✅ Verifies/installs Node.js 18+
✅ Installs dependencies
✅ Compiles the CLI
✅ Links the manel command globally
✅ Verifies the installation

Method 3: Manual installation

git clone https://github.com/devcristianlopez/manel.git
cd manel
npm install
npm run build:cli
npm link

Method 4: npx (without installing)

npx manel scan

Available npm scripts

npm run install:global   # Compile and install globally
npm run uninstall:global # Uninstall globally
npm run setup           # Run bash setup.sh
npm run uninstall       # Run bash uninstall.sh

Verify installation

manel --version
manel status

Supported operating systems

✅ Linux (Ubuntu, Debian, Fedora, Arch)
✅ macOS
⚠️ Windows (manual installation)

Uninstallation

Method 1: Uninstallation script (recommended)

# If you are in the project directory
bash uninstall.sh

# Or with the path to the project
/path/to/manel/uninstall.sh

Script options:

bash uninstall.sh --help   # Show help
bash uninstall.sh --yes    # Skip confirmations
bash uninstall.sh --all    # Also remove installation directory

Method 2: npm

npm uninstall -g manel

Method 3: Manual

# Remove global link
npm unlink -g manel

# Or remove the executable directly
rm -f $(which manel)

After uninstalling

# Refresh shell cache
hash -r

Commands

Command	Description
`manel status`	Quick status of installed technologies
`manel scan`	Full scan: vulnerabilities + hardening + score
`manel vulnerabilities`	Vulnerabilities only (alias: `vulns`)
`manel hardening`	Hardening checks only (Linux)
`manel score`	Detailed security score
`manel updates`	Check for available updates
`manel sync`	Download offline vulnerability database (OSV)
`manel history`	Show past scan results
`manel schema`	CLI introspective JSON (AI-friendly)

Usage examples

# Quick status
manel status

# Full scan with JSON output
manel scan --format json

# Critical and high vulnerabilities only
manel vulnerabilities --severity CRITICAL,HIGH

# Hardening with output to file
manel hardening --output report.txt

# Detailed score without colors
manel score --no-color

# Check for available updates
manel updates --format json

# Download offline vulnerability DB, then scan without network
manel sync
manel scan --offline

# Review past scans
manel history --last 5

Common Workflows

1. First-time setup

# Install globally from npm
npm install -g manel

# Download the offline vulnerability database (one time)
# Auto-detects ecosystems from your installed software
manel sync

First sync takes a few minutes (npm dump is ~200 MB). Re-run weekly to stay fresh — local data is trusted for 7 days.

2. Daily security check

# Quick overview of detected technologies
manel status

# Full scan: vulnerabilities + hardening + score
manel scan

3. Focus on what matters

# Only critical and high severity findings
manel vulns --severity CRITICAL,HIGH

# Fail (exit 1) if anything critical exists — great for pre-commit hooks
manel scan --fail-on critical

4. Export & integrate

# SARIF report for GitHub Code Scanning
manel scan --format sarif --output scan.sarif

# JSON for scripts and dashboards
manel score --format json | jq .data.overall

5. Work fully offline

# Zero network requests — uses the synced local database
manel scan --offline
manel vulns --offline --severity CRITICAL

Requires manel sync beforehand. Ideal for planes, secure networks, and CI runners without internet access.

6. Track your posture over time

# List your last scans with scores and findings
manel history

# More entries, machine-readable
manel history --last 20 --format json

Standard Flags

All commands support the following flags:

Flag	Description
`-f, --format <format>`	Output format: `table`, `json`, `sarif`, `ndjson`
`-o, --output <file>`	Write output to file instead of stdout
`-s, --severity <levels>`	Filter by severity (comma-separated)
`--fail-on <severity>`	Exit with code 1 if findings >= severity
`--no-color`	Disable ANSI color output
`-q, --quiet`	Suppress non-error output
`-V, --verbose`	Enable verbose output
`--offline`	Run fully offline using local synced data (`scan`, `vulnerabilities`)

Output Formats

Format	Description	Recommended use
`table`	Formatted table with colors (default)	Interactive terminal
`json`	Pretty-printed JSON	APIs, scripts, debugging
`sarif`	Static Analysis Results Interchange Format	GitHub Code Scanning, SAST tools
`ndjson`	Newline-delimited JSON	Pipes, streaming, batch processing

Exit Codes

Code	Meaning
`0`	Success, no findings
`1`	Findings detected (vulnerabilities, hardening failures)
`2`	Internal error
`3`	Invalid input

CI/CD Examples

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g manel
      - name: Run security scan
        run: manel scan --format sarif --output scan-results.sarif --no-interactive
      - name: Upload SARIF to GitHub
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: scan-results.sarif

Pipeline with fail-on

- name: Security gate
  run: manel scan --fail-on high --no-interactive --format json

Vulnerabilities-only scan

- name: Check vulnerabilities
  run: manel vulns --severity CRITICAL,HIGH --format ndjson | jq '.severity'

Pipe Examples

# Extract critical vulnerabilities
manel scan --format json | jq '.vulnerabilities[] | select(.severity == "CRITICAL")'

# Count vulnerabilities by severity
manel scan --format json | jq '[.vulnerabilities[].severity] | group_by(.) | map({(.[0]): length}) | add'

# Filter outdated technologies
manel scan --format json | jq '.technologies[] | select(.updateAvailable == true)'

# Send results to a logging service
manel scan --format ndjson | while read line; do echo "$line" | curl -X POST -d @- https://api.example.com/logs; done

# Generate SARIF report and upload to GitHub
manel scan --format sarif -o results.sarif

# Check score only
manel score --format json | jq '.overall'

Security Score

The score is calculated with the following weighting:

Category	Weight
Operating System	15%
Hardening	15%
Tools	10%
Dependencies	30%
Databases	10%
Critical vulnerabilities	20%

Detectable Technologies

Languages and runtimes: Node.js, Python, Python 3, Java
Package managers: npm, Yarn, pnpm, pip, Maven, Gradle
Tools: Git, Docker, Docker Compose, VS Code
Databases: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQLite, pgAdmin
Operating systems: Ubuntu, Debian, Fedora, macOS, Windows

Introspective Schema

The schema command generates a JSON describing the entire CLI interface, useful for AI tools and documentation generation:

manel schema | jq '.commands[] | .name'

Local Cache & Persistence

Manel stores API responses and scan results in a local SQLite database at ~/.manel/manel.db:

Version cache (24h TTL) — latest-version lookups skip the network on repeat runs
Vulnerability cache (24h TTL) — OSV/NVD/GHSA results cached per ecosystem:package:version, avoiding API rate limits
Scan history — every scan/vulnerabilities run persists detected software, findings, and score for auditing

The first run queries external APIs; subsequent runs within 24h are network-free for cached data. Override the database location with the MANEL_DB_PATH environment variable (useful for tests and CI).

Offline Mode

For fully offline operation, download the complete OSV vulnerability database with manel sync:

manel sync                      # Auto-detect ecosystems from installed software
manel sync --ecosystem npm,PyPI # Specific ecosystems
manel sync --force              # Re-sync even if fresh (< 24h)

Where does the data come from? manel sync downloads the public OSV.dev database dumps directly from Google's servers (osv-vulnerabilities.storage.googleapis.com) and indexes them into your local SQLite at ~/.manel/manel.db. The vulnerability data is not bundled with the npm package or the repo — new CVEs are published every day, so the database is fetched on demand and stays under your control. Sizes: npm ~200MB, PyPI ~31MB, Maven ~9MB. Once synced:

manel scan --offline / manel vulns --offline make zero network requests
Without --offline, fresh local data (< 7 days) is still preferred over live API calls
API failures are negative-cached for 15 minutes, so rate-limited sources are not retried on every run

Version-range matching (introduced/fixed) is evaluated locally — no semver service needed.

Development

# Install dependencies
npm install

# Build CLI
npm run build:cli

# Run in development
node bin/manel-cli.js scan

# Run tests
npm test

# Type checking
npm run lint

Tech Stack

Layer	Technology
CLI Framework	Commander.js 15
Language	TypeScript 5
Runtime	Node.js 18+
Database	SQLite (better-sqlite3)
Tests	Vitest
External APIs	OSV, NVD, GitHub Security Advisories, npm registry, PyPI, endoflife.date

Project Structure

manel/
├── bin/
│   └── manel-cli.js           # CLI entry point
├── src/
│   ├── cli/                   # CLI framework
│   │   ├── commands/          # Command implementations
│   │   ├── output/            # Formatters (table, json, sarif, ndjson)
│   │   ├── flags.ts           # Shared flags
│   │   ├── errors.ts          # Error handling
│   │   └── index.ts           # Main entry point
│   ├── core/                  # Business logic
│   │   ├── scanner/           # Software detection
│   │   ├── security/          # Security engine
│   │   ├── update-engine/     # Version checking
│   │   ├── database/          # SQLite persistence
│   │   └── index.ts           # Barrel export
│   └── shared/                # Shared types
│       └── types.ts
├── package.json
├── tsconfig.cli.json          # TypeScript config for CLI
└── vitest.config.ts

See ARCHITECTURE.md for detailed technical documentation.

Data Sources

OSV — Open Source Vulnerabilities database
NVD — National Vulnerability Database (USA)
GitHub Security Advisories — Advisory Database
End of Life — Software support dates
npm registry — Latest npm package versions
PyPI — Latest Python package versions
GitHub Releases — Latest GitHub project releases

Contributing

See CONTRIBUTING.md for development and contribution guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
bin		bin
docs		docs
src		src
.gitignore		.gitignore
.releaserc.json		.releaserc.json
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
setup.sh		setup.sh
tsconfig.cli.json		tsconfig.cli.json
tsconfig.json		tsconfig.json
uninstall.sh		uninstall.sh
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Manel — Security Health Monitor CLI

Quick Start

Installation

Prerequisites

Method 1: From npm (recommended)

Method 2: Automatic installation script

Method 3: Manual installation

Method 4: npx (without installing)

Available npm scripts

Verify installation

Supported operating systems

Uninstallation

Method 1: Uninstallation script (recommended)

Method 2: npm

Method 3: Manual

After uninstalling

Commands

Usage examples

Common Workflows

1. First-time setup

2. Daily security check

3. Focus on what matters

4. Export & integrate

5. Work fully offline

6. Track your posture over time

Standard Flags

Output Formats

Exit Codes

CI/CD Examples

GitHub Actions

Pipeline with fail-on

Vulnerabilities-only scan

Pipe Examples

Security Score

Detectable Technologies

Introspective Schema

Local Cache & Persistence

Offline Mode

Development

Tech Stack

Project Structure

Data Sources

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages