maunprekshak 0.1.0__tar.gz

maunprekshak-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Praman Kasliwal & MaunPrekshak Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maunprekshak-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: maunprekshak
+Version: 0.1.0
+Summary: The Silent Observer — Open-source Python security scanner for dependencies, secrets & insecure code
+Author-email: Praman Kasliwal <kasliwal.praman008@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/PramanKasliwal/maunprekshak
+Project-URL: Repository, https://github.com/PramanKasliwal/maunprekshak
+Project-URL: Issues, https://github.com/PramanKasliwal/maunprekshak/issues
+Project-URL: Documentation, https://github.com/PramanKasliwal/maunprekshak#readme
+Keywords: security,python,vulnerability,scanner,sast,secrets,cve,osv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: reportlab>=4.2.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: toml>=0.10.2
+Requires-Dist: python-dotenv>=1.2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Dynamic: license-file
+
+# MaunPrekshak — मौन प्रेक्षक
+
+> *"The Silent Observer. Nothing hides from it."*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/maunprekshak.svg)](https://badge.fury.io/py/maunprekshak)
+[![CI Tests](https://github.com/PramanKasliwal/maunprekshak/actions/workflows/ci.yml/badge.svg)](https://github.com/PramanKasliwal/maunprekshak/actions)
+
+**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](https://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
+
+```bash
+pip install maunprekshak
+```
+
+### 🐧 Linux (1-Line Standalone Install — No Python Required)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/PramanKasliwal/maunprekshak/main/install.sh | bash
+```
+
+### 🐍 Via PyPI (Any OS)
+```bash
+pip install maunprekshak
+# or using pipx (recommended for Ubuntu 24.04+)
+pipx install maunprekshak
+```
+
+Basic Scan
+
+Scan the current directory:
+
+```bash
+mp scan .
+```
+
+### Fast Scan without AI (No API Key Required)
+
+```bash
+mp scan . --no-ai
+```
+
+### Export Results to JSON or Markdown
+
+```bash
+# 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)
+
+```bash
+# 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
+```
+
+---
+
+## 🖥️ Sample Console Output
+
+```text
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ 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:
+
+```bash
+export GEMINI_API_KEY="AIzaSy..."
+mp scan .
+```
+
+Get a free API key at [Google AI Studio](https://aistudio.google.com/app/apikey).
+
+---
+
+## 🤝 Contributing
+
+We welcome community contributions! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+- Found a bug or missing a secret pattern? [Open an Issue](https://github.com/PramanKasliwal/maunprekshak/issues).
+- Want to contribute a new SAST check? PRs are warmly welcomed!
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**. See [LICENSE](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.*

maunprekshak-0.1.0/README.md

@@ -0,0 +1,151 @@
+# MaunPrekshak — मौन प्रेक्षक
+
+> *"The Silent Observer. Nothing hides from it."*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://badge.fury.io/py/maunprekshak.svg)](https://badge.fury.io/py/maunprekshak)
+[![CI Tests](https://github.com/PramanKasliwal/maunprekshak/actions/workflows/ci.yml/badge.svg)](https://github.com/PramanKasliwal/maunprekshak/actions)
+
+**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](https://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
+
+```bash
+pip install maunprekshak
+```
+
+### 🐧 Linux (1-Line Standalone Install — No Python Required)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/PramanKasliwal/maunprekshak/main/install.sh | bash
+```
+
+### 🐍 Via PyPI (Any OS)
+```bash
+pip install maunprekshak
+# or using pipx (recommended for Ubuntu 24.04+)
+pipx install maunprekshak
+```
+
+Basic Scan
+
+Scan the current directory:
+
+```bash
+mp scan .
+```
+
+### Fast Scan without AI (No API Key Required)
+
+```bash
+mp scan . --no-ai
+```
+
+### Export Results to JSON or Markdown
+
+```bash
+# 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)
+
+```bash
+# 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
+```
+
+---
+
+## 🖥️ Sample Console Output
+
+```text
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ 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:
+
+```bash
+export GEMINI_API_KEY="AIzaSy..."
+mp scan .
+```
+
+Get a free API key at [Google AI Studio](https://aistudio.google.com/app/apikey).
+
+---
+
+## 🤝 Contributing
+
+We welcome community contributions! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+- Found a bug or missing a secret pattern? [Open an Issue](https://github.com/PramanKasliwal/maunprekshak/issues).
+- Want to contribute a new SAST check? PRs are warmly welcomed!
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**. See [LICENSE](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.*

maunprekshak-0.1.0/maunprekshak/__init__.py

@@ -0,0 +1,3 @@
+"""MaunPrekshak — The Silent Observer. Nothing hides from it."""
+__version__ = "0.1.0"
+__author__ = "MaunPrekshak"

maunprekshak-0.1.0/maunprekshak/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for MaunPrekshak."""

maunprekshak-0.1.0/maunprekshak/cli/main.py

@@ -0,0 +1,84 @@
+import typer
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from maunprekshak import __version__
+from maunprekshak.scanner import scan_project
+from maunprekshak.scanner.report import to_json, to_markdown, to_pdf, generate_ai_summary
+
+# Auto-load .env from the current directory or any parent directory
+# This means `mp scan .` will pick up .env automatically
+load_dotenv(dotenv_path=Path.cwd() / ".env", override=False)
+load_dotenv(override=False)  # Also check current working dir
+
+app = typer.Typer(help="MaunPrekshak — The Silent Observer")
+console = Console()
+
+@app.command()
+def scan(
+    path: str,
+    only: str = typer.Option(None, help="Run only: deps, secrets, sast"),
+    output: str = typer.Option("console", help="Output format: console, json, markdown, pdf"),
+    output_file: str = typer.Option(None, help="Save output to this file path"),
+    ci: bool = typer.Option(False, help="CI mode: compact output, non-zero exit on threshold breach"),
+    fail_on: str = typer.Option("critical", help="Fail CI if severity reached: critical, high, medium, low"),
+    no_ai: bool = typer.Option(False, help="Skip Gemini AI summary generation"),
+    exclude: str = typer.Option(None, help="Comma-separated dirs to exclude (e.g. tests,fixtures)"),
+):
+    exclude_list = [e.strip() for e in exclude.split(",") if e.strip()] if exclude else None
+    with console.status("[bold green]Scanning project...") as status:
+        result = scan_project(path, exclude=exclude_list, only=only)
+        
+        if not no_ai:
+            status.update("[bold green]Generating AI summary...")
+            result.ai_summary = generate_ai_summary(result)
+            
+    if output == "json":
+        out_str = to_json(result)
+        if output_file:
+            with open(output_file, "w") as f:
+                f.write(out_str)
+        else:
+            print(out_str)
+    elif output == "markdown":
+        out_str = to_markdown(result)
+        if output_file:
+            with open(output_file, "w") as f:
+                f.write(out_str)
+        else:
+            print(out_str)
+    elif output == "pdf" and output_file:
+        to_pdf(result, output_file)
+        console.print(f"[bold green]Saved PDF to {output_file}[/bold green]")
+    else:
+        # Console output
+        console.print(Panel(f"[bold red]Risk Level: {result.risk_score.level}[/bold red] (Score: {result.risk_score.score})"))
+        if result.ai_summary:
+            console.print("\n[bold]AI Summary:[/bold]")
+            console.print(result.ai_summary)
+            
+        if ci:
+            severity_map = {"low": 1, "medium": 21, "high": 51, "critical": 100}
+            threshold = severity_map.get(fail_on.lower(), 100)
+            if result.risk_score.score >= threshold:
+                console.print(f"[bold red]CI Check Failed: Score {result.risk_score.score} >= {threshold}[/bold red]")
+                raise typer.Exit(code=1)
+
+@app.command()
+def version():
+    """Print the current version."""
+    console.print(f"MaunPrekshak v{__version__}")
+
+@app.command()
+def auth_login():
+    """Save API key."""
+    key = typer.prompt("Enter API Key", hide_input=True)
+    with open(os.path.expanduser("~/.maunprekshak.yaml"), "w") as f:
+        f.write(f"api_key: {key}")
+    console.print("[green]API Key saved.[/green]")
+
+if __name__ == "__main__":
+    app()

maunprekshak-0.1.0/maunprekshak/scanner/__init__.py

@@ -0,0 +1,37 @@
+import asyncio
+from typing import List, Optional
+from maunprekshak.scanner.report import ScanResult, aggregate
+from maunprekshak.scanner.deps import scan_dependencies
+from maunprekshak.scanner.secrets import scan_secrets
+from maunprekshak.scanner.sast import scan_sast
+
+def scan_project(
+    path: str,
+    exclude: Optional[List[str]] = None,
+    only: Optional[str] = None,
+) -> ScanResult:
+    """
+    Orchestrate the scanning of dependencies, secrets, and SAST.
+    
+    Args:
+        path: Path to the project root directory
+        exclude: Optional list of directories to exclude
+        only: Run only a specific module ('deps', 'secrets', 'sast')
+        
+    Returns:
+        A unified ScanResult containing all findings.
+    """
+    deps = []
+    secrets = []
+    sast = []
+
+    if only is None or only == "deps":
+        deps = asyncio.run(scan_dependencies(path))
+
+    if only is None or only == "secrets":
+        secrets = scan_secrets(path, exclude=exclude)
+
+    if only is None or only == "sast":
+        sast = scan_sast(path, exclude=exclude)
+
+    return aggregate(deps, secrets, sast)