micro-sec-audit

v1.0.1

Published

a month ago

Zero-backend security scanner with an interactive dashboard

0High
0Medium
0Low

yohanness16

security cve vulnerability-scanner sast sca secrets-detection epss cisa-kev osv sarif dashboard audit

🔒 micro-sec-audit

Zero-Backend Security Scanner & Ultra-Lightweight Interactive Dashboard

A local-first, zero-dependency developer security tool that audits dependencies, source code vulnerabilities, exposed credentials, and infrastructure configurations — compiling findings with live threat feeds into a single-file interactive Micro-SPA dashboard.

Quick Start • How It Works • Scan Engines • Interactive Dashboard • Dev Plugins • CI/CD • CLI Reference

✨ Highlights

⚡ Zero Dependencies — Built 100% on native Node.js standard libraries. Installs and executes in milliseconds.
🌐 Live Threat Intelligence — Real-time integration with Google OSV.dev, FIRST EPSS, CISA KEV, and NIST NVD 2.0.
📊 Interactive Micro-SPA Dashboard — Self-contained HTML report (<35KB) with dark theme, interactive SVG charts, EPSS/CVSS threat matrices, and client-side live feed updates.
🛡️ 4-in-1 Scanning Matrix:
- SCA: Dependency supply chain auditor (package-lock.json, yarn.lock, pnpm-lock.yaml).
- SAST: Static analysis for XSS, SQLi, command injection, prototype pollution, ReDoS, and weak crypto.
- Secrets: 30+ regex signatures + Shannon Entropy analysis for cloud credentials, API tokens, and private keys.
- Config: Security headers, Dockerfile root/privilege checks, Kubernetes manifests, and .env misconfigurations.
🔄 Multi-Format Export — Output to SARIF 2.1.0 (GitHub Code Scanning), Markdown, JSON, or HTML.
🔌 Framework Middleware — Serve a live security dashboard at /__security inside Vite, Next.js, or Express.

🚀 Quick Start

You don't even need to clone or install the repository to run a scan:

Run instantly with `npx`

# Scan current directory and print terminal summary
npx micro-sec-audit scan .

# Scan and immediately launch the interactive HTML dashboard in your browser
npx micro-sec-audit scan . --open

# Enforce a security gate (exit with code 1 if critical or high issues exist)
npx micro-sec-audit scan . --fail-on=high

Install as a project devDependency

npm install -D micro-sec-audit

Add to your package.json scripts:

{
  "scripts": {
    "security": "micro-sec-audit scan . --open",
    "security:ci": "micro-sec-audit scan . --fail-on=critical --format=sarif --output=security.sarif"
  }
}

Then run:

npm run security

🧠 How It Works

micro-sec-audit operates on a Local-First + Direct Threat Feed execution model. It never transmits your private source code to external servers:

                  ┌─────────────────────────────────────────────────────────┐
                  │                   LOCAL SCANNING                        │
                  ├───────────────────┬─────────────────────────────────────┤
                  │ Lockfiles         │ package-lock.json, yarn.lock, pnpm  │
                  │ Source Code       │ SAST AST/regex rules (XSS, Exec)    │
                  │ Secrets           │ 30+ credential patterns & Entropy   │
                  │ Configurations    │ Docker, K8s, .env, Security Headers │
                  └───────────────────┴──────────────────┬──────────────────┘
                                                         │ Extracted Packages & CVEs
                                                         ▼
                  ┌─────────────────────────────────────────────────────────┐
                  │                 LIVE PUBLIC THREAT APIS                 │
                  ├───────────────────┬─────────────────────────────────────┤
                  │ 1. OSV.dev        │ POST https://api.osv.dev/v1/query...│
                  │ 2. FIRST EPSS     │ GET  https://api.first.org/epss...  │
                  │ 3. CISA KEV       │ GET  https://www.cisa.gov/.../kev   │
                  │ 4. NVD 2.0        │ GET  https://services.nvd.nist.gov  │
                  └───────────────────┴──────────────────┬──────────────────┘
                                                         │ Enriched Intelligence
                                                         ▼
                                          ┌─────────────────────────────┐
                                          │     COMPOSITE RISK SCORE    │
                                          │ (CVSS + EPSS + KEV + Depth) │
                                          └──────────────┬──────────────┘
                                                         │
                                  ┌──────────────────────┴──────────────────────┐
                                  ▼                                             ▼
                      Terminal Output / SARIF / JSON                Interactive HTML Dashboard

Threat Feed Integrations

OSV.dev (Google): Batch-queries vulnerability advisories matching exact ecosystem packages and versions.
FIRST EPSS: Retrieves the real-time probability ($0.0 - 1.0$) of weaponized in-the-wild exploitation.
CISA KEV (US CISA): Cross-references known actively exploited vulnerabilities.
NVD 2.0 (NIST): Enriches CVEs with CVSS v3.1 vector scores and CWE vulnerability classes.

🧮 Composite Risk Scoring Formula

Unlike basic scanners that only look at static CVSS numbers, micro-sec-audit computes an aggregated Risk Score (0–100) incorporating exploit likelihood and dependency depth:

$$\text{RiskScore} = \min\Big(100,; (\text{CVSS} \times 6.0) + (\text{EPSS} \times 25.0) + (\text{isKEV} \times 15.0) + (\text{isDirect} \times 10.0)\Big)$$

🔍 Scanning Engines

1. Supply Chain & Dependencies (SCA)

Native parsing of package-lock.json (v1, v2, v3), yarn.lock (v1 classic), and pnpm-lock.yaml (v5, v6+).
Normalizes dependency trees into catalogs, tracking direct vs. transitive depth.
Maps vulnerabilities directly to fixed versions and upgrade guidance.

2. Static Application Security Testing (SAST)

Injection Flaws: Dynamic eval(), new Function(), child_process.exec(), template-literal SQL injection.
XSS Vulnerabilities: Direct innerHTML assignments, document.write(), React dangerouslySetInnerHTML.
Crypto & Randomness: Insecure hashing (MD5, SHA-1), legacy ciphers (DES, RC4), predictable Math.random() in security contexts.
Node.js Pitfalls: Prototype pollution (__proto__), path traversal in filesystem calls, unsafe mass assignment.
ReDoS: Catastrophic backtracking regex detection.

3. High-Precision Secret Scanner

30+ Provider Patterns: AWS Keys (AKIA...), GitHub PATs/OAuth, GitLab, Stripe, OpenAI, Anthropic, HuggingFace, Slack tokens & webhooks, Discord, Telegram, SendGrid, Twilio, DB URLs, Private Keys, JWTs.
Shannon Entropy Analyzer: Flags unformatted high-entropy tokens ($> 4.5$ bits) near credential keywords.
False Positive Filter: Suppresses test directories (test/, __mocks__/), dummy samples, and documentation files.

4. Configuration & Firewall Auditor

Web Security Headers: Content-Security-Policy (CSP), Strict-Transport-Security (HSTS), X-Frame-Options, X-Content-Type-Options, Referrer-Policy, and CORS wildcards.
Containers: Dockerfile missing USER (running as root), :latest tags, remote ADD directives, exposed sensitive ports (22, 3306, 5432).
Kubernetes: Manifest privileged: true, runAsRoot: true, hostNetwork: true, missing resource limits or read-only filesystems.
Environment: .env files missing from .gitignore, DEBUG=* enabled in production configs.

💻 Interactive Dashboard

Generate an interactive HTML dashboard:

npx micro-sec-audit scan . --open

┌────────────────────────────────────────────────────────────────────────┐
│  🔒 micro-sec-audit v1.0.0                      [Refresh Live Feeds]   │
│  Target: /workspace/app       Duration: 180ms   [Export JSON]          │
├────────────────────────────────────────────────────────────────────────┤
│  [Total: 12]  [Critical: 2]  [High: 4]  [Medium: 5]  [Low: 1]          │
├───────────────────────────────────┬────────────────────────────────────┤
│       SEVERITY DONUT RING         │      EPSS vs CVSS THREAT MATRIX    │
│           (SVG Chart)             │           (Scatter Plot)           │
├───────────────────────────────────┴────────────────────────────────────┤
│  Filter: [Critical] [High] [Medium] [Low] [KEV In-The-Wild] [Search /] │
├────────────────────────────────────────────────────────────────────────┤
│  ▼ CRITICAL  [email protected]: Prototype Pollution (CVE-2021-23337)     │
│    Location: package.json (Direct Dependency)                          │
│    Base CVSS: 7.2 | EPSS: 87.4% | CISA KEV: Active                    │
│    Fix: Update to 4.17.21                      [ Copy npm install ]    │
└────────────────────────────────────────────────────────────────────────┘

Key Dashboard Features:

Zero External Assets: No external CDNs, Google Fonts, or script tags. Opens instantly offline.
Threat Matrix (EPSS vs CVSS): Interactive SVG scatter plot visualizing which vulnerabilities are actively being exploited.
1-Click Remediation: Click "Copy Command" to copy the exact npm install fix to your clipboard.
Live Feed Refresh: Click "Refresh Live Threat Feeds" to fetch live updates from OSV & EPSS directly inside the browser.
Keyboard Shortcuts: Press / anywhere to focus the search bar.

🔌 Dev Server Integrations

Serve the security audit dashboard directly in your local development environment:

Vite (`vite.config.js`)

import { defineConfig } from 'vite';
import { microSecAudit } from 'micro-sec-audit/plugins/vite';

export default defineConfig({
  plugins: [
    microSecAudit({ path: '/__security' })
  ]
});

Open http://localhost:5173/__security while developing.

Next.js (`app/api/security/route.js` or `pages/api/security.js`)

// App Router: app/api/__security/route.js
export { GET } from 'micro-sec-audit/plugins/nextjs';

// Pages Router: pages/api/__security.js
export { handler as default } from 'micro-sec-audit/plugins/nextjs';

Express (`app.js`)

import express from 'express';
import { microSecAuditMiddleware } from 'micro-sec-audit/plugins/express';

const app = express();
app.use(microSecAuditMiddleware({ path: '/__security' }));

🤖 CI/CD (GitHub Actions)

Add automated pull-request scanning and report uploading to your repository:

Create .github/workflows/security.yml:

name: Security Audit

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

jobs:
  security-audit:
    runs-on: ubuntu-latest
    permissions:
      security-events: write # Required for GitHub Code Scanning
      contents: read

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run micro-sec-audit
        run: |
          npx micro-sec-audit scan . \
            --fail-on=critical \
            --format=sarif \
            --output=security-results.sarif

      - name: Upload to GitHub Code Scanning Alerts
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: security-results.sarif

📖 CLI Options

$ npx micro-sec-audit scan [path] [options]

Examples

# Output SARIF format for CI ingestion
npx micro-sec-audit scan . --format=sarif --output=results.sarif

# Scan only secrets and dependencies, skipping static analysis
npx micro-sec-audit scan . --engines=sca,secrets --open

# Air-gapped / offline scanning
npx micro-sec-audit scan . --no-enrich

# Export Markdown summary for documentation
npx micro-sec-audit scan . --format=markdown --output=SECURITY_AUDIT.md

🧪 Testing

The test suite runs using Node's native test runner without third-party frameworks:

npm test

📄 License

This project is licensed under the MIT License.