ragsec 0.1.0__tar.gz

ragsec-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.venv/
+report.md
+report.html

ragsec-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: ragsec
+Version: 0.1.0
+Summary: Static security scanner for RAG pipelines
+Author-email: Hrushikesh Yadav <yadavhrushikesh65@gmail.com>
+License-Expression: Apache-2.0
+Keywords: rag,scanner,security,static-analysis,vector-store
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# RAGGuard
+
+Static security scanner for RAG pipelines. Finds injection vulnerabilities, secret logging, auth gaps, and resource safety issues in Python codebases.
+
+Built from real-world security audits of production RAG frameworks.
+
+## Install
+
+```bash
+pip install ragguard
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/HrushiYadav/ragGuard.git
+cd ragguard
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Terminal output (default)
+ragguard scan ./path/to/codebase
+
+# Generate reports
+ragguard scan ./path/to/codebase --output report.md --format markdown
+ragguard scan ./path/to/codebase --output report.html --format html
+
+# Filter by severity or category
+ragguard scan ./path/to/codebase --severity high
+ragguard scan ./path/to/codebase --category filter-injection
+```
+
+## What it detects
+
+| Scanner | Severity | What it finds |
+|---------|----------|---------------|
+| Filter Injection | HIGH | f-string interpolation in Milvus, Valkey, Azure, Elasticsearch filter expressions |
+| NoSQL Injection | HIGH | Unvalidated dict values in MongoDB/Elasticsearch queries |
+| SQL Injection | HIGH | f-string SQL construction (INSERT, DELETE, SELECT, UPDATE) |
+| Secret Logging | MEDIUM | API keys, passwords, connection strings in logger calls |
+| Auth Gaps | MEDIUM | FastAPI/Flask routes without auth, client-controlled user IDs (IDOR) |
+| Resource Safety | HIGH/MEDIUM/LOW | pickle deserialization, zip bombs, eval/exec, unbounded reads |
+
+## Example output
+
+```
+RAGGuard scanning ./my-rag-app
+
+RG-001 [HIGH] Filter injection: Possible filter expression injection
+  vector_stores/store.py:42
+  > conditions.append(f'(metadata["{key}"] == "{value}")')
+
+RG-002 [HIGH] NoSQL injection: Filter value passed into query
+  vector_stores/mongo.py:89
+  > filter_dict["payload." + key] = value
+
+      Summary
++------------------+
+| Severity | Count |
+|----------+-------|
+| HIGH     |     5 |
+| MEDIUM   |     8 |
+| LOW      |     3 |
+| Total    |    16 |
++------------------+
+```
+
+## HTML Report
+
+Generate a styled HTML report for sharing:
+
+```bash
+ragguard scan ./my-rag-app --output report.html --format html
+```
+
+Dark theme with severity badges, code snippets, and remediation guidance.
+
+## Development
+
+```bash
+pip install -e .
+pytest tests/ -v
+ruff check ragguard/
+```
+
+## License
+
+Apache-2.0

ragsec-0.1.0/README.md

@@ -0,0 +1,91 @@
+# RAGGuard
+
+Static security scanner for RAG pipelines. Finds injection vulnerabilities, secret logging, auth gaps, and resource safety issues in Python codebases.
+
+Built from real-world security audits of production RAG frameworks.
+
+## Install
+
+```bash
+pip install ragguard
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/HrushiYadav/ragGuard.git
+cd ragguard
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Terminal output (default)
+ragguard scan ./path/to/codebase
+
+# Generate reports
+ragguard scan ./path/to/codebase --output report.md --format markdown
+ragguard scan ./path/to/codebase --output report.html --format html
+
+# Filter by severity or category
+ragguard scan ./path/to/codebase --severity high
+ragguard scan ./path/to/codebase --category filter-injection
+```
+
+## What it detects
+
+| Scanner | Severity | What it finds |
+|---------|----------|---------------|
+| Filter Injection | HIGH | f-string interpolation in Milvus, Valkey, Azure, Elasticsearch filter expressions |
+| NoSQL Injection | HIGH | Unvalidated dict values in MongoDB/Elasticsearch queries |
+| SQL Injection | HIGH | f-string SQL construction (INSERT, DELETE, SELECT, UPDATE) |
+| Secret Logging | MEDIUM | API keys, passwords, connection strings in logger calls |
+| Auth Gaps | MEDIUM | FastAPI/Flask routes without auth, client-controlled user IDs (IDOR) |
+| Resource Safety | HIGH/MEDIUM/LOW | pickle deserialization, zip bombs, eval/exec, unbounded reads |
+
+## Example output
+
+```
+RAGGuard scanning ./my-rag-app
+
+RG-001 [HIGH] Filter injection: Possible filter expression injection
+  vector_stores/store.py:42
+  > conditions.append(f'(metadata["{key}"] == "{value}")')
+
+RG-002 [HIGH] NoSQL injection: Filter value passed into query
+  vector_stores/mongo.py:89
+  > filter_dict["payload." + key] = value
+
+      Summary
++------------------+
+| Severity | Count |
+|----------+-------|
+| HIGH     |     5 |
+| MEDIUM   |     8 |
+| LOW      |     3 |
+| Total    |    16 |
++------------------+
+```
+
+## HTML Report
+
+Generate a styled HTML report for sharing:
+
+```bash
+ragguard scan ./my-rag-app --output report.html --format html
+```
+
+Dark theme with severity badges, code snippets, and remediation guidance.
+
+## Development
+
+```bash
+pip install -e .
+pytest tests/ -v
+ruff check ragguard/
+```
+
+## License
+
+Apache-2.0

ragsec-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ragsec"
+version = "0.1.0"
+description = "Static security scanner for RAG pipelines"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Hrushikesh Yadav", email = "yadavhrushikesh65@gmail.com" }]
+keywords = ["rag", "security", "scanner", "vector-store", "static-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "click>=8.0",
+    "jinja2>=3.0",
+    "rich>=13.0",
+]
+
+[project.scripts]
+ragguard = "ragguard.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ragguard"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ragsec-0.1.0/ragguard/__init__.py

@@ -0,0 +1,3 @@
+"""RAGGuard -- static security scanner for RAG pipelines."""
+
+__version__ = "0.1.0"

ragsec-0.1.0/ragguard/cli.py

@@ -0,0 +1,86 @@
+import os
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ragguard.engine import run_scan
+from ragguard.report.html import write_html_report
+from ragguard.report.markdown import write_markdown_report
+from ragguard.scanners import ALL_SCANNERS
+
+console = Console()
+
+
+@click.group()
+@click.version_option()
+def main():
+    """RAGGuard -- static security scanner for RAG pipelines."""
+
+
+@main.command()
+@click.argument("target", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), help="Output file path (auto-detects format from extension).")
+@click.option("--format", "fmt", type=click.Choice(["markdown", "html", "terminal"]), default="terminal")
+@click.option(
+    "--severity", type=click.Choice(["high", "medium", "low"], case_sensitive=False), help="Filter by severity."
+)
+@click.option("--category", help="Filter by category (e.g. filter-injection, nosql-injection).")
+def scan(target: str, output: str | None, fmt: str, severity: str | None, category: str | None):
+    """Scan a codebase for RAG security vulnerabilities."""
+    target = os.path.abspath(target)
+    console.print(f"\n[bold blue]RAGGuard[/] scanning [cyan]{target}[/]\n")
+
+    scanners = [cls() for cls in ALL_SCANNERS]
+    findings = run_scan(target, scanners, severity_filter=severity, category_filter=category)
+
+    if output and not fmt:
+        if output.endswith(".html"):
+            fmt = "html"
+        elif output.endswith(".md"):
+            fmt = "markdown"
+
+    if fmt == "terminal" and not output:
+        _print_terminal(findings, target)
+    elif fmt == "html" or (output and output.endswith(".html")):
+        path = output or "ragguard-report.html"
+        write_html_report(findings, target, path)
+        console.print(f"\n[green]HTML report written to {path}[/]")
+    elif fmt == "markdown" or (output and output.endswith(".md")):
+        path = output or "ragguard-report.md"
+        write_markdown_report(findings, target, path)
+        console.print(f"\n[green]Markdown report written to {path}[/]")
+    else:
+        _print_terminal(findings, target)
+
+    _print_summary(findings)
+
+
+def _print_terminal(findings: list, target: str):
+    if not findings:
+        console.print("[green]No findings.[/]")
+        return
+
+    for f in findings:
+        sev_color = {"HIGH": "red", "MEDIUM": "yellow", "LOW": "blue"}.get(f.severity, "white")
+        console.print(f"\n[bold {sev_color}]{f.id} [{f.severity}][/] {f.title}")
+        console.print(f"  [dim]{f.file_path}:{f.line_number}[/]")
+        console.print(f"  {f.description}")
+        if f.code_snippet:
+            console.print(f"  [dim]> {f.code_snippet.strip()[:120]}[/]")
+
+
+def _print_summary(findings: list):
+    high = sum(1 for f in findings if f.severity == "HIGH")
+    med = sum(1 for f in findings if f.severity == "MEDIUM")
+    low = sum(1 for f in findings if f.severity == "LOW")
+
+    console.print()
+    table = Table(title="Summary", show_header=True)
+    table.add_column("Severity", style="bold")
+    table.add_column("Count", justify="right")
+    table.add_row("[red]HIGH[/]", str(high))
+    table.add_row("[yellow]MEDIUM[/]", str(med))
+    table.add_row("[blue]LOW[/]", str(low))
+    table.add_row("[bold]Total[/]", f"[bold]{len(findings)}[/]")
+    console.print(table)

ragsec-0.1.0/ragguard/engine.py

@@ -0,0 +1,51 @@
+import os
+from pathlib import Path
+
+from ragguard.finding import Finding
+from ragguard.scanners.base import BaseScanner
+
+
+def discover_python_files(root: str) -> list[str]:
+    files = []
+    for dirpath, _, filenames in os.walk(root):
+        if any(skip in dirpath for skip in ("__pycache__", ".git", "node_modules", ".venv", "venv")):
+            continue
+        for f in filenames:
+            if f.endswith(".py"):
+                files.append(os.path.join(dirpath, f))
+    return sorted(files)
+
+
+def run_scan(
+    target: str,
+    scanners: list[BaseScanner],
+    severity_filter: str | None = None,
+    category_filter: str | None = None,
+) -> list[Finding]:
+    root = os.path.abspath(target)
+    files = discover_python_files(root)
+    findings: list[Finding] = []
+    counter = 1
+
+    for file_path in files:
+        try:
+            content = Path(file_path).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+
+        lines = content.splitlines()
+        rel_path = os.path.relpath(file_path, root)
+
+        for scanner in scanners:
+            if category_filter and scanner.category != category_filter:
+                continue
+
+            for finding in scanner.scan_file(rel_path, content, lines):
+                if severity_filter and finding.severity.lower() != severity_filter.lower():
+                    continue
+                finding.id = f"RG-{counter:03d}"
+                counter += 1
+                findings.append(finding)
+
+    findings.sort(key=lambda f: ({"HIGH": 0, "MEDIUM": 1, "LOW": 2}.get(f.severity, 3), f.file_path, f.line_number))
+    return findings

ragsec-0.1.0/ragguard/finding.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Finding:
+    id: str
+    severity: str
+    category: str
+    title: str
+    file_path: str
+    line_number: int
+    code_snippet: str
+    description: str
+    remediation: str
+    cwe_id: str | None = None

ragsec-0.1.0/ragguard/report/html.py

@@ -0,0 +1,32 @@
+import html
+from datetime import datetime, timezone
+from pathlib import Path
+
+from jinja2 import Template
+
+from ragguard.finding import Finding
+
+_TEMPLATE_PATH = Path(__file__).parent / "template.html"
+
+
+def write_html_report(findings: list[Finding], target: str, output_path: str) -> None:
+    high = sum(1 for f in findings if f.severity == "HIGH")
+    med = sum(1 for f in findings if f.severity == "MEDIUM")
+    low = sum(1 for f in findings if f.severity == "LOW")
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    template_str = _TEMPLATE_PATH.read_text(encoding="utf-8")
+    template = Template(template_str)
+
+    rendered = template.render(
+        target=html.escape(target),
+        timestamp=timestamp,
+        total=len(findings),
+        high=high,
+        medium=med,
+        low=low,
+        findings=findings,
+    )
+
+    with open(output_path, "w", encoding="utf-8") as fp:
+        fp.write(rendered)

ragsec-0.1.0/ragguard/report/markdown.py

@@ -0,0 +1,61 @@
+from datetime import datetime, timezone
+
+from ragguard.finding import Finding
+
+
+def write_markdown_report(findings: list[Finding], target: str, output_path: str) -> None:
+    high = sum(1 for f in findings if f.severity == "HIGH")
+    med = sum(1 for f in findings if f.severity == "MEDIUM")
+    low = sum(1 for f in findings if f.severity == "LOW")
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    lines = [
+        "# RAGGuard Security Report",
+        "",
+        f"**Target**: `{target}`",
+        f"**Date**: {timestamp}",
+        f"**Findings**: {len(findings)} ({high} high, {med} medium, {low} low)",
+        "",
+        "---",
+        "",
+        "## Summary",
+        "",
+        "| Severity | Count |",
+        "|----------|-------|",
+        f"| HIGH     | {high}   |",
+        f"| MEDIUM   | {med}   |",
+        f"| LOW      | {low}   |",
+        f"| **Total**| **{len(findings)}** |",
+        "",
+    ]
+
+    if not findings:
+        lines.append("No security findings detected.")
+    else:
+        lines.append("## Findings")
+        lines.append("")
+
+        for f in findings:
+            cwe = f" ({f.cwe_id})" if f.cwe_id else ""
+            lines.append(f"### {f.id} [{f.severity}] {f.title}{cwe}")
+            lines.append("")
+            lines.append(f"**File**: `{f.file_path}:{f.line_number}`")
+            lines.append(f"**Category**: {f.category}")
+            lines.append("")
+            lines.append(f"{f.description}")
+            lines.append("")
+            if f.code_snippet:
+                lines.append("```python")
+                lines.append(f"{f.code_snippet}")
+                lines.append("```")
+                lines.append("")
+            lines.append(f"**Remediation**: {f.remediation}")
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+
+    lines.append("")
+    lines.append("*Generated by [RAGGuard](https://github.com/HrushiYadav/ragguard)*")
+
+    with open(output_path, "w", encoding="utf-8") as fp:
+        fp.write("\n".join(lines))

ragsec-0.1.0/ragguard/report/template.html

@@ -0,0 +1,164 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>RAGGuard Security Report</title>
+<style>
+  :root {
+    --bg: #0d1117;
+    --card: #161b22;
+    --border: #30363d;
+    --text: #e6edf3;
+    --dim: #8b949e;
+    --high: #f85149;
+    --medium: #d29922;
+    --low: #58a6ff;
+    --green: #3fb950;
+  }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.6;
+    padding: 2rem;
+    max-width: 960px;
+    margin: 0 auto;
+  }
+  h1 { font-size: 1.8rem; margin-bottom: 0.5rem; }
+  .meta { color: var(--dim); margin-bottom: 2rem; font-size: 0.9rem; }
+  .stats {
+    display: flex;
+    gap: 1rem;
+    margin-bottom: 2rem;
+  }
+  .stat {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 1rem 1.5rem;
+    text-align: center;
+    flex: 1;
+  }
+  .stat .number { font-size: 2rem; font-weight: 700; }
+  .stat .label { font-size: 0.8rem; color: var(--dim); text-transform: uppercase; letter-spacing: 0.05em; }
+  .stat.high .number { color: var(--high); }
+  .stat.medium .number { color: var(--medium); }
+  .stat.low .number { color: var(--low); }
+  .stat.total .number { color: var(--text); }
+  .finding {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 1.25rem;
+    margin-bottom: 1rem;
+    border-left: 4px solid var(--border);
+  }
+  .finding.sev-HIGH { border-left-color: var(--high); }
+  .finding.sev-MEDIUM { border-left-color: var(--medium); }
+  .finding.sev-LOW { border-left-color: var(--low); }
+  .finding-header {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    margin-bottom: 0.5rem;
+  }
+  .badge {
+    font-size: 0.7rem;
+    font-weight: 700;
+    padding: 0.15rem 0.5rem;
+    border-radius: 4px;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+  .badge.HIGH { background: var(--high); color: #fff; }
+  .badge.MEDIUM { background: var(--medium); color: #000; }
+  .badge.LOW { background: var(--low); color: #000; }
+  .finding-id { color: var(--dim); font-size: 0.85rem; font-weight: 600; }
+  .finding-title { font-weight: 600; }
+  .finding-location { color: var(--dim); font-size: 0.85rem; margin-bottom: 0.5rem; }
+  .finding-desc { margin-bottom: 0.75rem; font-size: 0.9rem; }
+  .code {
+    background: #0d1117;
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    padding: 0.75rem;
+    font-family: 'SF Mono', 'Fira Code', monospace;
+    font-size: 0.8rem;
+    overflow-x: auto;
+    margin-bottom: 0.75rem;
+    color: var(--dim);
+  }
+  .remediation {
+    font-size: 0.85rem;
+    color: var(--green);
+  }
+  .remediation::before { content: "Fix: "; font-weight: 600; }
+  .footer {
+    text-align: center;
+    color: var(--dim);
+    margin-top: 2rem;
+    font-size: 0.8rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+  }
+  .footer a { color: var(--blue, #58a6ff); text-decoration: none; }
+  .no-findings {
+    text-align: center;
+    padding: 3rem;
+    color: var(--green);
+    font-size: 1.2rem;
+  }
+</style>
+</head>
+<body>
+  <h1>RAGGuard Security Report</h1>
+  <div class="meta">
+    Target: <code>{{ target }}</code> &middot; {{ timestamp }}
+  </div>
+
+  <div class="stats">
+    <div class="stat high">
+      <div class="number">{{ high }}</div>
+      <div class="label">High</div>
+    </div>
+    <div class="stat medium">
+      <div class="number">{{ medium }}</div>
+      <div class="label">Medium</div>
+    </div>
+    <div class="stat low">
+      <div class="number">{{ low }}</div>
+      <div class="label">Low</div>
+    </div>
+    <div class="stat total">
+      <div class="number">{{ total }}</div>
+      <div class="label">Total</div>
+    </div>
+  </div>
+
+  {% if not findings %}
+  <div class="no-findings">No security findings detected.</div>
+  {% endif %}
+
+  {% for f in findings %}
+  <div class="finding sev-{{ f.severity }}">
+    <div class="finding-header">
+      <span class="finding-id">{{ f.id }}</span>
+      <span class="badge {{ f.severity }}">{{ f.severity }}</span>
+      <span class="finding-title">{{ f.title }}</span>
+    </div>
+    <div class="finding-location">{{ f.file_path }}:{{ f.line_number }}{% if f.cwe_id %} &middot; {{ f.cwe_id }}{% endif %}</div>
+    <div class="finding-desc">{{ f.description }}</div>
+    {% if f.code_snippet %}
+    <div class="code">{{ f.code_snippet | e }}</div>
+    {% endif %}
+    <div class="remediation">{{ f.remediation }}</div>
+  </div>
+  {% endfor %}
+
+  <div class="footer">
+    Generated by <a href="https://github.com/HrushiYadav/ragguard">RAGGuard</a>
+  </div>
+</body>
+</html>