permi 0.1.1__tar.gz

permi-0.1.1/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: permi
+Version: 0.1.1
+Summary: AI-powered vulnerability scanner for Nigerian developers
+Requires-Python: >=3.9
+Requires-Dist: python-dotenv
+Requires-Dist: colorama
+Requires-Dist: click
+Requires-Dist: requests

permi-0.1.1/README.md

@@ -0,0 +1,87 @@
+# Permi
+
+**AI-powered vulnerability scanner for Nigerian developers and global SMBs.**
+
+Permi scans your code for security vulnerabilities and uses AI to filter out
+false positives — so you only see findings that actually matter.
+
+Built in Nigeria. For Nigeria. Then for the world.
+
+---
+
+## What Permi detects
+
+- SQL Injection (string concatenation, f-strings, % formatting)
+- Cross-Site Scripting (innerHTML, document.write, Jinja2 |safe)
+- Hardcoded secrets (passwords, API keys, AWS keys, Paystack/Flutterwave keys)
+- Insecure practices (eval/exec, pickle.loads, SSL verification disabled, debug mode)
+- USSD vulnerabilities (Nigerian-specific — unvalidated sessionId, phoneNumber, serviceCode)
+
+---
+
+## Installation
+```bash
+pip install permi
+```
+
+Requires Python 3.9+
+
+---
+
+## Usage
+
+**Scan a local project:**
+```bash
+permi scan --path ./myapp
+```
+
+**Scan a GitHub repository:**
+```bash
+permi scan --path https://github.com/user/repo
+```
+
+**Show only high severity findings:**
+```bash
+permi scan --path ./myapp --severity high
+```
+
+**Output as JSON (for CI/CD pipelines):**
+```bash
+permi scan --path ./myapp --output json
+```
+
+**Skip AI filter (offline mode):**
+```bash
+permi scan --path ./myapp --offline
+```
+
+---
+
+## Setup
+
+Permi uses [OpenRouter](https://openrouter.ai) for AI-powered false positive
+filtering. Create a free account, generate an API key, and add it to a `.env`
+file in your project root:
+OPENROUTER_API_KEY=sk-or-your-key-here
+
+No API key? Use `--offline` mode. All findings are shown unfiltered.
+
+---
+
+## Example output
+[1] [HIGH] SQL001  SQL Injection — string concatenation
+File  : app/auth.py
+Line  : 42
+Code  : cursor.execute("SELECT * FROM users WHERE name = " + username)
+Why   : Raw string concatenation used to build a SQL query.
+AI    : REAL  User input is directly embedded into a SQL query with no sanitisation.
+
+---
+
+## Built by
+
+Peter N. D. — Cybersecurity student, University of Jos, Nigeria.
+
+---
+
+*Permi is in active development. Feedback and contributions welcome.*

permi-0.1.1/ai_filter/filter.py

@@ -0,0 +1,71 @@
+# ai_filter/filter.py
+# Takes a list of raw findings, runs each through the LLM,
+# saves the verdict back to the database, and returns only
+# the findings the LLM marked as REAL.
+
+from ai_filter.llm_client import analyse
+from db.database import get_connection
+
+
+def _update_finding_verdict(conn, finding_id: int, verdict: str, explanation: str) -> None:
+    """Write the AI verdict back to the findings table."""
+    conn.execute("""
+        UPDATE findings
+        SET ai_verdict     = ?,
+            ai_explanation = ?
+        WHERE id = ?
+    """, (verdict, explanation, finding_id))
+    conn.commit()
+
+
+def run_filter(findings: list[dict], offline: bool = False) -> list[dict]:
+    """
+    Run the AI filter over a list of findings.
+
+    Args:
+        findings: Raw findings list from the scanner.
+        offline:  If True, skip all API calls and return everything as REAL.
+
+    Returns:
+        Only the findings the LLM (or offline fallback) marked as REAL.
+    """
+    if not findings:
+        return []
+
+    if offline:
+        print("[Permi] Offline mode — AI filter skipped, showing all findings.\n")
+        return findings
+
+    print(f"[Permi] Running AI filter on {len(findings)} finding(s)...\n")
+
+    conn        = get_connection()
+    real        = []
+    fp_count    = 0
+
+    for i, finding in enumerate(findings, start=1):
+        print(f"  [{i}/{len(findings)}] {finding['rule_id']} "
+              f"line {finding['line_number']} — ", end="", flush=True)
+
+        # Send to LLM
+        result = analyse(finding)
+
+        verdict     = result["ai_verdict"]
+        explanation = result["ai_explanation"]
+
+        print(f"{verdict}  {explanation}")
+
+        # Save verdict back to DB
+        if "id" in finding:
+            _update_finding_verdict(conn, finding["id"], verdict, explanation)
+
+        if verdict == "REAL":
+            real.append(result)
+        else:
+            fp_count += 1
+
+    conn.close()
+
+    print(f"\n[Permi] Filter complete — "
+          f"{len(real)} real  |  {fp_count} false positive(s) removed\n")
+
+    return real

permi-0.1.1/ai_filter/llm_client.py

@@ -0,0 +1,123 @@
+# ai_filter/llm_client.py
+# The only module in Permi that makes network requests.
+# Sends a finding to OpenRouter and returns a verdict:
+#   REAL  — this is a genuine vulnerability
+#   FP    — this is a false positive, ignore it
+
+import os
+import json
+import requests
+from dotenv import load_dotenv
+
+load_dotenv()
+
+OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")
+OPENROUTER_URL     = "https://openrouter.ai/api/v1/chat/completions"
+
+# We use DeepSeek V3 — fast, cheap, and very good at code analysis.
+# You can swap this for any model on openrouter.ai/models
+MODEL = "deepseek/deepseek-chat"
+
+# How many seconds to wait for the API before giving up
+TIMEOUT = 30
+
+
+def _build_prompt(finding: dict) -> str:
+    """
+    Build the prompt we send to the LLM for a single finding.
+    The prompt is structured so the model returns a predictable format
+    we can parse reliably.
+    """
+    return f"""You are a senior application security engineer reviewing automated scan results.
+
+A static analysis tool flagged the following finding. Your job is to decide if this is a REAL vulnerability or a FALSE POSITIVE (FP).
+
+--- FINDING ---
+Rule     : {finding['rule_id']} — {finding['rule_name']}
+Severity : {finding['severity']}
+File     : {finding['file']}
+Line     : {finding['line_number']}
+Code     : {finding['line_content']}
+Detail   : {finding['description']}
+---------------
+
+Instructions:
+- Answer with exactly one word on the first line: REAL or FP
+- On the second line, write one short sentence (max 20 words) explaining your verdict
+- Do not write anything else
+
+Example response:
+REAL
+The string concatenation directly embeds user input into a SQL query with no sanitisation.
+
+Your verdict:"""
+
+
+def analyse(finding: dict) -> dict:
+    """
+    Send one finding to the LLM and return the finding dict
+    updated with ai_verdict and ai_explanation.
+
+    If the API call fails for any reason (no key, network error,
+    bad response), we default to REAL so nothing gets silently dropped.
+    """
+    # If no API key is configured, skip the filter entirely
+    if not OPENROUTER_API_KEY:
+        finding["ai_verdict"]     = "REAL"
+        finding["ai_explanation"] = "No API key — AI filter skipped."
+        return finding
+
+    prompt = _build_prompt(finding)
+
+    try:
+        response = requests.post(
+            OPENROUTER_URL,
+            headers={
+                "Authorization": f"Bearer {OPENROUTER_API_KEY}",
+                "Content-Type":  "application/json",
+                "HTTP-Referer":  "https://github.com/permi",   # required by OpenRouter
+                "X-Title":       "Permi Security Scanner",
+            },
+            json={
+                "model": MODEL,
+                "messages": [
+                    {"role": "user", "content": prompt}
+                ],
+                "temperature": 0,     # we want deterministic, not creative
+                "max_tokens":  60,    # verdict + one sentence is plenty
+            },
+            timeout=TIMEOUT,
+        )
+        response.raise_for_status()
+
+    except requests.exceptions.Timeout:
+        finding["ai_verdict"]     = "REAL"
+        finding["ai_explanation"] = "API timeout — defaulting to REAL."
+        return finding
+
+    except requests.exceptions.RequestException as e:
+        finding["ai_verdict"]     = "REAL"
+        finding["ai_explanation"] = f"API error — defaulting to REAL. ({e})"
+        return finding
+
+    # ── Parse the response ────────────────────────────────────────────────────
+    try:
+        content = response.json()["choices"][0]["message"]["content"].strip()
+        lines   = content.splitlines()
+
+        verdict     = lines[0].strip().upper()
+        explanation = lines[1].strip() if len(lines) > 1 else "No explanation provided."
+
+        # Normalise — if the model returns anything unexpected, treat as REAL
+        if verdict not in ("REAL", "FP"):
+            verdict     = "REAL"
+            explanation = f"Unexpected verdict '{verdict}' — defaulting to REAL."
+
+        finding["ai_verdict"]     = verdict
+        finding["ai_explanation"] = explanation
+
+    except (KeyError, IndexError, json.JSONDecodeError) as e:
+        finding["ai_verdict"]     = "REAL"
+        finding["ai_explanation"] = f"Parse error — defaulting to REAL. ({e})"
+
+    return finding

permi-0.1.1/cli/formatter.py

@@ -0,0 +1,123 @@
+# cli/formatter.py
+# Handles all terminal output formatting.
+# Keeps colour logic completely separate from scan logic.
+
+from colorama import init, Fore, Style
+
+# Initialise colorama — required on Windows for ANSI colours to work
+init(autoreset=True)
+
+# Severity colours
+SEVERITY_COLOUR = {
+    "high":   Fore.RED,
+    "medium": Fore.YELLOW,
+    "low":    Fore.CYAN,
+}
+
+VERDICT_COLOUR = {
+    "REAL": Fore.RED,
+    "FP":   Fore.GREEN,
+}
+
+
+def _divider(char="─", width=72, colour=Fore.WHITE):
+    print(colour + char * width + Style.RESET_ALL)
+
+
+def print_banner():
+    """Print the Permi header banner."""
+    print()
+    print(Fore.CYAN + Style.BRIGHT + "┌─────────────────────────────────────────┐")
+    print(Fore.CYAN + Style.BRIGHT + "│        Permi — Security Scanner         │")
+    print(Fore.CYAN + Style.BRIGHT + "│   Built in Nigeria. For the World.      │")
+    print(Fore.CYAN + Style.BRIGHT + "└─────────────────────────────────────────┘")
+    print()
+
+
+def print_finding(finding: dict, index: int) -> None:
+    """
+    Print a single finding as a formatted block.
+    Each finding gets a numbered header, severity badge,
+    file location, code snippet, AI verdict, and explanation.
+    """
+    sev    = finding.get("severity", "low")
+    colour = SEVERITY_COLOUR.get(sev, Fore.WHITE)
+
+    _divider()
+
+    # ── Header line ───────────────────────────────────────────────────────────
+    print(
+        Fore.WHITE + Style.BRIGHT + f"  [{index}] " +
+        colour + Style.BRIGHT + f"[{sev.upper()}] " +
+        Fore.WHITE + Style.BRIGHT + finding.get("rule_id", "") +
+        Style.RESET_ALL + "  " +
+        finding.get("rule_name", "")
+    )
+
+    print()
+
+    # ── File and line ─────────────────────────────────────────────────────────
+    print(
+        Fore.WHITE + "  File  : " + Style.RESET_ALL +
+        finding.get("file", "unknown")
+    )
+    print(
+        Fore.WHITE + "  Line  : " + Style.RESET_ALL +
+        str(finding.get("line_number", "?"))
+    )
+
+    # ── Code snippet ──────────────────────────────────────────────────────────
+    print(
+        Fore.WHITE + "  Code  : " + Style.RESET_ALL +
+        Fore.YELLOW + finding.get("line_content", "") + Style.RESET_ALL
+    )
+
+    # ── Description ───────────────────────────────────────────────────────────
+    print(
+        Fore.WHITE + "  Why   : " + Style.RESET_ALL +
+        finding.get("description", "")
+    )
+
+    # ── AI verdict ────────────────────────────────────────────────────────────
+    verdict = finding.get("ai_verdict")
+    if verdict:
+        v_colour = VERDICT_COLOUR.get(verdict, Fore.WHITE)
+        print(
+            Fore.WHITE + "  AI    : " +
+            v_colour + Style.BRIGHT + verdict + Style.RESET_ALL +
+            "  " + finding.get("ai_explanation", "")
+        )
+
+    print()
+
+
+def print_results_human(findings: list[dict]) -> None:
+    """Print all findings in human-readable coloured format."""
+    if not findings:
+        print(Fore.GREEN + Style.BRIGHT + "\n  ✅  No real vulnerabilities found.\n")
+        return
+
+    for i, finding in enumerate(findings, start=1):
+        print_finding(finding, i)
+
+    _divider()
+
+
+def print_summary(findings: list[dict], raw_count: int) -> None:
+    """Print the final summary block."""
+    high   = sum(1 for f in findings if f["severity"] == "high")
+    medium = sum(1 for f in findings if f["severity"] == "medium")
+    low    = sum(1 for f in findings if f["severity"] == "low")
+    fp     = raw_count - len(findings)
+
+    print()
+    _divider("═")
+    print(Fore.WHITE + Style.BRIGHT + "  SCAN SUMMARY")
+    _divider("═")
+    print(f"  Total findings  : {Style.BRIGHT}{len(findings)}{Style.RESET_ALL}  "
+          f"(filtered {fp} false positive(s))")
+    print(f"  {Fore.RED}High    : {high}{Style.RESET_ALL}")
+    print(f"  {Fore.YELLOW}Medium  : {medium}{Style.RESET_ALL}")
+    print(f"  {Fore.CYAN}Low     : {low}{Style.RESET_ALL}")
+    _divider("═")
+    print()

permi-0.1.1/cli/main.py

@@ -0,0 +1,133 @@
+# cli/main.py
+import json
+import sys
+import click
+from colorama import Fore, Style, init
+
+init(autoreset=True)
+
+from cli.formatter import print_banner, print_results_human, print_summary
+from scanner.scan import scan
+
+
+@click.group()
+def cli():
+    """
+    Permi — AI-powered vulnerability scanner.
+
+    Scans code for vulnerabilities and uses AI to filter out false
+    positives so you only see findings that actually matter.
+
+    Built in Nigeria. For Nigeria. Then for the world.
+    """
+    pass
+
+
+@cli.command()
+@click.option("--path", "-p", required=True,
+              help="Local directory path or GitHub URL to scan.")
+@click.option("--output", "-o",
+              type=click.Choice(["human", "json"], case_sensitive=False),
+              default="human", show_default=True,
+              help="Output format.")
+@click.option("--severity", "-s",
+              type=click.Choice(["high", "medium", "low", "all"], case_sensitive=False),
+              default="all", show_default=True,
+              help="Minimum severity level to display.")
+@click.option("--offline", is_flag=True, default=False,
+              help="Skip AI filter and show all raw findings.")
+@click.option("--project", default=None,
+              help="Project name to store in the database.")
+def scan_cmd(path, output, severity, offline, project):
+    """
+    Scan a local directory or GitHub repo for vulnerabilities.
+
+    Permi detects SQL injection, XSS, hardcoded secrets, insecure
+    practices, and USSD vulnerabilities. An AI filter then removes
+    false positives so only real issues are shown.
+
+    \b
+    EXAMPLES
+
+      Scan a local project:
+        permi scan --path ./myapp
+
+      Scan a GitHub repo:
+        permi scan --path https://github.com/user/repo
+
+      High severity only:
+        permi scan --path ./myapp --severity high
+
+      Export as JSON for CI/CD:
+        permi scan --path ./myapp --output json
+
+      Skip AI filter (no API key needed):
+        permi scan --path ./myapp --offline
+
+      Name your project in the database:
+        permi scan --path ./myapp --project my-api
+
+    \b
+    SEVERITY LEVELS
+
+      high    — SQL injection, hardcoded secrets, eval(), XSS, SSL disabled
+      medium  — debug mode, USSD input issues
+      low     — informational findings
+      all     — everything (default)
+
+    \b
+    EXIT CODES
+
+      0   No high severity findings
+      1   At least one high severity finding (useful for CI/CD pipelines)
+    """
+    if output == "human":
+        print_banner()
+
+    try:
+        # Run the full scan pipeline
+        findings, raw_count = scan(
+            path=path,
+            project_name=project,
+            offline=offline,
+        )
+
+        # ── Severity filter ───────────────────────────────────────────────────
+        order = {"high": 1, "medium": 2, "low": 3}
+
+        if severity != "all":
+            level = order[severity]
+            findings = [
+                f for f in findings
+                if isinstance(f, dict) and order.get(f.get("severity", "low"), 99) <= level
+            ]
+
+        # ── Output ────────────────────────────────────────────────────────────
+        if output == "json":
+            clean = [
+                {k: v for k, v in f.items() if v is not None}
+                for f in findings
+                if isinstance(f, dict)
+            ]
+            click.echo(json.dumps(clean, indent=2))
+
+        else:
+            print_results_human(findings)
+            print_summary(findings, raw_count=raw_count)
+
+        # Exit code 1 if any high severity findings — used by GitHub Action
+        if any(f.get("severity") == "high" for f in findings if isinstance(f, dict)):
+            sys.exit(1)
+
+    except FileNotFoundError as e:
+        click.echo(Fore.RED + f"\n[Error] {e}\n")
+        sys.exit(1)
+    except NotADirectoryError as e:
+        click.echo(Fore.RED + f"\n[Error] {e}\n")
+        sys.exit(1)
+    except Exception as e:
+        click.echo(Fore.RED + f"\n[Unexpected error] {e}\n")
+        sys.exit(1)
+
+
+cli.add_command(scan_cmd, name="scan")

permi-0.1.1/db/database.py

@@ -0,0 +1,95 @@
+# db/database.py
+# Handles all database creation and connection logic.
+# The database file (permi.db) is created automatically in the
+# project root the first time this module is imported.
+
+import sqlite3
+from pathlib import Path
+
+# The database lives in the project root folder
+DB_PATH = Path(__file__).parent.parent / "permi.db"
+
+
+def get_connection() -> sqlite3.Connection:
+    """
+    Open and return a connection to the local SQLite database.
+    Sets row_factory so rows behave like dictionaries — you can
+    access columns by name (row['severity']) instead of index (row[2]).
+    """
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")  # enforce relationships
+    return conn
+
+
+def init_db() -> None:
+    """
+    Create all tables if they don't already exist.
+    Safe to call every time the app starts — won't overwrite existing data.
+    """
+    conn = get_connection()
+
+    with conn:
+
+        # ── projects ──────────────────────────────────────────────────────────
+        # One row per codebase you want to scan repeatedly.
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS projects (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                name        TEXT    NOT NULL,
+                path        TEXT    NOT NULL,
+                created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
+                last_scan   TEXT
+            )
+        """)
+
+        # ── scan_results ──────────────────────────────────────────────────────
+        # One row per scan run. Links back to the project that was scanned.
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS scan_results (
+                id            INTEGER PRIMARY KEY AUTOINCREMENT,
+                project_id    INTEGER NOT NULL REFERENCES projects(id),
+                started_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+                finished_at   TEXT,
+                total_files   INTEGER DEFAULT 0,
+                total_findings INTEGER DEFAULT 0,
+                status        TEXT    DEFAULT 'running'
+            )
+        """)
+
+        # ── findings ──────────────────────────────────────────────────────────
+        # One row per vulnerability found in a scan.
+        # ai_verdict and ai_explanation are NULL until Phase 1 fills them in.
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS findings (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                scan_id         INTEGER NOT NULL REFERENCES scan_results(id),
+                rule_id         TEXT    NOT NULL,
+                rule_name       TEXT    NOT NULL,
+                severity        TEXT    NOT NULL,
+                description     TEXT,
+                file            TEXT    NOT NULL,
+                line_number     INTEGER NOT NULL,
+                line_content    TEXT,
+                ai_verdict      TEXT,
+                ai_explanation  TEXT,
+                fix_suggestion  TEXT,
+                created_at      TEXT    NOT NULL DEFAULT (datetime('now'))
+            )
+        """)
+
+        # ── feedback ──────────────────────────────────────────────────────────
+        # Stores manual corrections from the user.
+        # 'confirmed' = real vulnerability, 'false_positive' = not a real issue.
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS feedback (
+                id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                finding_id   INTEGER NOT NULL REFERENCES findings(id),
+                verdict      TEXT    NOT NULL CHECK(verdict IN ('confirmed', 'false_positive')),
+                note         TEXT,
+                created_at   TEXT    NOT NULL DEFAULT (datetime('now'))
+            )
+        """)
+
+    conn.close()
+    print(f"Database ready: {DB_PATH}")

permi-0.1.1/db/queries.py

@@ -0,0 +1,112 @@
+# db/queries.py
+# All database read/write functions used by the scanner.
+# Every function takes a connection as its first argument
+# so the caller controls when to open and close it.
+
+from datetime import datetime
+
+
+def create_project(conn, name: str, path: str) -> int:
+    """
+    Insert a new project and return its ID.
+    If a project with the same path already exists, return its ID instead.
+    """
+    existing = conn.execute(
+        "SELECT id FROM projects WHERE path = ?", (path,)
+    ).fetchone()
+
+    if existing:
+        return existing["id"]
+
+    cursor = conn.execute(
+        "INSERT INTO projects (name, path) VALUES (?, ?)",
+        (name, path)
+    )
+    conn.commit()
+    return cursor.lastrowid
+
+
+def start_scan(conn, project_id: int) -> int:
+    """
+    Create a new scan_results row with status 'running'.
+    Returns the scan ID.
+    """
+    cursor = conn.execute(
+        "INSERT INTO scan_results (project_id, status) VALUES (?, 'running')",
+        (project_id,)
+    )
+    conn.commit()
+    return cursor.lastrowid
+
+
+def finish_scan(conn, scan_id: int, total_files: int, total_findings: int) -> None:
+    """
+    Mark a scan as completed and record the final counts.
+    """
+    conn.execute("""
+        UPDATE scan_results
+        SET status          = 'completed',
+            finished_at     = datetime('now'),
+            total_files     = ?,
+            total_findings  = ?
+        WHERE id = ?
+    """, (total_files, total_findings, scan_id))
+
+    conn.commit()
+
+
+def save_finding(conn, scan_id: int, finding: dict) -> int:
+    """
+    Insert one finding into the findings table.
+    Returns the new finding's ID.
+    """
+    cursor = conn.execute("""
+        INSERT INTO findings (
+            scan_id, rule_id, rule_name, severity, description,
+            file, line_number, line_content, ai_verdict, ai_explanation
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    """, (
+        scan_id,
+        finding["rule_id"],
+        finding["rule_name"],
+        finding["severity"],
+        finding["description"],
+        finding["file"],
+        finding["line_number"],
+        finding["line_content"],
+        finding.get("ai_verdict"),
+        finding.get("ai_explanation"),
+    ))
+    conn.commit()
+    return cursor.lastrowid
+
+
+def get_findings_for_scan(conn, scan_id: int) -> list:
+    """
+    Retrieve all findings for a given scan, ordered by severity then file.
+    """
+    rows = conn.execute("""
+        SELECT * FROM findings
+        WHERE scan_id = ?
+        ORDER BY
+            CASE severity
+                WHEN 'high'   THEN 1
+                WHEN 'medium' THEN 2
+                WHEN 'low'    THEN 3
+                ELSE 4
+            END,
+            file, line_number
+    """, (scan_id,)).fetchall()
+
+    return [dict(row) for row in rows]
+
+
+def update_last_scan(conn, project_id: int) -> None:
+    """
+    Update the last_scan timestamp on a project after a scan completes.
+    """
+    conn.execute(
+        "UPDATE projects SET last_scan = datetime('now') WHERE id = ?",
+        (project_id,)
+    )
+    conn.commit()

permi-0.1.1/permi.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: permi
+Version: 0.1.1
+Summary: AI-powered vulnerability scanner for Nigerian developers
+Requires-Python: >=3.9
+Requires-Dist: python-dotenv
+Requires-Dist: colorama
+Requires-Dist: click
+Requires-Dist: requests

permi-0.1.1/permi.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+ai_filter/__init__.py
+ai_filter/filter.py
+ai_filter/llm_client.py
+cli/__init__.py
+cli/formatter.py
+cli/main.py
+db/__init__.py
+db/database.py
+db/queries.py
+permi.egg-info/PKG-INFO
+permi.egg-info/SOURCES.txt
+permi.egg-info/dependency_links.txt
+permi.egg-info/entry_points.txt
+permi.egg-info/requires.txt
+permi.egg-info/top_level.txt
+scanner/__init__.py
+scanner/engine.py
+scanner/rules.py
+scanner/scan.py

permi-0.1.1/permi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

permi-0.1.1/permi.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+permi = cli.main:cli

permi-0.1.1/permi.egg-info/requires.txt

@@ -0,0 +1,4 @@
+python-dotenv
+colorama
+click
+requests

permi-0.1.1/permi.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+ai_filter
+cli
+db
+scanner

permi-0.1.1/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "permi"
+version = "0.1.1"
+description = "AI-powered vulnerability scanner for Nigerian developers"
+requires-python = ">=3.9"
+dependencies = [
+    "python-dotenv",
+    "colorama",
+    "click",
+    "requests",
+]
+
+[project.scripts]
+permi = "cli.main:cli"
+
+[tool.setuptools.packages.find]
+include = ["scanner*", "ai_filter*", "cli*", "db*"]

permi-0.1.1/scanner/engine.py

@@ -0,0 +1,68 @@
+# scanner/engine.py
+# The engine takes a file path, reads it line by line,
+# and tests every line against every rule in RULES.
+# Returns a list of finding dictionaries.
+
+from pathlib import Path
+from .rules import RULES, SCANNABLE_EXTENSIONS, SKIP_DIRS
+
+
+def scan_file(file_path: Path) -> list[dict]:
+    """
+    Scan a single file against all rules.
+    Returns a list of findings (may be empty).
+    """
+    findings = []
+
+    # Skip files with extensions we don't handle
+    if file_path.suffix.lower() not in SCANNABLE_EXTENSIONS:
+        return findings
+
+    try:
+        content = file_path.read_text(encoding="utf-8", errors="ignore")
+    except Exception:
+        # If the file can't be read for any reason, skip it silently
+        return findings
+
+    lines = content.splitlines()
+
+    for line_number, line in enumerate(lines, start=1):
+        for rule in RULES:
+            if rule["pattern"].search(line):
+                findings.append({
+                    "rule_id":     rule["id"],
+                    "rule_name":   rule["name"],
+                    "severity":    rule["severity"],
+                    "description": rule["description"],
+                    "file":        str(file_path),
+                    "line_number": line_number,
+                    "line_content": line.strip(),
+                    "ai_verdict":  None,   # filled in Phase 1
+                    "ai_explanation": None, # filled in Phase 1
+                })
+
+    return findings
+
+
+def scan_directory(directory: Path) -> list[dict]:
+    """
+    Recursively walk a directory, scan every eligible file,
+    and return all findings combined.
+    """
+    all_findings = []
+    directory = Path(directory).resolve()
+
+    for file_path in directory.rglob("*"):
+
+        # Skip any path that passes through a blocked directory
+        if any(skip in file_path.parts for skip in SKIP_DIRS):
+            continue
+
+        # Skip directories themselves — only process files
+        if not file_path.is_file():
+            continue
+
+        findings = scan_file(file_path)
+        all_findings.extend(findings)
+
+    return all_findings

permi-0.1.1/scanner/rules.py

@@ -0,0 +1,268 @@
+# scanner/rules.py
+# Each rule has: id, name, pattern (regex), severity, description
+# Patterns are intentionally broad — the AI filter in Phase 1 will
+# remove false positives. Better to over-catch than under-catch here.
+
+import re
+
+RULES = [
+
+    # ── SQL INJECTION ─────────────────────────────────────────────────────────
+
+    {
+        "id": "SQL001",
+        "name": "SQL Injection — string concatenation",
+        "severity": "high",
+        "description": (
+            "Raw string concatenation used to build a SQL query. "
+            "An attacker can inject arbitrary SQL through user input."
+        ),
+        "pattern": re.compile(
+            r'(execute|query|cursor\.execute)\s*\(\s*["\'].*\+',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "SQL002",
+        "name": "SQL Injection — f-string or format() in query",
+        "severity": "high",
+        "description": (
+            "An f-string or .format() call is used inside a SQL query. "
+            "User-controlled variables embedded this way are injectable."
+        ),
+        "pattern": re.compile(
+            r'(execute|query|cursor\.execute)\s*\(\s*f["\']',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "SQL003",
+        "name": "SQL Injection — % formatting in query",
+        "severity": "high",
+        "description": (
+            "% string formatting is used to build a SQL query. "
+            "This is a classic injection vector."
+        ),
+        "pattern": re.compile(
+            r'(execute|query)\s*\(\s*["\'].*%\s*[(\w]',
+            re.IGNORECASE
+        ),
+    },
+
+    # ── CROSS-SITE SCRIPTING (XSS) ────────────────────────────────────────────
+
+    {
+        "id": "XSS001",
+        "name": "XSS — innerHTML assignment",
+        "severity": "high",
+        "description": (
+            "innerHTML is set dynamically. If any part of the value comes "
+            "from user input, this is a direct XSS vector."
+        ),
+        "pattern": re.compile(
+            r'\.innerHTML\s*=',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "XSS002",
+        "name": "XSS — document.write with variable",
+        "severity": "high",
+        "description": (
+            "document.write() is called with a variable. "
+            "Writing user-controlled content to the page enables XSS."
+        ),
+        "pattern": re.compile(
+            r'document\.write\s*\(\s*\w',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "XSS003",
+        "name": "XSS — Flask render without escape (Jinja2 | safe filter)",
+        "severity": "medium",
+        "description": (
+            "The Jinja2 |safe filter disables auto-escaping. "
+            "If the variable contains user input, this enables XSS."
+        ),
+        "pattern": re.compile(
+            r'\|\s*safe',
+            re.IGNORECASE
+        ),
+    },
+
+    # ── HARDCODED SECRETS ─────────────────────────────────────────────────────
+
+    {
+        "id": "SEC001",
+        "name": "Hardcoded secret — generic password or key assignment",
+        "severity": "high",
+        "description": (
+            "A variable named password, secret, api_key, or token is "
+            "assigned a string literal. Hardcoded credentials are a "
+            "critical exposure risk if the code is shared or pushed."
+        ),
+        "pattern": re.compile(
+            r'(password|passwd|secret|api_key|apikey|token|auth_key)'
+            r'\s*=\s*["\'][^"\']{4,}["\']',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "SEC002",
+        "name": "Hardcoded secret — AWS key pattern",
+        "severity": "high",
+        "description": (
+            "A string matching the format of an AWS Access Key ID was found. "
+            "Exposed AWS keys can lead to full account compromise."
+        ),
+        "pattern": re.compile(
+            r'AKIA[0-9A-Z]{16}',
+        ),
+    },
+    {
+        "id": "SEC003",
+        "name": "Hardcoded secret — private key header",
+        "severity": "high",
+        "description": (
+            "A PEM private key header was found in the source code. "
+            "Private keys must never be committed to a repository."
+        ),
+        "pattern": re.compile(
+            r'-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----',
+        ),
+    },
+    {
+        "id": "SEC004",
+        "name": "Hardcoded secret — Paystack or Flutterwave secret key",
+        "severity": "high",
+        "description": (
+            "A Paystack or Flutterwave secret key pattern was found. "
+            "Exposed payment gateway keys allow fraudulent transactions."
+        ),
+        "pattern": re.compile(
+            r'(sk_live_|sk_test_)[a-zA-Z0-9]{20,}',
+        ),
+    },
+
+    # ── USSD / NIGERIAN-SPECIFIC ──────────────────────────────────────────────
+
+    {
+        "id": "USSD001",
+        "name": "USSD — missing input validation on sessionId or phoneNumber",
+        "severity": "medium",
+        "description": (
+            "A USSD handler accesses sessionId or phoneNumber from the "
+            "request without any visible validation. Unvalidated USSD "
+            "inputs can be manipulated to hijack sessions or spoof callers."
+        ),
+        "pattern": re.compile(
+            r'request\.(get|form|json|args)\s*[\.\[]\s*'
+            r'["\']?(sessionId|phoneNumber|serviceCode)["\']?',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "USSD002",
+        "name": "USSD — wildcard or open-ended serviceCode handling",
+        "severity": "medium",
+        "description": (
+            "A USSD serviceCode is compared to a wildcard or catch-all "
+            "value. This may allow unintended service codes to trigger "
+            "application logic."
+        ),
+        "pattern": re.compile(
+            r'serviceCode\s*[=!]=\s*["\'][*\?]["\']',
+            re.IGNORECASE
+        ),
+    },
+
+    # ── INSECURE PRACTICES ────────────────────────────────────────────────────
+
+    {
+        "id": "INS001",
+        "name": "Insecure — debug mode enabled in production",
+        "severity": "medium",
+        "description": (
+            "debug=True is set, likely in a Flask or Django app. "
+            "Debug mode exposes stack traces and an interactive console "
+            "to anyone who triggers an error."
+        ),
+        "pattern": re.compile(
+            r'debug\s*=\s*True',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "INS002",
+        "name": "Insecure — SSL/TLS verification disabled",
+        "severity": "high",
+        "description": (
+            "verify=False is passed to a requests call. "
+            "This disables certificate validation and exposes the app "
+            "to man-in-the-middle attacks."
+        ),
+        "pattern": re.compile(
+            r'requests\.\w+\(.*verify\s*=\s*False',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "INS003",
+        "name": "Insecure — use of eval() on external input",
+        "severity": "high",
+        "description": (
+            "eval() is called with a variable argument. If the variable "
+            "contains user-supplied data, this allows arbitrary code execution."
+        ),
+        "pattern": re.compile(
+            r'eval\s*\(\s*\w',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "INS004",
+        "name": "Insecure — use of exec() on external input",
+        "severity": "high",
+        "description": (
+            "exec() is called with a variable argument — same risk as eval()."
+        ),
+        "pattern": re.compile(
+            r'exec\s*\(\s*\w',
+            re.IGNORECASE
+        ),
+    },
+    {
+        "id": "INS005",
+        "name": "Insecure — pickle.loads() on untrusted data",
+        "severity": "high",
+        "description": (
+            "pickle.loads() deserializes data. If the data comes from "
+            "an untrusted source (network, user upload), this allows "
+            "arbitrary code execution."
+        ),
+        "pattern": re.compile(
+            r'pickle\.loads\s*\(',
+            re.IGNORECASE
+        ),
+    },
+]
+
+# ── FILE EXTENSIONS TO SCAN ───────────────────────────────────────────────────
+# Permi only reads these file types. Binary files, images, and lockfiles
+# are skipped automatically.
+
+SCANNABLE_EXTENSIONS = {
+    ".py", ".js", ".ts", ".jsx", ".tsx",
+    ".html", ".htm", ".php", ".java",
+    ".env", ".yml", ".yaml", ".json",
+}
+
+# ── DIRECTORIES TO SKIP ───────────────────────────────────────────────────────
+# These folders are never scanned — they contain dependencies or build
+# artifacts, not your actual code.
+
+SKIP_DIRS = {
+    "node_modules", "venv", ".venv", "__pycache__",
+    ".git", "dist", "build", ".next", "target",
+}

permi-0.1.1/scanner/scan.py

@@ -0,0 +1,123 @@
+# scanner/scan.py
+# Full scan pipeline — engine + AI filter combined.
+# Supports local directories and GitHub URLs.
+
+import tempfile
+import subprocess
+from pathlib import Path
+
+from scanner.engine import scan_directory as run_engine
+from ai_filter.filter import run_filter
+from db.database import init_db, get_connection
+from db.queries import (
+    create_project,
+    start_scan,
+    save_finding,
+    finish_scan,
+    update_last_scan,
+)
+
+
+def _is_github_url(path: str) -> bool:
+    """Return True if the path looks like a GitHub URL."""
+    p = path.strip().strip('"').strip("'")
+    return p.startswith("https://github.com/") or p.startswith("git@github.com:")
+
+
+def _clone_repo(url: str, target_dir: Path) -> None:
+    """
+    Clone a GitHub repo into target_dir.
+    Raises RuntimeError if git is not installed or the clone fails.
+    """
+    print(f"[Permi] Cloning  : {url}")
+    result = subprocess.run(
+        ["git", "clone", "--depth", "1", url, str(target_dir)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"git clone failed:\n{result.stderr.strip()}")
+    print(f"[Permi] Cloned to: {target_dir}\n")
+
+
+def scan(
+    path: str,
+    project_name: str = None,
+    offline: bool = False,
+) -> tuple[list[dict], int]:
+    """
+    Full scan pipeline.
+
+    Returns:
+        (real_findings, raw_count)
+        real_findings — findings the AI marked as REAL
+        raw_count     — total before AI filtering (for accurate summary)
+    """
+    # ── Normalise path ────────────────────────────────────────────────────────
+    path = path.strip().strip('"').strip("'")
+    is_github = _is_github_url(path)
+
+    # ── GitHub URL — clone to a temp directory ────────────────────────────────
+    if is_github:
+        tmp = tempfile.TemporaryDirectory()
+        target = Path(tmp.name) / "repo"
+        _clone_repo(path, target)
+        default_name = path.rstrip("/").split("/")[-1].replace(".git", "")
+    else:
+        tmp = None
+        target = Path(path).resolve()
+        if not target.exists():
+            raise FileNotFoundError(f"Path does not exist: {target}")
+        if not target.is_dir():
+            raise NotADirectoryError(f"Path is not a directory: {target}")
+        default_name = target.name
+
+    name = project_name or default_name
+
+    # ── Init DB and create/find project ───────────────────────────────────────
+    init_db()
+    conn = get_connection()
+    project_id = create_project(conn, name=name, path=str(target))
+
+    # ── Start scan record ─────────────────────────────────────────────────────
+    scan_id = start_scan(conn, project_id)
+
+    print(f"[Permi] Scanning : {target}")
+    print(f"[Permi] Project  : {name}  (id={project_id})")
+    print(f"[Permi] Scan     : id={scan_id}\n")
+
+    # ── Run the engine ────────────────────────────────────────────────────────
+    raw_findings = run_engine(target)
+    raw_count    = len(raw_findings)
+    scanned_files = len({f["file"] for f in raw_findings}) if raw_findings else 0
+
+    print(f"[Permi] Engine found {raw_count} raw finding(s) "
+          f"across {scanned_files} file(s)\n")
+
+    # ── Save every raw finding to DB ──────────────────────────────────────────
+    for finding in raw_findings:
+        finding_id = save_finding(conn, scan_id, finding)
+        finding["id"] = finding_id
+
+    conn.close()
+
+    # ── Run AI filter ─────────────────────────────────────────────────────────
+    real_findings = run_filter(raw_findings, offline=offline)
+
+    # ── Finish scan record ────────────────────────────────────────────────────
+    conn = get_connection()
+    finish_scan(
+        conn,
+        scan_id=scan_id,
+        total_files=scanned_files,
+        total_findings=len(real_findings),
+    )
+    update_last_scan(conn, project_id)
+    conn.close()
+
+    # ── Clean up temp clone ───────────────────────────────────────────────────
+    if tmp:
+        tmp.cleanup()
+        print("[Permi] Temp clone deleted.\n")
+
+    return real_findings, raw_count

permi-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+