owasp-guard-cli 0.2.0__py3-none-any.whl

owasp_guard/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ['__version__']
+__version__ = '0.2.0'
+

owasp_guard/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+if __name__ == '__main__':
+    main()
+

owasp_guard/cli.py

@@ -0,0 +1,507 @@
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from .config import CONFIG_FILE, ensure_api_key, save_api_key
+from .errors import (
+    ApiError,
+    ConfigError,
+    InputError,
+    OwaspGuardError,
+    ReportError,
+    ScanError,
+)
+from .reporting import write_reports
+from .scanner import run_scan
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+from rich.text import Text
+
+
+DEFAULT_MODEL = "llama-3.1-8b-instant"
+TOOL_NAME = "owasp-guard"
+console = Console(safe_box=True)
+
+
+class ScanUI:
+    def __init__(
+        self, target_path: Path, output_dir: Path, model: str, max_files: int | None
+    ) -> None:
+        self.target_path = target_path
+        self.output_dir = output_dir
+        self.model = model
+        self.max_files = max_files
+        self._progress: Progress | None = None
+        self._task_id: int | None = None
+
+    def render_intro(self) -> None:
+        title = Text(" OWASP Guard ", style="bold black on cyan")
+        subtitle = Text("Secure Code Inspection Pipeline", style="bold white")
+        console.print(
+            Panel.fit(Text.assemble(title, "\n", subtitle), border_style="cyan")
+        )
+
+        meta = Table.grid(padding=(0, 2))
+        meta.add_column(style="bold cyan", justify="right")
+        meta.add_column(style="white")
+        meta.add_row("Target", str(self.target_path))
+        meta.add_row("Output", str(self.output_dir))
+        meta.add_row("Model", self.model)
+        meta.add_row("Scope", str(self.max_files) if self.max_files else "all files")
+        console.print(meta)
+        console.print()
+
+    def start_analyzer(self, total_chunks: int) -> None:
+        if total_chunks <= 0:
+            return
+        self._progress = Progress(
+            SpinnerColumn(spinner_name="line", style="cyan"),
+            TextColumn("[bold cyan]{task.description}"),
+            BarColumn(bar_width=32, complete_style="green", finished_style="green"),
+            TaskProgressColumn(),
+            TimeElapsedColumn(),
+            transient=False,
+            console=console,
+        )
+        self._progress.start()
+        self._task_id = self._progress.add_task("Analyzing chunks", total=total_chunks)
+
+    def update_analyzer(self, index: int, total: int, file_name: str) -> None:
+        if self._progress is None or self._task_id is None:
+            self.start_analyzer(total)
+        if self._progress is not None and self._task_id is not None:
+            self._progress.update(
+                self._task_id, completed=index, description=f"Analyzing {file_name}"
+            )
+
+    def finish_analyzer(self) -> None:
+        if self._progress is not None:
+            self._progress.stop()
+            self._progress = None
+            self._task_id = None
+
+    def progress_callback(self, stage: str, message: str, data: dict[str, Any]) -> None:
+        if stage == "collect_start":
+            console.print(f"[bold cyan]INFO[/] {message}...")
+            return
+        if stage == "collect_done":
+            console.print(
+                f"[bold green]DONE[/] Files collected: [bold]{data.get('total_files', 0)}[/]"
+            )
+            return
+        if stage == "chunk_file":
+            index = int(data.get("index", 0))
+            total = int(data.get("total", 0))
+            chunks = int(data.get("chunks", 0))
+            file_name = Path(str(data.get("file", ""))).name
+            console.print(
+                f"[bold blue]STEP[/] Chunked [bold]{file_name}[/] "
+                f"({index}/{total}) -> {chunks} chunk(s)"
+            )
+            return
+        if stage == "chunk_done":
+            console.print(
+                f"[bold green]DONE[/] Total chunks prepared: [bold]{data.get('total_chunks', 0)}[/]"
+            )
+            return
+        if stage == "analyze_chunk":
+            index = int(data.get("index", 0))
+            total = int(data.get("total", 0))
+            file_name = Path(str(data.get("file", ""))).name
+            self.update_analyzer(index, total, file_name)
+            return
+        if stage == "analyze_done":
+            self.finish_analyzer()
+            console.print(
+                f"[bold green]DONE[/] Initial findings detected: [bold]{data.get('findings', 0)}[/]"
+            )
+            return
+        if stage == "verify_start":
+            console.print(
+                f"[bold cyan]INFO[/] {message} ([bold]{data.get('total', 0)}[/] finding(s))..."
+            )
+            return
+        if stage == "verify_done":
+            console.print(
+                f"[bold green]DONE[/] Verification kept [bold]{data.get('kept', 0)}[/]/[bold]{data.get('total', 0)}[/]"
+            )
+            return
+        if stage == "dedup_done":
+            console.print(
+                f"[bold green]DONE[/] Deduplicated findings: [bold]{data.get('after', 0)}[/] "
+                f"(from {data.get('before', 0)})"
+            )
+            return
+
+    def render_outcome(self, json_path: Path, md_path: Path, findings: int) -> None:
+        status_color = "red" if findings > 0 else "green"
+        status_text = "Issues found" if findings > 0 else "No issues found"
+        summary = Table.grid(padding=(0, 1))
+        summary.add_column(style="bold cyan", justify="right")
+        summary.add_column(style="white")
+        summary.add_row("Status", f"[bold {status_color}]{status_text}[/]")
+        summary.add_row("Findings", str(findings))
+        summary.add_row("JSON", str(json_path.resolve()))
+        summary.add_row("Markdown", str(md_path.resolve()))
+        console.print()
+        console.print(
+            Panel(summary, title="[bold]Scan Summary[/bold]", border_style=status_color)
+        )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    prog_name = Path(sys.argv[0]).name or TOOL_NAME
+    parser = argparse.ArgumentParser(
+        prog=prog_name,
+        description="OWASP Guard CLI - Prompt-engineered secure code inspector",
+        epilog=(
+            "Examples:\n"
+            f"  {prog_name} init\n"
+            f"  {prog_name} init --api-key gsk_xxx\n"
+            f"  {prog_name} scan ./test --output-dir outputs\n"
+            f"  {prog_name} scan ./juice-shop --max-files 10 --model llama-3.1-8b-instant\n"
+            f"  {prog_name} help\n"
+            f"  {prog_name} help scan"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    sub = parser.add_subparsers(
+        dest="command",
+        required=True,
+        title="Actions",
+        description="Use one action at a time.",
+    )
+
+    init_cmd = sub.add_parser(
+        "init",
+        help="Initialize local configuration",
+        description=(
+            "Store a Groq API key in local user config.\n"
+            "Default location: ~/.owasp_guard/config.json"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    init_cmd.add_argument(
+        "--api-key",
+        help="Groq API key. If omitted, input is requested securely.",
+    )
+
+    scan_cmd = sub.add_parser(
+        "scan",
+        help="Scan repository or file",
+        description=(
+            "Scan source code for OWASP Top 10 findings and write:\n"
+            "  report.json  (structured)\n"
+            "  report.md    (human readable)"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    scan_cmd.add_argument("path", help="Target path: directory or single source file")
+    scan_cmd.add_argument(
+        "--output-dir",
+        default=".",
+        help="Output directory for report.json and report.md (default: current directory)",
+    )
+    scan_cmd.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=f"Groq model name (default: {DEFAULT_MODEL})",
+    )
+    scan_cmd.add_argument(
+        "--max-files",
+        type=int,
+        default=None,
+        help="Optional file limit for fixed-scope evaluation (example: 10)",
+    )
+
+    help_cmd = sub.add_parser(
+        "help",
+        help="Show detailed help pages",
+        description="Show detailed help and usage playbooks for the tool.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    help_cmd.add_argument(
+        "topic",
+        nargs="?",
+        choices=["init", "scan", "reports", "errors"],
+        help="Optional topic-specific help page",
+    )
+    return parser
+
+
+def _show_top_level_help(prog_name: str) -> int:
+    header = Text.assemble(
+        (" OWASP Guard ", "bold black on cyan"),
+        "\n",
+        ("Professional OWASP Top 10 Code Security Scanner", "bold white"),
+    )
+    console.print(Panel.fit(header, border_style="cyan"))
+
+    actions = Table(
+        title="Actions", title_style="bold cyan", show_lines=False, box=None
+    )
+    actions.add_column("Command", style="bold")
+    actions.add_column("Description", style="white")
+    actions.add_row("init", "Store API key in local secure config")
+    actions.add_row("scan", "Scan repository or file and generate reports")
+    actions.add_row("help", "Show detailed usage help by topic")
+    console.print(actions)
+
+    examples = Table(
+        title="Examples", title_style="bold cyan", show_header=False, box=None
+    )
+    examples.add_column(style="green")
+    examples.add_row(f"{prog_name} init")
+    examples.add_row(f"{prog_name} scan ./project --output-dir outputs")
+    examples.add_row(f"{prog_name} scan ./project --max-files 10")
+    examples.add_row(f"{prog_name} help scan")
+    console.print(examples)
+
+    options = Table(
+        title="Global Options", title_style="bold cyan", show_header=False, box=None
+    )
+    options.add_column(style="bold")
+    options.add_column(style="white")
+    options.add_row("-h, --help, --h", "Show this help screen")
+    options.add_row("", "")
+    options.add_row(
+        "Exit Codes",
+        "0: success/no findings, 1: findings found, 2: invalid usage, 3: runtime error",
+    )
+    console.print(options)
+    return 0
+
+
+def _show_help(topic: str | None) -> int:
+    if topic == "init":
+        console.print(
+            Panel.fit(
+                "Init command\n\n"
+                "Purpose:\n"
+                "  Save a Groq API key once for future scans.\n\n"
+                "Usage:\n"
+                "  owasp-guard init\n"
+                "  owasp-guard init --api-key gsk_xxx\n\n"
+                "Storage:\n"
+                "  ~/.owasp_guard/config.json\n",
+                title="[bold]Help: init[/bold]",
+                border_style="cyan",
+            )
+        )
+        return 0
+    if topic == "scan":
+        console.print(
+            Panel.fit(
+                "Scan command\n\n"
+                "Purpose:\n"
+                "  Analyze a repository or single file and generate OWASP reports.\n\n"
+                "Usage:\n"
+                "  owasp-guard scan ./project --output-dir outputs\n"
+                "  owasp-guard scan ./project --max-files 10\n"
+                "  owasp-guard scan ./file.py --model llama-3.1-8b-instant\n\n"
+                "Outputs:\n"
+                "  report.json (structured)\n"
+                "  report.md   (executive + detailed)\n",
+                title="[bold]Help: scan[/bold]",
+                border_style="cyan",
+            )
+        )
+        return 0
+    if topic == "reports":
+        console.print(
+            Panel.fit(
+                "Reports\n\n"
+                "report.json includes:\n"
+                "  metadata, severity summary, OWASP distribution, per-file distribution, findings list.\n\n"
+                "report.md includes:\n"
+                "  executive summary, risk snapshot, findings index, detailed findings,\n"
+                "  remediation roadmap, and methodology.",
+                title="[bold]Help: reports[/bold]",
+                border_style="cyan",
+            )
+        )
+        return 0
+    if topic == "errors":
+        console.print(
+            Panel.fit(
+                "Error Handling\n\n"
+                "Configuration errors:\n"
+                "  Missing/invalid API key, unreadable config file.\n\n"
+                "Input errors:\n"
+                "  Path not found, unsupported extension, no source files, invalid max-files.\n\n"
+                "API errors:\n"
+                "  Invalid key, model unavailable, request failure/timeout.\n\n"
+                "Report errors:\n"
+                "  Output directory not writable, report serialization/write failure.\n",
+                title="[bold]Help: errors[/bold]",
+                border_style="cyan",
+            )
+        )
+        return 0
+
+    console.print(
+        Panel.fit(
+            "OWASP Guard Help\n\n"
+            "Quick start:\n"
+            "  1) owasp-guard init\n"
+            "  2) owasp-guard scan ./project --output-dir outputs\n\n"
+            "Topic help:\n"
+            "  owasp-guard help init\n"
+            "  owasp-guard help scan\n"
+            "  owasp-guard help reports\n"
+            "  owasp-guard help errors\n\n"
+            "If installed with alias entrypoint:\n"
+            "  owasp help\n"
+            "  owasp help scan",
+            title="[bold]Help[/bold]",
+            border_style="cyan",
+        )
+    )
+    return 0
+
+
+def _handle_init(args: argparse.Namespace) -> int:
+    if args.api_key:
+        path = save_api_key(args.api_key)
+    else:
+        key = ensure_api_key(interactive=True)
+        path = save_api_key(key)
+    console.print(
+        Panel.fit(
+            f"[green]API key saved[/green]\n[bold]Path:[/bold] {path}",
+            title="[bold]Initialization Complete[/bold]",
+            border_style="green",
+        )
+    )
+    return 0
+
+
+def _handle_scan(args: argparse.Namespace) -> int:
+    api_key = ensure_api_key(interactive=True)
+    if args.max_files is not None and args.max_files <= 0:
+        raise InputError("--max-files must be greater than 0.")
+    output_dir = Path(args.output_dir).resolve()
+    if output_dir.exists() and not output_dir.is_dir():
+        raise InputError(
+            f"--output-dir must be a directory path, got file: {output_dir}"
+        )
+    ui = ScanUI(
+        target_path=Path(args.path).resolve(),
+        output_dir=output_dir,
+        model=args.model,
+        max_files=args.max_files,
+    )
+    ui.render_intro()
+    report = run_scan(
+        target_path=args.path,
+        model_name=args.model,
+        api_key=api_key,
+        max_files=args.max_files,
+        progress_callback=ui.progress_callback,
+    )
+    ui.finish_analyzer()
+    json_path, md_path = write_reports(report, output_dir=args.output_dir)
+    ui.render_outcome(
+        json_path=json_path, md_path=md_path, findings=report.total_findings
+    )
+    return 1 if report.total_findings > 0 else 0
+
+
+def _render_error_panel(kind: str, message: str, hint: str | None = None) -> None:
+    body = f"[bold]{kind}[/bold]\n\n{message}"
+    if hint:
+        body += f"\n\n[bold]Hint:[/bold] {hint}"
+    console.print(
+        Panel.fit(
+            body, title="[bold red]Execution Failed[/bold red]", border_style="red"
+        )
+    )
+
+
+def main() -> None:
+    raw_args = sys.argv[1:]
+    prog_name = Path(sys.argv[0]).name or TOOL_NAME
+    if not raw_args or raw_args[0] in {"-h", "--help", "--h"}:
+        sys.exit(_show_top_level_help(prog_name))
+    if (
+        len(raw_args) >= 2
+        and raw_args[1] in {"-h", "--help", "--h"}
+        and raw_args[0] in {"init", "scan", "help"}
+    ):
+        topic = (
+            raw_args[0]
+            if raw_args[0] in {"init", "scan"}
+            else (raw_args[2] if len(raw_args) >= 3 else None)
+        )
+        sys.exit(_show_help(topic))
+
+    parser = _build_parser()
+    args = parser.parse_args()
+    try:
+        if args.command == "init":
+            code = _handle_init(args)
+        elif args.command == "scan":
+            code = _handle_scan(args)
+        elif args.command == "help":
+            code = _show_help(args.topic)
+        else:
+            parser.print_help()
+            code = 2
+    except KeyboardInterrupt:
+        console.print()
+        console.print("[yellow]Interrupted.[/]")
+        code = 130
+    except ConfigError as exc:
+        _render_error_panel(
+            "Configuration Error",
+            str(exc),
+            hint=f"Run [bold]{TOOL_NAME} init[/] to configure credentials.",
+        )
+        code = 3
+    except InputError as exc:
+        _render_error_panel(
+            "Input Error",
+            str(exc),
+            hint=f"Run [bold]{TOOL_NAME} help scan[/] for valid usage.",
+        )
+        code = 3
+    except ApiError as exc:
+        _render_error_panel(
+            "API Error",
+            str(exc),
+            hint="Check API key, internet access, and selected model.",
+        )
+        code = 3
+    except ReportError as exc:
+        _render_error_panel(
+            "Report Error",
+            str(exc),
+            hint="Check output directory permissions and available disk space.",
+        )
+        code = 3
+    except ScanError as exc:
+        _render_error_panel("Scan Error", str(exc))
+        code = 3
+    except OwaspGuardError as exc:
+        _render_error_panel("Application Error", str(exc))
+        code = 3
+    except Exception as exc:
+        _render_error_panel(
+            "Unexpected Error",
+            str(exc),
+            hint="Run again with a smaller scope and verify dependencies.",
+        )
+        if not CONFIG_FILE.exists():
+            console.print(f"Run first-time setup: [bold]{TOOL_NAME} init[/]")
+        code = 3
+    sys.exit(code)

owasp_guard/config.py

@@ -0,0 +1,65 @@
+import json
+import os
+from getpass import getpass
+from pathlib import Path
+
+from .errors import ConfigError
+
+
+CONFIG_DIR = Path.home() / ".owasp_guard"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def _load_config() -> dict:
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        raw = CONFIG_FILE.read_text(encoding="utf-8")
+        loaded = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Invalid config file format: {CONFIG_FILE} ({exc})") from exc
+    except OSError as exc:
+        raise ConfigError(f"Unable to read config file: {CONFIG_FILE} ({exc})") from exc
+    if not isinstance(loaded, dict):
+        raise ConfigError(f"Invalid config file structure: {CONFIG_FILE}")
+    return loaded
+
+
+def save_api_key(api_key: str) -> Path:
+    sanitized = api_key.strip()
+    if not sanitized:
+        raise ConfigError("API key cannot be empty.")
+    if not sanitized.startswith("gsk_"):
+        raise ConfigError("API key must start with 'gsk_'.")
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    payload = _load_config()
+    payload["groq_api_key"] = sanitized
+    try:
+        CONFIG_FILE.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"Unable to write config file: {CONFIG_FILE} ({exc})") from exc
+    return CONFIG_FILE
+
+
+def get_api_key() -> str | None:
+    from_env = os.getenv("GROQ_API_KEY")
+    if from_env:
+        return from_env.strip()
+    payload = _load_config()
+    key = payload.get("groq_api_key")
+    if isinstance(key, str) and key.strip():
+        return key.strip()
+    return None
+
+
+def ensure_api_key(interactive: bool = True) -> str:
+    key = get_api_key()
+    if key:
+        return key
+    if not interactive:
+        raise ConfigError("Groq API key not set. Run: owasp-guard init")
+    entered = getpass("Enter your Groq API key (input hidden): ").strip()
+    if not entered:
+        raise ConfigError("Empty API key. Run again with a valid key.")
+    save_api_key(entered)
+    return entered

owasp_guard/errors.py

@@ -0,0 +1,22 @@
+class OwaspGuardError(Exception):
+    """Base exception for all tool errors."""
+
+
+class ConfigError(OwaspGuardError):
+    """Configuration or credential setup issues."""
+
+
+class InputError(OwaspGuardError):
+    """Invalid or unsupported user input."""
+
+
+class ScanError(OwaspGuardError):
+    """General scan pipeline failures."""
+
+
+class ApiError(ScanError):
+    """Remote LLM API request failures."""
+
+
+class ReportError(OwaspGuardError):
+    """Report serialization or write failures."""

owasp_guard/models.py

@@ -0,0 +1,46 @@
+from pydantic import BaseModel, Field
+
+
+class CodeChunk(BaseModel):
+    file: str
+    line_start: int = Field(ge=1)
+    line_end: int = Field(ge=1)
+    context: str
+    code: str
+
+
+class Finding(BaseModel):
+    file: str
+    line_start: int = Field(ge=1)
+    line_end: int = Field(ge=1)
+    owasp_category: str
+    title: str
+    risk_summary: str
+    fix_recommendation: str
+    evidence: str
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class FindingsResponse(BaseModel):
+    findings: list[Finding] = Field(default_factory=list)
+
+
+class VerificationDecision(BaseModel):
+    index: int = Field(ge=0)
+    keep: bool
+    normalized_owasp_category: str
+    normalized_title: str
+    adjusted_confidence: float = Field(ge=0.0, le=1.0)
+    reason: str
+
+
+class VerificationResponse(BaseModel):
+    decisions: list[VerificationDecision] = Field(default_factory=list)
+
+
+class ScanReport(BaseModel):
+    scanned_path: str
+    total_files: int
+    total_chunks: int
+    total_findings: int
+    findings: list[Finding] = Field(default_factory=list)