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

• 🔍 Multi-Ecosystem SCA: Real-time CVE discovery against OSV.dev across Python, JavaScript/Node.js, Go, Rust, Java (Maven pom.xml, Gradle build.gradle, gradle.lockfile), and PHP (Composer composer.lock, composer.json) for deep transitive dependency tracking. CI fails as soon as any finding meets the selected severity threshold.
• 🔑 Entropy & Regex Secrets Detection: 50+ high-precision regex detectors (GCP Service Account JSON, Azure Storage & SAS tokens, GitHub Copilot/App tokens, K8s Service Account tokens, Databricks API tokens, PyPI, NPM, OpenAI, Anthropic, Postman, Supabase, HuggingFace, GitLab, GitHub PAT, Discord, HashiCorp Vault, AWS, Stripe) PLUS Shannon entropy token analysis ($H \ge 4.5$ Base64 / $H \ge 3.0$ Hex) for un-prefixed credentials.
• 🏗️ Infrastructure-as-Code (IaC) Scanner: Zero-dependency Terraform & OpenTofu static analysis (TF001–TF008) for AWS, GCP, and Azure cloud resources (--only tf).
• 🔔 CI/CD Webhook & Alerting Engine: Dispatch rich scan summaries and failure notifications to Slack Block Kit, Discord embeds, or generic JSON endpoints via --notify-webhook <url> and --notify-on <fail|always>.
• 📜 Git Commit History Secrets Scanner: Deep-scan historical git commits with --history and --commits <N> to uncover leaked credentials that were committed and later "deleted" in git log.
• 🛠️ Custom Rule Engine: Extend the scanner with proprietary secret patterns and custom SAST rules via .maunprekshak-rules.yaml or --rules-file without modifying core code.
• 🛡️ Static Code & CI/CD Analysis (SAST): 48 Python AST rules (MP001–MP048 including CORS wildcard credentials, open redirect, JWT validation, CSRF exemptions, path traversal in file serving, mass assignment, GraphQL introspection, LLM prompt injection, SSRF, unsafe YAML, and deserialization), Kubernetes manifest checks (K8S001–K8S008), Dockerfile rules (DF001–DF006), and GitHub Actions workflow security checks (GHA001–GHA005).
• 📊 Interactive Standalone HTML Report: Generate a 100% offline, single-file interactive HTML dashboard with search, filtering, and risk gauges via --output html.
• ⚡ Git Staged, Diff & Baseline Scanning: Fast pre-commit mode via --staged, diff checks via --diff, and legacy debt suppression via --baseline.
• 🎨 Rich Terminal & Multi-Format CI/CD Export: Formatted console output, SonarQube Generic Issue format (--output sonarqube), Code Climate / GitLab Code Quality (--output codeclimate), GitLab SAST v15 (--output gitlab), OASIS SARIF 2.1.0, CycloneDX 1.5, SPDX 2.3, HTML, JSON, or Markdown export.
• 🔒 100% Privacy & Local-First: Scans run entirely on your local CPU. Your source code never leaves your machine.
• 🤖 Multi-Provider AI Remediation: Plug in Google Gemini, OpenAI, Anthropic Claude, or local offline Ollama for root-cause analysis and 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

🪟 Windows (1-Line PowerShell Install — Configures PATH Automatically)

irm https://raw.githubusercontent.com/PramanKasliwal/maunprekshak/main/install.ps1 | iex

🐍 Via PyPI (Any OS)

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

Windows Tip: If mp is not recognized after a standard pip install, run directly via the Python module:

python -m maunprekshak scan .
# or using py launcher
py -m maunprekshak scan .

Or permanently add Python's Scripts\ folder to your user PATH via PowerShell:

$scriptsDir = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
[Environment]::SetEnvironmentVariable("PATH", "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$scriptsDir", "User")

Basic Scan

Scan the current directory:

mp scan .

Fast Scan without AI (No API Key Required)

mp scan . --no-ai

Export Results to HTML, SARIF, SBOM, JSON, or Markdown

# Export interactive standalone single-file HTML audit report (100% offline, zero CDN dependencies)
mp scan ./my-project --output html --output-file audit.html

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

# Export OASIS CycloneDX 1.5 JSON SBOM
mp scan ./my-project --output cyclonedx --output-file bom.cdx.json

# Export Linux Foundation SPDX 2.3 JSON SBOM
mp scan ./my-project --output spdx --output-file bom.spdx.json

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

# Export SonarQube Generic Issue Import JSON for sonar.externalIssuesReportPaths
mp scan ./my-project --output sonarqube --output-file sonar-issues.json

# Export Code Climate JSON for GitLab Code Quality / Code Climate CLI
mp scan ./my-project --output codeclimate --output-file codeclimate.json

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

📜 Git Commit History Secrets Scanning (--history)

Detect credentials and tokens that were previously committed and subsequently deleted in git history:

# Scan git history for leaked credentials (default: last 50 commits)
mp scan . --history

# Deep-scan specific commit depth
mp scan . --history --commits 100

🛠️ Custom Rule Engine (--rules-file)

Define organization-specific secret patterns or custom SAST banned functions via .maunprekshak-rules.yaml:

custom_rules:
  secrets:
    - id: "ACME-001"
      name: "Acme Corp Token"
      regex: "acme_secret_[0-9a-f]{32}"
      severity: "high"
  sast:
    - id: "ACME-002"
      name: "Banned Legacy Function"
      severity: "critical"
      description: "myapp.legacy_eval is unsafe and deprecated."
      recommendation: "Use secure parser module instead."
      banned_calls: ["myapp.legacy_eval", "os.system"]
      banned_imports: ["telnetlib"]

# Scan using explicit custom rules file (or auto-discovered .maunprekshak-rules.yaml)
mp scan . --rules-file .maunprekshak-rules.yaml

Safe Mechanical Auto-Fixing (--fix)

Automatically patch safe, deterministic anti-patterns without breaking application logic:

• MP012 & MP036: yaml.load() / yaml.unsafe_load() -> yaml.safe_load(), unsafe Loader -> yaml.SafeLoader
• MP031: torch.load() -> torch.load(..., weights_only=True) (prevents arbitrary pickle execution)
• MP023: tar.extractall() -> tar.extractall(filter='data') (prevents Zip Slip)
• MP014: tempfile.mktemp() -> tempfile.NamedTemporaryFile().name
• MP015: Insecure HTTP SSL verification verify=False -> verify=True
• MP033: World-writable os.chmod(): 0o777 -> 0o700, 0o666 -> 0o600
• TF004: Terraform storage/database storage_encrypted = false -> true
• TF005: Terraform database publicly_accessible = true -> false
• TF006: Terraform S3 Public Access Block block_public_* = false -> true
• DF002: Dockerfile missing non-root user -> injects USER 10001:10001 before CMD/ENTRYPOINT

mp scan . --fix

Inline Code Suppression

Suppress specific false-positives or approved patterns directly in code comments:

# Suppress all findings on this line:
result = eval(user_input)  # maunprekshak: ignore
# or Bandit / flake8 compatible:
result = eval(user_input)  # nosec

# Suppress specific rule ID:
result = eval(user_input)  # maunprekshak: ignore[MP001]
result = eval(user_input)  # nosec: MP001

# Disable entire file for a rule at the top of the file:
# maunprekshak: disable-file[MP001]

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

# A single HIGH or CRITICAL finding is enough to fail; the risk score remains informational

🐙 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.8.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

🪝 Native Git Pre-Commit Hook (1-Command Install)

Install MaunPrekshak directly into your repository's .git/hooks/pre-commit with a single command — no external dependencies needed:

# Install native pre-commit hook (automatically scans staged files before every commit)
mp hook install

# Uninstall hook and restore any previous backup
mp hook uninstall

Or using the standard .pre-commit-config.yaml framework:

repos:
  - repo: https://github.com/PramanKasliwal/maunprekshak
    rev: v0.8.0
    hooks:
      - id: maunprekshak
        args: ["--staged", "--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

🛡️ CI/CD & Container Rules Reference

🤖 Multi-Provider AI Remediation (Gemini, OpenAI, Anthropic, Ollama)

MaunPrekshak automatically crafts actionable executive security summaries and prioritized remediation plans. It auto-detects your preferred AI provider or allows explicit selection with zero extra dependencies (powered by built-in httpx):

# Auto-detects based on available environment key:
mp scan .

# Google Gemini:
export GEMINI_API_KEY="AIzaSy..."
mp scan . --ai-provider gemini

# OpenAI:
export OPENAI_API_KEY="sk-..."
mp scan . --ai-provider openai --ai-model gpt-4o-mini

# Anthropic Claude:
export ANTHROPIC_API_KEY="sk-ant-..."
mp scan . --ai-provider anthropic --ai-model claude-3-5-haiku-20241022

# 100% Offline / Air-Gapped via Local Ollama:
mp scan . --ai-provider ollama --ai-model llama3.2

# Custom enterprise gateway or vLLM:
mp scan . --ai-provider openai --ai-base-url "http://localhost:11434/v1"

🤝 Contributing & Community

We welcome community contributions! Please read our CONTRIBUTING.md and our CODE_OF_CONDUCT.md before participating.

• Found a bug or missing a secret pattern? Open an Issue.
• Want to contribute a new SAST check or rule? 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 Apache License 2.0. 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.