github-guardian 1.0.0__py3-none-any.whl

core/__init__.py

@@ -0,0 +1 @@
+# Marks the core directory as a Python package

core/hook.py

@@ -0,0 +1,49 @@
+import os
+import stat
+import platform
+
+HOOK_SCRIPT = """#!/usr/bin/env bash
+# GitHub Guardian Pre-Commit Shield
+
+echo "🛡️ GitHub Guardian: Running Pre-Commit Shield Audit..."
+
+# We use the isolated virtual environment from the CLI directory
+CLI_DIR="$(git rev-parse --show-toplevel)/github-guardian-cli"
+$CLI_DIR/venv/bin/python $CLI_DIR/guardian.py scan-local . --hook
+
+if [ $? -ne 0 ]; then
+    echo "❌ COMMIT BLOCKED! Secrets or semantic vulnerabilities were detected in your staging area."
+    echo "Please fix the issues. To bypass the shield (NOT RECOMMENDED), use 'git commit --no-verify'."
+    exit 1
+fi
+
+echo "✅ Code looks clean. Proceeding with commit."
+exit 0
+"""
+
+import subprocess
+
+def install_pre_commit_hook(console):
+    try:
+        git_root_proc = subprocess.run(["git", "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=True)
+        git_root = git_root_proc.stdout.strip()
+    except Exception:
+        console.print("[bold red]Error:[/bold red] Not inside a git repository. Cannot install hook.")
+        return
+        
+    git_dir = os.path.join(git_root, ".git")
+    hook_path = os.path.join(git_dir, "hooks", "pre-commit")
+    
+    try:
+        with open(hook_path, "w") as f:
+            f.write(HOOK_SCRIPT)
+            
+        # Make the bash script executable (Unix/macOS only)
+        if platform.system() != 'Windows':
+            st = os.stat(hook_path)
+            os.chmod(hook_path, st.st_mode | stat.S_IEXEC)
+        
+        console.print(f"[bold green]✅ Success![/bold green] Pre-commit shield installed at: {hook_path}")
+        console.print("[italic]Your commits will now be securely blocked if secrets or SAST vulnerabilities are staged.[/italic]")
+    except Exception as e:
+        console.print(f"[bold red]Failed to install hook:[/bold red] {str(e)}")

core/remote.py

@@ -0,0 +1,76 @@
+import httpx
+import time
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+BACKEND_URL = "http://localhost:8000/api/v1"
+
+def run_remote_scan(owner: str, repo: str, console):
+    try:
+        # 1. Trigger the asynchronous scan task on FastAPI
+        with console.status("[bold cyan]Triggering remote forensic scan on Guardian Core...[/bold cyan]") as status:
+            res = httpx.post(f"{BACKEND_URL}/scan", json={"owner": owner, "repo_name": repo}, timeout=10.0)
+            if res.status_code != 200:
+                console.print(f"[bold red]Failed to trigger scan. Status Code: {res.status_code}[/bold red]")
+                console.print(res.text)
+                return
+            
+            task_id = res.json().get("task_id")
+            console.print(f"[green]Scan initiated successfully. Task ID:[/green] {task_id}\n")
+            
+        # 2. Poll the FastAPI backend for status updates
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            transient=True,
+        ) as progress:
+            task = progress.add_task(description="Initializing scanners...", total=None)
+            
+            while True:
+                status_res = httpx.get(f"{BACKEND_URL}/scan/status/{task_id}", timeout=10.0)
+                if status_res.status_code != 200:
+                    time.sleep(2)
+                    continue
+                    
+                data = status_res.json()
+                
+                if data.get("status") == "completed":
+                    progress.update(task, description="[bold green]Scan Completed! Processing AI Report...[/bold green]")
+                    break
+                elif data.get("status") == "failed":
+                    progress.update(task, description=f"[bold red]Scan Failed: {data.get('error')}[/bold red]")
+                    return
+                else:
+                    msg = data.get("message", "Processing pipelines...")
+                    progress.update(task, description=f"[cyan]Engine Status:[/cyan] {msg}")
+                    
+                time.sleep(2)
+                
+        # 3. Download and Render the final AI enriched report
+        res_data = httpx.get(f"{BACKEND_URL}/scan/status/{task_id}").json()
+        report = res_data.get("report", {})
+        
+        score = report.get("score", 0.0)
+        verdict = report.get("verdict", "Unknown")
+        
+        console.print("\n[bold underline]🛡️ GitHub Guardian Audit Report[/bold underline]")
+        console.print(f"\nFinal AI Dampened Score: [bold {'red' if score > 5 else 'green'}]{score} / 10.0[/bold]")
+        console.print(f"Verdict: [italic]{verdict}[/italic]\n")
+        
+        # Table of Actionable Findings
+        if report.get("negatives"):
+            vuln_table = Table(title="Actionable Architectural Threats", show_header=True, header_style="bold red")
+            vuln_table.add_column("Issue Detected", style="white")
+            
+            for neg in report.get("negatives"):
+                vuln_table.add_row(neg)
+                
+            console.print(vuln_table)
+            
+        if report.get("positives"):
+            console.print("\n[bold green]Security Positives:[/bold green]")
+            for pos in report.get("positives"):
+                console.print(f"  [green]✔[/green] {pos}")
+        
+    except Exception as e:
+        console.print(f"[bold red]Critical Error during remote scan orchestration:[/bold red] {str(e)}")

core/scanner.py

@@ -0,0 +1,97 @@
+import os
+import re
+from rich.table import Table
+
+# Re-using the professional-grade patterns from the backend
+SECRET_PATTERNS = {
+    "AWS Access Key": r'AKIA[0-9A-Z]{16}',
+    "GitHub Token": r'ghp_[0-9a-zA-Z]{36}',
+    "Slack Webhook": r'https://hooks\.slack\.com/services/T[0-9A-Z]{8}/B[0-9A-Z]{8}/[0-9a-zA-Z]{24}',
+    "Stripe API Key": r'sk_live_[0-9a-zA-Z]{24}',
+    "Private Key": r'-----BEGIN (?:RSA|OPENSSH) PRIVATE KEY-----',
+    "Google API Key": r'AIza[0-9A-Za-z\-_]{35}'
+}
+
+SAST_PATTERNS = {
+    "SQL Injection (Raw Query)": r"\.execute\(\".*%\s*\"",
+    "Insecure Rendering (XSS)": r"dangerouslySetInnerHTML",
+    "Hardcoded Auth/Secret": r"password\s*=\s*['\"][^'\"]+['\"]"
+}
+
+def ask_gitignore(files):
+    import sys
+    try:
+        with open("/dev/tty", "w") as tty_out, open("/dev/tty", "r") as tty_in:
+            tty_out.write("\n⚠️  Would you like to automatically add these vulnerable files to .gitignore? (y/N): ")
+            tty_out.flush()
+            ans = tty_in.readline().strip().lower()
+            return ans in ['y', 'yes']
+    except Exception:
+        ans = input("\n⚠️  Would you like to automatically add these vulnerable files to .gitignore? (y/N): ")
+        return ans.lower() in ['y', 'yes']
+
+def run_local_scan(path: str, console, hook_mode: bool = False) -> bool:
+    console.print(f"[*] Scanning local directory: [yellow]{os.path.abspath(path)}[/yellow]...\n")
+    findings = []
+    
+    for root, _, files in os.walk(path):
+        # Ignore common build/dependency directories
+        if any(x in root for x in [".git", "node_modules", "venv", "__pycache__"]):
+            continue
+        for file in files:
+            ext = os.path.splitext(file)[1]
+            if ext in [".png", ".jpg", ".pdf", ".zip", ".pyc"]: 
+                continue
+                
+            # Skip the scanner scripts themselves to prevent false positives!
+            if file in ["scanner.py", "leak_forensics.py", "sast_analyzer.py"]:
+                continue
+                
+            filepath = os.path.join(root, file)
+            try:
+                with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+                    lines = f.readlines()
+                    
+                for line_idx, line in enumerate(lines, 1):
+                    # Check for Secrets
+                    for name, pat in SECRET_PATTERNS.items():
+                        if re.search(pat, line):
+                            findings.append((filepath, line_idx, "SECRET LEAK", name))
+                            
+                    # Check for Semantic vulnerabilities
+                    for name, pat in SAST_PATTERNS.items():
+                        if re.search(pat, line):
+                            findings.append((filepath, line_idx, "SAST VULN", name))
+            except Exception:
+                pass
+
+    if not findings:
+        console.print("[bold green]✅ No local leaks or vulnerabilities detected. Ready to push![/bold green]")
+        return True
+        
+    table = Table(title="Guardian Local Shield Findings")
+    table.add_column("File Path", style="cyan")
+    table.add_column("Line", justify="right", style="magenta")
+    table.add_column("Threat Class", style="yellow")
+    table.add_column("Pattern Matched", style="red")
+    
+    for f in findings:
+        table.add_row(os.path.relpath(f[0], path), str(f[1]), f[2], f[3])
+        
+    console.print(table)
+    
+    if hook_mode:
+        vulnerable_files = list(set([os.path.relpath(f[0], path) for f in findings]))
+        if ask_gitignore(vulnerable_files):
+            gitignore_path = os.path.join(path, ".gitignore")
+            with open(gitignore_path, "a") as gf:
+                gf.write("\n# GitHub Guardian: Auto-ignored vulnerable files\n")
+                for vf in vulnerable_files:
+                    gf.write(f"{vf}\n")
+            console.print("\n[bold green]✅ Vulnerable files appended to .gitignore![/bold green]")
+            console.print("[yellow]Note: If the files were already tracked by git, you must also run 'git rm --cached <file>'.[/yellow]")
+            console.print("[yellow]Please review your changes and try committing again.[/yellow]")
+            return False
+
+    console.print("\n[bold red]❌ SCAN FAILED! Active vulnerabilities were detected locally.[/bold red]")
+    return False

github_guardian-1.0.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: github-guardian
+Version: 1.0.0
+Summary: Deep Forensic Security Audit Engine & Pre-Commit Shield
+Author: GitHub Guardian Team
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: httpx>=0.27.0
+Dynamic: author
+Dynamic: requires-dist
+Dynamic: summary

github_guardian-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+guardian.py,sha256=JelEnNRwGoAEMJcf0wJLiZCK2BeOyBK8RWVwzQfD7vA,1456
+core/__init__.py,sha256=Ugc5jnfm_Bl5kgVR4UaOoOdlv9fUr5yP3nGGy9kg_GA,47
+core/hook.py,sha256=arqBruVkmSER6Z9M5SEMIjXAU6QY6LKJSNPH5NzhZ4U,1831
+core/remote.py,sha256=RTmPp42XGeixC8cIz-SEIZjNOI-1Sz2TD1IEI2darcA,3544
+core/scanner.py,sha256=m6yazu4qz9q8pWMpzCLCPihP-ne4ayKqouXhEkkkaN8,4345
+github_guardian-1.0.0.dist-info/METADATA,sha256=y4LP2ERTWKrmFqyFii-I-Kciu5xaa_oQQiMzvcTFEGs,294
+github_guardian-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+github_guardian-1.0.0.dist-info/entry_points.txt,sha256=aaXgoBHQZpeppnCgqM0-1Bm4lYN9kBnXgC-KYo79M3o,42
+github_guardian-1.0.0.dist-info/top_level.txt,sha256=ZMNVow5B-nJtHwT3irGO0hUFjolR2TXv0IDD0dMeS_8,14
+github_guardian-1.0.0.dist-info/RECORD,,

github_guardian-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

github_guardian-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+guardian = guardian:app

github_guardian-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+core
+guardian

guardian.py

@@ -0,0 +1,34 @@
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from core.scanner import run_local_scan
+from core.remote import run_remote_scan
+from core.hook import install_pre_commit_hook
+
+app = typer.Typer(help="GitHub Guardian - Forensic Security Audit CLI")
+console = Console()
+
+@app.command()
+def scan_local(
+    path: str = typer.Argument(".", help="Path to scan locally"),
+    hook_mode: bool = typer.Option(False, "--hook", help="Run in git hook mode (prompts to gitignore)")
+):
+    """Scan local directory for exposed secrets and vulnerabilities before committing."""
+    console.print(Panel.fit("[bold cyan]GitHub Guardian[/bold cyan] - Local Shield", border_style="cyan"))
+    run_local_scan(path, console, hook_mode)
+
+@app.command()
+def scan_remote(owner: str = typer.Argument(..., help="GitHub Repository Owner"), 
+                repo: str = typer.Argument(..., help="GitHub Repository Name")):
+    """Trigger an AI-driven forensic scan on the Guardian backend."""
+    console.print(Panel.fit(f"[bold magenta]GitHub Guardian[/bold magenta] - Remote Scan: {owner}/{repo}", border_style="magenta"))
+    run_remote_scan(owner, repo, console)
+
+@app.command()
+def hook_install():
+    """Install the Pre-Commit Shield to block insecure commits."""
+    console.print(Panel.fit("[bold green]GitHub Guardian[/bold green] - Pre-Commit Hook", border_style="green"))
+    install_pre_commit_hook(console)
+
+if __name__ == "__main__":
+    app()