MaunPrekshak — मौन प्रेक्षक

"The Silent Observer. Nothing hides from it."

MaunPrekshak (मौन = Silent, प्रेक्षक = Observer) is a fast, privacy-first Python security toolkit designed to catch vulnerabilities, exposed credentials, and insecure code patterns right in your terminal.

---

⚡ Highlights

• 🔍 Dependency Vulnerabilities (SCA): Real-time CVE discovery against OSV.dev for requirements.txt, pyproject.toml, and Pipfile.
• 🔑 Secrets & Credential Detection: 40+ high-precision regex detectors for AWS keys, GCP keys, GitHub tokens, Stripe keys, RSA/SSH private keys, JWTs, and database URIs with false-positive suppression.
• 🛡️ Static Code Analysis (SAST): Python AST visitor checking for eval(), exec(), pickle.loads(), subprocess(..., shell=True), yaml.load(), insecure hashing (MD5/SHA1), and command injection.
• 🎨 Rich Terminal UX: Beautiful formatted console output, severity badges, and export to JSON or Markdown.
• 🔒 100% Privacy & Local-First: Scans run entirely on your local CPU. Your source code never leaves your computer.
• 🤖 Optional AI Remediation: Plug in your own Google Gemini API key to get an instant executive summary and tailored remediation steps.

---

🚀 Quick Start

Installation

pip install maunprekshak

🐧 Linux (1-Line Standalone Install — No Python Required)

curl -sSL https://raw.githubusercontent.com/PramanKasliwal/maunprekshak/main/install.sh | bash

🐍 Via PyPI (Any OS)

pip install maunprekshak
# or using pipx (recommended for Ubuntu 24.04+)
pipx install maunprekshak

Basic Scan

Scan the current directory:

mp scan .

Fast Scan without AI (No API Key Required)

mp scan . --no-ai

Export Results to SARIF, JSON, or Markdown

# Export standard OASIS SARIF 2.1.0 for GitHub Code Scanning
mp scan ./my-project --output sarif --output-file results.sarif

# Export as JSON for pipelines
mp scan ./my-project --output json > report.json

# Export formatted Markdown
mp scan ./my-project --output markdown > SECURITY.md

CI/CD Mode (Exit with Non-Zero on Threshold Breach)

# Fail CI build if any CRITICAL issue is found
mp scan . --ci --fail-on critical

# Fail CI build on HIGH or CRITICAL issues
mp scan . --ci --fail-on high

---

🐙 GitHub Actions & Code Scanning (SARIF)

Run MaunPrekshak in your GitHub workflow and get native inline alerts in GitHub's Security ➔ Code Scanning tab:

name: Security Scan

on: [push, pull_request]

jobs:
  maunprekshak:
    runs-on: ubuntu-latest
    permissions:
      security-events: write  # Needed for SARIF upload
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Run MaunPrekshak Security Scan
        uses: PramanKasliwal/maunprekshak@v0.2.0
        with:
          fail-on: high
          output: sarif
          sarif-file: results.sarif

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

---

🪝 Pre-Commit Hook

Prevent secrets, leaked API keys, and AST flaws from ever reaching Git. Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/PramanKasliwal/maunprekshak
    rev: v0.2.0
    hooks:
      - id: maunprekshak
        args: ["--fail-on", "high"]

---

⚙️ Configuration File (.maunprekshak.toml)

Generate a starter configuration file with:

mp init

Or customize .maunprekshak.toml (or [tool.maunprekshak] in pyproject.toml):

[scanner]
# Directories to exclude from scans
exclude = ["tests", "fixtures", ".venv", "node_modules"]

# Default CI failure threshold: "critical", "high", "medium", or "low"
fail_on = "high"

# Disable Gemini AI remediation (fully offline)
no_ai = false

# Ignore specific SAST check IDs
ignore_rules = ["MP010"]

🖥️ Sample Console Output

╭──────────────────────────────────────────────────────────────────────────────╮
│ Risk Level: HIGH (Score: 78)                                                 │
╰──────────────────────────────────────────────────────────────────────────────╯

┌──────────────────────────────────────────────────────────────────────────────┐
│                              Scan Summary                                    │
├──────────────┬──────────┬─────────┬────────┬───────┬────────────────────────┤
│ Module       │ CRITICAL │  HIGH   │ MEDIUM │  LOW  │ Total                  │
├──────────────┼──────────┼─────────┼────────┼───────┼────────────────────────┤
│ Dependencies │    1     │    2    │   0    │   0   │ 3 vulnerabilities      │
│ Secrets      │    1     │    1    │   0    │   0   │ 2 exposed credentials  │
│ SAST         │    0     │    3    │   4    │   1   │ 8 insecure patterns    │
└──────────────┴──────────┴─────────┴────────┴───────┴────────────────────────┘

Top Findings:
  [CRITICAL] CVE-2023-32681 — requests==2.25.1 (Fixed in 2.31.0)
  [HIGH]     AWS Access Key ID exposed in config.py:12
  [HIGH]     MP004: subprocess.run() called with shell=True in deploy.py:45

---

📖 CLI Command Reference

Option	Default	Description
path	.	Directory or project path to scan
--only	all	Restrict scan to: deps, secrets, or sast
--output	console	Output format: console, json, markdown
--output-file	stdout	Write report directly to a file
--ci	false	Compact machine-readable summary + exit code
--fail-on	critical	Threshold: critical, high, medium, low
--no-ai	false	Skip AI summary generation (instant execution)
--exclude	None	Comma-separated directories to exclude

---

🤖 Bringing Your Own Gemini AI Key (Optional)

If you'd like AI-generated remediation summaries, set your Gemini API key in your environment or a .env file:

export GEMINI_API_KEY="AIzaSy..."
mp scan .

Get a free API key at Google AI Studio.

---

🤝 Contributing

We welcome community contributions! Please read our CONTRIBUTING.md to get started.

• Found a bug or missing a secret pattern? Open an Issue.
• Want to contribute a new SAST check? PRs are warmly welcomed!

---

🔒 Security Policy

We take security vulnerabilities seriously. Please review our SECURITY.md for details on supported versions and how to responsibly report vulnerabilities privately.

---

📄 License

Distributed under the MIT License. See LICENSE for details.

---

In ancient Sanskrit, मौन (Maun) signifies the all-knowing silence, and प्रेक्षक (Prekshak) is the ever-vigilant observer. MaunPrekshak protects your code quietly, thoroughly, and without compromise.